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 submodule update --init --recursive— Initialize submodules in your local repo (yes, inkscape has submodules since the 1.0 release)
git pull --recurse-submodules— Updates local repository including all submodules
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 pull --rebase --autostash— Same as above, but automatically stashes your local changes before pulling.
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 email@example.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|
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 commit --local
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|
|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|
- 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
- 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 commitcommand. 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-nameand 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
git clone https://gitlab.com/inkscape/inkscape.git will download all commits from all branches (currently ~ 1.5 GB).
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.