Getting the most out of Git in GNOME
Contents
Introduction
Git is a powerful method of allowing many developers to work on the same source code. It is used extensively within the GNOME project and often proves to be the first hurdle for new developers that are attracted to the GNOME project.
Each developer clones a copy of the repository of the source code from Git and then is able to work on their own personal clone separately from other developers. When they have made changes, they commit them locally. After they are satisfied with their commits they push them back to the Git repository. This way a series of commits can be prepared and tested locally and then pushed as a single event.
With git everybody has all the tools available and can do whatever they want to do with their local copy. Moreover, almost all operations are local, so the operations are fast, and can be done without connection to the original repository.
The GNOME project has also set up online browsing of its Git repository.
If you would like to track the changes that occur in various GNOME Git projects, subscribe to the commits-list mailing list, a high volume, read-only list that receives mail every time somebody checks something into the repository. You can filter mail from this list by the title of the projects you are interested in.
Setting up Git
The first thing you should do is configure git to know who you are:
git config --global user.name "Rupert Monkey" git config --global user.email rupert@example.com
You can omit --global to change it for a single checked-out repository.
If you like pretty colors in your terminal output, you can enable those as well:
git config --global color.ui auto
or
git config --global color.diff auto git config --global color.status auto git config --global color.branch auto
If after turning on pretty colors, you instead see garbage in your output, you might need to add this line to your ~/.bashrc
export LESS=-R
Getting Code
Anonymous Access
To clone all the history and branches of a project into a subfolder of the current directory on your local harddrive, from a shell:
git clone https://gitlab.gnome.org/GNOME/[project].git
The new subfolder will be named after the project.
You should replace [project] with the name of the project you want. If you want the check-out to be put in a folder that is not the same as the project name, specify your own folder name as a second argument to git clone.
Developer Access
GitLab
To clone a project in GNOME GitLab, run this command:
git clone git@ssh.gitlab.gnome.org:GNOME/[project].git
Refer to #Convert_fork for steps to change the URI of the repository if your checkout predates the migration.
If you have a GNOME Gitlab account already and after you have set up your GNOME_GITLAB_PERSONAL_ACCESS_TOKEN environment variable, you can use their SSH key to authenticate themselves to the Git server so that they may also push changes back to the Git repositories. They use a slightly different URL to clone and deal with Git projects:
git clone ssh://git@ssh.gitlab.gnome.org/GNOME/[project].git
Note
You will need to log in at least once using your LDAP account on the website and wait for an email, informing you of gained developer privileges, which could take up to an hour. Your SSH key will be imported from account.gnome.org automatically.
Convert fork
Suppose you've been contributing patches to GTK+ and now you've been given developer access, you don't need to git clone again and waste precious time, just change the origin URI of your fork, like so:
git remote set-url origin git@ssh.gitlab.gnome.org:GNOME/[project].git
git.gnome.org
The previously used git.gnome.org service has been discontinued as of August 23rd, 2018.
Submodules
Some gnome modules may contain git submodules inside it (eg. libgd inside nautilus), in that case you need to add --recursive to clone command so to retrieve code for any existent submodule, like so:
git clone --recursive git@ssh.gitlab.gnome.org:GNOME/[project].git
For already cloned modules, that have added new submodules afterwards, you can just execute the following command at the root of the relevant git module to retrieve code for any new submodule:
git submodule update --init --recursive
Common Files
When the clone has been completed, you will start to notice that many projects in Git GNOME contain similar files:
- .git: This directory is present in the root directory of a given project. It contains information about version numbers, where the source code came from, etc.. You can ignore it for all purposes, but you should not delete it.
- autogen.sh: This is a wrapper script around gettextize, intltoolize, libtoolize, aclocal, autoheader, automake and autoconf which you use to start building the project. For example
./autogen.sh --prefix=/usr/local will start the build process checking your system, generating all the necessary Makefiles before you are ready to type 'make' and 'make install'.
- README: This generally gives information about the Git project in terms of project requirements, where to report bugs etc..
- HACKING: This file usually specifies the rules [if any] for development in the project.
- [project].doap: This file lists the people who are responsible for the day to day maintenance of the project. Generally these are the people you should send patches to. It also lists some other metadata for the project, such as a description, homepage, mailing list, etc..
- MAINTAINERS: This file lists the maintainers, in a similar way to the DOAP file. It is no longer required to have a MAINTAINERS file, but a lot of projects still use them.
Using Branches
Git allows you to isolate changes onto a separate line of development, known as a branch. Quite often in GNOME, there are stable and unstable branches of development for a given project - as a result, the main branch [also known as 'master'] may not be suitable for your needs. Stable branches in GNOME Git are generally a mixture of lowercase alphabetic and numeric characters separated by dashes ie. of the form:
[project]-[MAJOR]-[MINOR]
where major, minor are version numbers. For example:
gnome-2-0 gtk-2-0
In Git, branches and tags are simply references to a commit. For a list of the available local branches for a given project you can use:
git branch
Listing Branches
For a list of the available remote branches for a given project you can use:
git branch -r
Checking Out a Branch
You can check out an existing local branch using the following command:
git checkout -b [branch name] origin/[branch name]
That specifies a local branch that will be created, to track the remote (origin/) branch. You must use a local branch, and you must give it the same name as the remote branch, or things will get very complicated when you try to push your commits later. If you do it as we show here, then a simple "git push" will work.
Note that before switching branches your working tree must be clean. If it is not, you can stash your changes (explained below) or commit them temporarily.
The following example will check out gnome-utils master and then check out the 'gnome-2-26' branch:
$ git clone git@ssh.gitlab.gnome.org:GNOME/gnome-utils.git $ cd gnome-utils $ git checkout -b gnome-2-26 origin/gnome-2-26
Creating Branches
See #Branching about creating remote branches at gitlab.gnome.org.
Local Branches
A local branch is a local snapshot of the repository branched so you can do work without changing the master branch. This makes it possible for you to work on several issues at the same time in different branches. A useful feature in cases where something urgent comes up while you are working on something else. Creating a local branch means that the branch is only available to you. The local branch is not created remotely.
You can create a local branch using:
git branch my-branch
You can create a local branch tracking a remote branch by using:
git branch my-branch origin/my-branch
You can create a new branch and check out it at the same time with:
git checkout -b my-branch origin/my-branch
- If you have a version of git greater than 1.6.1 you can also use:
git checkout --track origin/my-branch
which will create a local branch called my-branch tracking the origin/my-branch remote branch.
- If you already created a local branch you can switch easily between them using:
# Switch to my-branch git checkout my-branch # Switch back to master git checkout master
Using Tags
Git tags are used to mark releases and are typically named in the form of [MAJOR].[MINOR].[MICRO], where MAJOR, MINOR and MICRO are version numbers, for example:
3.26.0 3.27.92
Note
Accidents happen and a maintainer may need to make a fix-up release, which will typically result in adding a new component to the version, e.g. 3.27.92.1.
You may notice different conventions used in different projects as well:
v[MAJOR].[MINOR].[MICRO]
v3.26.0 v3.27.92
[PROJECT]_[MAJOR]_[MINOR]_[MICRO] (older tags in older projects, typically ones that survived a transition from SVN to Git)
GTK_2_0_6 GNOME_UTILS_2_0_2
Listing Tags
For a list of the available tags for a given project:
git tag -l
As all the data is local you can examine the history very fast. To see the history up to the current revision:
git log -p gitk
where the '-p' is to see the patch and the last one is a graphical viewer.
Checking Out a Tag
You can check out a tag with the same command as you checkout a branch:
git checkout [tag name]
The following examples will check out the gnome-utils 2.0.2 tag and the 1.8.0 from Banshee respectively:
$ git clone git@ssh.gitlab.gnome.org:GNOME/gnome-utils.git $ cd gnome-utils $ git checkout GNOME_UTILS_2_0_2
$ git clone git@ssh.gitlab.gnome.org:GNOME/banshee.git $ cd banshee $ git checkout 1.8.0
Getting Changes
Git is designed so that whenever there were any changes in the source code, you don't need to remove your sources and re-check out. The following command syncs up your code with what is stored in the Git repository
git pull --rebase
When you pull, you will notice a summary of the changes transferred (updated/new branches and tags) and a diffstat of the changes applied to your working copy. If you have local commits then the --rebase option will ensure that your local commits will first be removed temporarily, then the new changes from the remote git repository are fetched and applied, after which your local commits are reapplied on top of the new changes. If you do not use --rebase and you have local commits, your local commits will be merged with the new changes introducing a new commit which is often undesired.
Stashing Local Changes
If you have conflicting changes in your working copy the changes will not be applied. You can stash them first, do the pull, and apply you changes again with:
git stash git pull --rebase git stash pop
If you still have conflicts, you must resolve these, in general, before being able to rebuild the source code.
Check the output of 'git status' to know in which stage is each file and what you can do.
Note: The pull command should do what is called a fast-forward - that is, just update to a later revision.
Contributing patches
Since GNOME is moving from Bugzilla to GitLab, please see GitLab how to contribute a patch.
Note: If your patch is big or does many different things you may want to split it to make the review easier.
Setting the following global config and the git log command will decorate local commits:
git config --global log.decorate short
Applying Patches
If you are the one that gets sent a 'patch', then you can apply the commit in the patch with the following command:
git am [patch]
- If you have a patch based on an old version of the project and you want to update it to the current version you can do it with:
git pull --rebase
- Note that you may need to resolve some conflicts and commit afterwards.
Remember that git is a very flexible tool, and there are many different ways to use it. The above workflow is convenient for working on small patches, or for those who are just getting started with git.
Publishing your tree
If you are working on a large change, or need to make your patches available frequently, you may want to publish your tree somewhere where other people can clone from it.
Publishing your tree on github
github is a free (but not libre) web-based git hosting service. To publish a GNOME git tree to github:
Create an "Open Source" account, at http://github.com/signup/free. (Free accounts only let you create public source code repositories; paid accounts let you create private repos as well.)
After creating your account, click the link marked "(create a new one)" next to "Your repositories".
- Fill in the name and description, and click "Create Repository".
- It will then give you instructions on how to fill in your repository; however, since you are going to be pulling from gitlab.gnome.org but pushing to github.com, you need to do something slightly different from what they say:
- Look at the directions under "Existing Git Repo?"
cd to your git checkout, and copy the git remote add command from the git page, but change "origin" to "github"
to push all of your local branches to github, type: git push --all github
Now you can continue to pull and merge changes from gitlab.gnome.org as described above, and create as many local branches as you want, and just do "git push --all github" to push all of your branches to github, where other developers can see them, and clone their own copies of your repository.
Increased Trust
Applying for your own Git account
To apply for your own Git account, please read the New Account instructions.
Pushing your changes upstream
As you supply more and more patches to a given maintainer, the maintainer may ask you to obtain your own Git account to make your own source code check ins. To push your local commits back to the central repository, you would typically:
git pull --rebase
check that everything looks OK, test it,... You can also check what would be pushed with:
git push --dry-run
to finally push the new commits with:
git push
If you do not pull beforehand, and changes have occurred that you never pulled, you may receive an error when you try to push. So, it is always best to pull before you push.
Git, by default, pushes all the local branches which exist also in the remote repository. That may not be what you want so git displays this warning:
warning: You did not specify any refspecs to push, and the current remote warning: has not configured any push refspecs. The default action in this warning: case is to push all matching refspecs, that is, all branches warning: that exist both locally and remotely will be updated. This may warning: not necessarily be what you want to happen. warning: warning: You can specify what action you want to take in this case, and warning: avoid seeing this message again, by configuring 'push.default' to: warning: 'nothing' : Do not push anything warning: 'matching' : Push all matching branches (default) warning: 'tracking' : Push the current branch to whatever it is tracking warning: 'current' : Push the current branch
(comment: is it advisable to change push.default?) To only push the current branch to the remote repository use:
git push origin HEAD
or configure the remote to push only the current branch with:
git config remote.origin.push HEAD
Working as a module maintainer
With an increased amount of trust and responsibility, you may even be asked to start maintaining a project within GNOME Git - or indeed, one of your own that you may have imported.
Committing on behalf of a contributor
When committing code on behalf of others use the --author option, e.g.:
git commit -a --author "Joe Coder <joe@coder.org>"
This makes it easier to know who has contributed the code. You will still appear as committer.
Releasing
Maintainers must make tarball releases of their projects. This is well-documented at MaintainersCorner/Releasing.
Branching
At some point, you will need to branch your project for a stable set of releases, while continuing development on master; this works very much like tagging. This is documented at MaintainersCorner#branches.
Please make sure to read MaintainersCorner to familiarize yourself with other requirements of maintainers, including how to create Git/NewRepository.
See also
References
A good git cheat sheet is available from here.