在GNOME中充分使用git(Getting the most out of Git in GNOME)


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.

GNOME 建立了自己的Git库online browsing

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.

如果你想跟踪发生在不同的GNOME的Git项目的更改,订阅commits-list 邮件列表,这是一个高容量,只读列表接收邮件,每当有人合入代码库会触发此邮件的群发。你可以通过过滤邮件标题来查找你感兴趣的项目的变化。

设置 Git(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



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 git://git.gnome.org/[project]

The new subfolder will be named after the project.


With Git 1.6.6 and newer, http is possible too (please use the git protocol though!):

git clone http://git.gnome.org/browse/[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.

此时你把[project]替换成你想要的项目的名称。如果您想要把签出的代码另一个放在名称的文件夹下面,请把指定自己文件夹名称作为git clone的第二个参数。

开发者方式获取(Developer Access)

If you have a GNOME Git account already 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:

如果你已经有一个GNOME Git的帐户 你可以使用SSH密钥来验证自己的Git服务器,他们可能也将变回的Git仓库。他们使用一个稍微不同的URL和Git项目涉及克隆:

git clone ssh://[login@]git.gnome.org/git/[project]

In this case, if your local login is not the same as your GNOME developer login, you will also need to specify it in the URL.


An alternative to providing your GNOME developer login directly in the URL is to configure your SSH to automatically provide it when an attempt is made to connect to the git.gnome.org host. To do so, simply include the following in ~/.ssh/config :


Host git.gnome.org
    User [login]
    Compression yes
    CompressionLevel 3
    # Following keeps a connection around, speeding up jhbuild
    # requires a new enough openssh client
    ControlPersist 5m

从匿名的代码库到开发者方式(Convert anonymous repository to developer access)

Suppose you've been contributing patches to gtk+ and now you've been given developer access, you don't need to git clone again the 200 MB size of a gtk+ repository, just change the origin url of your anonymous repository, like so:

假如你为GTK+贡献补丁,并你已经获得了开发者接入,你不需要再次git clone 200 MB大小的GTK+库,只是改变你的匿名代码库的来源网址,像这样:

git config remote.origin.url ssh://[login@]git.gnome.org/git/[project]

gnome:clone的别名(gnome: clone alias)

Since all gnome modules have a common url prefix, it can be convenient to set up a clone alias:


git config --global url.ssh://[login@]git.gnome.org/git/.insteadof gnome:

Then the clone line becomes much shorter:


git clone gnome:[project]


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:

一些gnome模块里面可能包含Git子模块(例如nautilus中包含了libgd),在这种情况下,你需要添加--recursive 到clone 命令行,以提取得所有的子模块,像这样:

git clone --recursive git://git.gnome.org/[project]

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.

  • .git:这个目录处于一个项目的根目录。它包含了版本号的信息,源代码是从这里来的等。你可以忽略它,但你不应该删除它。
  • 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'.

  • autogen.sh:这是一个打包脚本,包括例如gettextize, intltoolize, libtoolize, aclocal, autoheader, automake 和 autoconf, 你可以用它来编译项目.比如
    • ./autogen.sh --prefix=/usr/local 将启动构建过程,包括检查你的电脑系统,生成所有必要的文件,然后你就输入'make'和'make install' 来启动构建.

  • ChangeLog

  • README: This generally gives information about the Git project in terms of project requirements, where to report bugs etc..

  • README文件: 这一般会提供项目的Git信息,在哪里报告错误等。
  • HACKING: This file usually specifies the rules [if any] for development in the project.

  • HACKING文件:此文件通常指定项目开发中的规则(如果有的话)。
  • [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..

  • [project].doap文件:此文件列出谁负责项目的日常维护。一般来说,他们都是你发送补丁的人。它还列出了一些其他的元数据的项目,如描述,网页,邮件列表等。
  • 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.

  • MAINTAINERS文件:这个文件列出维护者,类似于DOAP文件。现在通常已经不再需要MAINTAINERS文件了,但很多项目仍然使用该文件。

使用分支(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:

Git允许你在一个单独的开发线,也即分支(branch)上修改代码。在GNOME的很多时候,开发某一项目时存在稳定分支和不稳定分支 - 作为一个结果,主干分支[也被称为“主”(master)]可能不适用于你。在GNOME Git的稳定分支一般都是小写字母和数字组成的,以破折号隔开,比如:


where major, minor are version numbers. For example:



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.

本命令指定要创建一个本地分支,以跟踪远程(产地/)分支。您必须使用本地分支,并且你使用和它的远程分支一样的名字,否则稍后当您尝试你提交代码修改时,事情会变得非常复杂。如果你如我们这里演示的这样做,那么一个简单的“git push”就可以了。

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://git.gnome.org/gnome-utils
$ cd gnome-utils
$ git checkout -b gnome-2-26 origin/gnome-2-26

创建分支(Creating Branches)

See #Branching about creating remote branches at git.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)

Maintainers 'tag' their projects in GNOME Git to mark releases. Tags in GNOME Git are generally a mixture of uppercase alphabetic and numeric characters separated by underscores ie. of the form

在GNOME Git中,维护者给代码打标签来发正式版本.GNOME Git的代码标签是一个由大写字母和数字组成,用下划线隔开的标记,类似如下的形式:


or simply



where MAJOR, MINOR and MICRO are version numbers. For example

这里MAJOR, MINOR 和MICRO都是版本号,比如:


or 或者


列出标签(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

where the '-p' is to see the patch and the last one is a graphical viewer.

这里 '-p' 是查看补丁,最后的gitk是个图形节目的查看工具.

检出一个标签的代码(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://git.gnome.org/gnome-utils
$ cd gnome-utils
$ git checkout GNOME_UTILS_2_0_2

$ git clone git://git.gnome.org/banshee
$ 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)

Now that you have successfully checked out a GNOME Git project and hopefully managed to build it, you are ready to move forward and become a GNOME contributor.

现在你已经成功签出(check out)一个GNOME Git项目,希望设法创建(build)它,你已经准备好继续前进,成为GNOME的贡献者。

GNOME contributors send 'patches' [sometimes called 'diffs'] to each other and attach them to bug reports in bugzilla.gnome.org. A 'patch' describes changes in some files. Generally, you will use git format-patch to create a patch suitable for mailing or attaching to bugzilla, which looks like:

GNOME的贡献者彼此之间发送“补丁(patches)”[有时也称为“diff文件”],并将它们作为附件放在bugzilla.gnome.org的错误报告里面. 。 一个'补丁(patch)'描述文件的变化。一般情况下,你将使用git format-patch创建一个适合e-mail或附加到Bugzilla的补丁,它看起来像:

From 5eaf4b1061621ba5bc3157777f749237150b4cc8 Mon Sep 17 00:00:00 2001
From: Joe Bloggs <joe.bloggs@gnome.org>
Date: Fri, 17 Apr 2009 12:35:45 -0700
Subject: [PATCH] Add myself to AUTHORS. Fixes bug #12345.

 AUTHORS |    1 +
 1 files changed, 1 insertions(+), 0 deletions(-)

diff --git a/AUTHORS b/AUTHORS
index 15c2e37..12731aa 100644
@@ -8,3 +8,4 @@ Sandy Armstrong <sanfordarmstrong@gmail.com>
 Sebastian Rittau <srittau@jroger.in-berlin.de>
 Kevin Kubasik <kevin@kubasik.net>
 Stefan Schweizer <steve.schweizer@gmail.com>
+Joe Bloggs <joe.bloggs@gnome.org>

Here you can see the lines added prepended with a '+'. If you had removed [or edited] a line of code, you would have been likely to see a line prepended with '-'. Notice it also shows you the revision of the file you are creating a patch against (in the index line). Because you created the patch with git format-patch, your name and email address show up along with your commit message.

在这里,您可以看到行加入前面加上一个“+”。如果您已经删除[或编辑]一行代码,你可能会看到前面加上一行“ - ”。请注意,它也会显示你正在创建的补丁的版本号。因为你用git format-patch创建补丁,您的姓名和电子邮件地址与您提交的信息在一起。

Once you make changes to some given files you can generate a patch very easily.


First, see which files you've modified with git status, which should have output like:

首先,使用git status看看你有修改过的文件,应该有这样的输出:

# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#       modified:   AUTHORS
no changes added to commit (use "git add" and/or "git commit -a")

Here you can see the the "AUTHORS" file is modified, and that if you want to undo your change, you can use git checkout -- AUTHORS.

  • 在这里,你可以看到的“AUTHORS”被修改,如果你想撤消更改,您可以使用git checkout -- AUTHORS.

If you want to see the actual changes of the modified files, you can with:


git diff [files]

Then you have to commit your changes with:


git commit [files]
  • where [files] are the files that have changed, or use '-a' to commit all the changes. You should then be prompted with your favorite editor to add a descriptive commit message for this commit. Alternatively, you can also use '-m "Add myself to AUTHORS. Fixes bug #12345."' with the command written above.

其中[files]是已更改的文件,或者你也使用“-a”提交你的所有更改。然后,git会提示你在编辑器中为此次提交添加Git/CommitMessages。Alternatively, you can also use '-m "Add myself to AUTHORS. Fixes bug #12345."' with the command written above.

After committing, you can use the git-bz extension to git to submit a bug directly to bugzilla.gnome.org:

提交之后,你可以使用git-bz 插件直接提交到bugzilla.gnome.org的bug单:

git-bz file product/component HEAD

Substitute product and component with the Bugzilla identifiers, like gnome-panel/general. Or you can can generate a patch file manually with:

  • 使用Bugzilla标识如gnome-panel/general,替换上文的productcomponent。或者你如下可以手工生成patch

git format-patch HEAD^

This makes a patch out of your last commit, including the changes, the commit message, and your contact information.

  • 这会生成你的最后一次提交的一个补丁,包括修改,提交信息,以及您的联系信息。

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 log命令将修饰本地提交:

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.


在github发布代码树(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:

github 是一个免费的 (但不是开源的) 基于web页面的git托管网站. 为了在github发布GNOME 代码树:

1. 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.)

  1. After creating your account, click the link marked "(create a new one)" next to "Your repositories".

  2. Fill in the name and description, and click "Create Repository".

  3. 在http://github.com/signup/free创建一个“Open Source”的帐户。 (免费帐户只允许你创建公共源代码库,付费帐户则可以让您创建私有代码库)
  4. 创建帐户后,点击标记“Your repositories”边上的链接“[[https://github.com/repositories/new|(create a new one)]”。

  5. 在名称和说明填写,然后点击"Create Repository"。
  6. It will then give you instructions on how to fill in your repository; however, since you are going to be pulling from git.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 git.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.

在 Gitorious 发布代码树(Publishing your tree on Gitorious)

Gitorious is another free web-based git hosting service, which is also AGPL-licensed and can thus be installed on other servers as well.

Gitorious 是另一种基于网络的免费的git托管服务,它也是AGPL许可证的,因此可以安装在其他服务器上。

  • Click "Switch to OpenId" in the login form and login with your OpenId or register using the big "register now" button.

  • In the top right corner search for the gnome project name (e.g. "jhbuild-mirror")

  • 点击"Switch to OpenId" 的登录表单,并与您的OpenID登录,或者点击"register now" 大按钮开始注册。

  • 在右上角的搜索GNOME项目名称(例如,"jhbuild-mirror")

If there is one:

  • Click on the repository name
  • On the right hand side click "Clone this repository"
  • Pick a name for your repository & Confirm cloning

  • This will take you to your repository-clone page with push and pull url use git remote add gitorious PushURL and then push your branches like so git push gitorious mybranch

If there isn't one:

  • Click "your dashboard" in the top right corner
  • On the left hand side under "Your Projects" heading click "Create Project"
  • Fill out information about the project
  • On the next page create repository. You might want to create two repositories one for mirror & one for your personal stuff so that others can clone mirror as well and save space on gitorious.org.

  • Use instructions in the new repository to push branches.

增进了信任(Increased Trust)

申请你的GIT账号(Applying for your own Git account )

To apply for your own Git account, please read the New Account instructions.

申请你的Git账号,请阅读New Account

向上游提供你的修改(Pushing your changes upstream )

As you supply more and more patches to a given maintainer, or attach them to bugs in bugzilla.gnome.org, 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:

随着你提供越来越多的补丁给代码维护者,或者在bugzilla.gnome.org附上越来越多的补丁,维护者会让你获得Git账户own Git account 以让你的代码合入。为了发布你的本地改动到代码库,你通常需要:

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: 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.

随着不断增长的信任和责任,你可能会被邀请维护GNOME Git的某一个具体项目,或者你自己开启的项目imported

代替贡献者提交代码文件(Committing on behalf of a contributor)

When committing code on behalf of others use the --author option, e.g.:

当以其他人的身份提交代码,请使用--author 选项,比如:

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.



Maintainers must make tarball releases of their projects. This is well-documented at MaintainersCorner/Releasing.



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. 在某些时候,你就需要为发布稳定版本而拉出代码分支,同时在主干代码继续开发;这种工作方式非常类似给代码打标签(tagging)。有关此内容见[[MaintainersCorner#分支]。

Please make sure to read MaintainersCorner to familiarize yourself with other requirements of maintainers, including how to create Git/NewRepository.


其他(See also)


其他语言(Other languages)

Git/Developers_zh_CN (last edited 2015-12-27 15:40:04 by nsynet)