Working with Git

This page contains an introduction to the Git distributed version control system. For now, it is mainly useful to Bazaar users, but will be updated with general Git information over time.

Git commands for the novice

• git status — Returns status of your local repository.
• git pull — Updates local repository from remote repository.
• git pull --recurse-submodules — Updates local repository including all submodules (yes, inkscape has submodules since the 1.0 release)
• git pull --rebase — Updates local repository moving any local commits after any pulled commits. Good for keeping things in order when you push your commits.
• git add — Add files to the list that will be committed.
• git commit — Commit your changes locally (after adding).
• git push — Push your locally committed changes to remote repository.
• git remote -v — Shows remote repository (should be: origin git@gitlab.com:inkscape/inkscape.git).
• git checkout filename — Reverts 'filename' to repository version.
• git stash — Move changes in directory out of the way (in order to 'pull' in changes).
• git stash pop — Restore changes stashed by 'git stash'.
• git diff xxxxx yyyyy — Difference between xxxxx and yyyyy.
• git diff HEAD^ — Examine last commit.
• git diff HEAD^^ HEAD^ — Examine second to last commit.

Cheat sheet for Bazaar users

Historical reference. We no longer use bazaar.

Bazaar command	Git command
bzr branch branch-url	git clone repository-url directory cd directory git checkout branch-name
bzr checkout lp:project-name	not supported
bzr update	not supported
bzr pull	git pull
bzr add file	git add file
bzr diff	git diff HEAD
bzr revert	git reset --hard
bzr revert file -r revision	git checkout commit -- file
bzr uncommit	git reset HEAD^
bzr uncommit ...some changes... bzr commit --local	...some changes... git commit -a --amend
bzr push location	git remote add remote-name location git push remote-name branch-name
bzr commit --local	git commit -a
bzr commit	git commit -a git push
bzr log -c 10	git log -n 10
bzr switch branch-url	git checkout branch-name
bzr switch -b branch-url	git checkout -b branch-name
bzr merge branch-url	git merge branch-name
bzr shelve --all	git stash
bzr unshelve change-id	git stash pop

Other cheatsheets

• git - the simple guide - short and sweet, enough to get started

Differences from Bazaar

Here are the most important differences between Bazaar and Git:

• Bazaar revisions are identified by sequential numbers. Git revisions (called commits in the documentation) are identified by cryptographic hashes which are strings of 40 hexadecimal numbers, though it is possible to also refer to them by a sequential number since the last tag (see git describe).
• Bazaar is branch-oriented, while Git is repository- and commit-oriented. Repositories in Bazaar are storage locations for potentially multiple branches. Repositories in Git are collections of commits, and branches are just pointers to particular commits that are updated after each git commit command. Cloning a Git repository by default retrieves all of its commits and branches.
• In Bazaar, you conceptually submit your work to only one place - the push branch. You can change this place at any time, but Bazaar remembers only one value for you. In Git, you can configure many remote repositories and work with code from multiple sources using a single working tree.
• By default, each branch in Bazaar has a separate working tree, while all branches in the same Git repository share the same working tree. It's possible to make Bazaar work in the latter mode as well, but it's not very well supported.

In Bazaar, if you want to try out someone else's code, you need to create a new checkout of their branch or use bzr switch. In Git, what you do depends on where the code is located.

• If the code to try out is in a branch in the project's main repository, you update the repository (git fetch) and then check out the branch (git checkout origin/branch-to-try-out). This creates a local branch called branch-to-try-out. (You can use a different name as well.)
• If the code is in a different repository, you first add it as a remote repository with git remote add remote-name repository-url, fetch it with git fetch remote-name and check out the relevant branch with git checkout remote-name/branch-to-try-out.

Another difference is that in Git, you cannot directly make changes to remote branches - you must to use git push and git pull. Therefore, the Subversion-like checkout mode known from Bazaar is unsupported.

Ideas for an efficient workflow

Here are some ideas on how you can increase your efficiency when working with git and/or achieve a workflow similar to what you were used to with Bazaar

Download single branches or shallow clones

By default git clone https://gitlab.com/inkscape/inkscape.git will download all commits from all branches (currently ~ 1.5 GB).

Single branches

If you're only interested in a single branch use

 git clone --single-branch [--branch <name>]

which downloads only the files and history for the specified branch. Omit --branch to download trunk / master (currently ~ 900 MB).

Shallow clones (no history)

If you're not interested in commit history and only want to download the latest files use

  git clone --depth 1 [--branch <name>]

which downloads only the latest revision of the specified branch. Omit --branch to download the latest revision of trunk / master (currently ~ 30 MB).

Checkout multiple branches into different folders

As git branches are all stored in the same repository you'll only have one "working tree" (the set of files making up the branch) in the beginning and switching to another branch will modify all files on disk. To have multiple branches (say trunk and 0.92.x) checked out at the same time you can obviously clone the repository multiple times. However it's much more elegant to use the git-worktree command which links a new working tree to your repository that can be on any branch you want. For example

 git worktree add 0.92.x_files 0.92.x

will create a working tree for the 0.92.x branch in the folder "0.92.x_files". You can then use this new working tree exactly like you'd use the main working tree. (You'll need to run git checkout 0.92.x to set the branch.)

Use ccache to speed up compilation after switching branches

As git does not preserve file modification times you'd have to do a lot of recompiling whenever switching branches (unless you use the method described above for all your branches). This can be avoided by using ccache. There are many ways to use ccache (search the Internet!). A convenient way when using CMake are the CMAKE_<LANG>_COMPILER_LAUNCHER variables (needs CMake 3.4 or later).

Just run CMake with the additional arguments -DCMAKE_C_COMPILER_LAUNCHER="ccache" -DCMAKE_CXX_COMPILER_LAUNCHER="ccache" or use any other way you prefer to set the two variables accordingly.