This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex

(备注:因为本页面翻译自英文页面,为了便于在英文页面更新后,中文版也能方便地对比出差异以同步更新,因此本页面把翻译时的英文内容也保留下来(以斜体的格式),如果有翻译不妥的地方,也请不吝修改.)

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

介绍(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.

Git是一个让许多开发者针对相同的源代码同时工作的一个强大工具。它广泛应用于GNOME项目中,同时常常也是GNOME项目新开发者遇到的第一个难关。

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.

每个开发人员从Git的源代码库中克隆出一个副本,然后在自己的副本中工作,独立于其他开发人员。当他们做了修改后,他们从本地提交(commit)。他们满意自己提交(commit)后,他们把修改提交到Git仓库(push)。这样的一系列的提交可以在准备和检验,然后一次性推到库上。

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.

使用Git,每个人都可以用他们的本地克隆的代码,去做任何他们想做的事。此外,几乎所有的git操作都是本地的,所以操作速度快,并且可以在不连接到原来的代码库。

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配置自己的身份:

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

如果打开漂亮的着色后,您看到异常的输出,则可能需要将此行添加到您的~/.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:

要克隆的所有历史和项目的分支到你的本地硬盘的当前目录下的子文件夹,从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.

在这种情况下,如果你的本地登录不上你的GNOME开发者登录一样,你也需要在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 :

另一种直接在URL提供GNOME开发者登录的方法是配置你的SSH连接git.gnome.org主机时自动提供它。简单地包括以下几步就可以实现~/.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:

因为所有的gnome模块都有一个共同的URL前缀,所以建立一个clone的别名会方面后期使用:

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

Then the clone line becomes much shorter:

这样,clone的命令行就变得更短了:

git clone gnome:[project]

子模块(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:

一些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模块的根目录,执行以下命令来提取出所有的新子模块代码:

git submodule update --init --recursive

Source

常见的文件(Common Files)

When the clone has been completed, you will start to notice that many projects in Git GNOME contain similar files:

当克隆完成后,你会开始发现,在GNOME的许多项目的包含相似的git文件:

使用分支(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的稳定分支一般都是小写字母和数字组成的,以破折号隔开,比如:

[project]-[MAJOR]-[MINOR]

where major, minor are version numbers. For example:

这里major和minor是版本号。比如:

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中,分支和标签都指的是一次提交。列出一个指定项目的本地分支,你可以使用:

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:

下面的例子将检出的gnome-utils的主干分支,然后检出'的gnome-2-26'分支:

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

关于在git.gnome.org创建远程分支机构请参见[[#Branching]。

本地的代码分支(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版本大于1.6.1,你也可以使用:

git checkout --track origin/my-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的代码标签是一个由大写字母和数字组成,用下划线隔开的标记,类似如下的形式:

[PROJECT]_[MAJOR]_[MINOR]_[MICRO]

or simply

或者简单一点的如下:

[MAJOR].[MINOR].[MICRO]

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

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

GTK_2_0_6
GNOME_UTILS_2_0_2

or 或者

1.8.0
1.9.1

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

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

检出一个标签的代码(Checking Out a Tag)

You can check out a tag with the same command as you checkout a branch:

您可以检出一个标签(tag)的代码,使用的命令与你检出一个分支(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:

下面的例子将检出的gnome-utils的2.0.2标签,以及从Banshee检出1.8.0:

$ 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是设计成,不管在源代码中的任何变化,你不需要删除你的源代码,并重新检出,并再次合入。下面的命令把你的代码同步到Git仓库代码

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
--- a/AUTHORS
+++ b/AUTHORS
@@ -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>
-- 
1.6.2.1

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.

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]

其中[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:

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.

请记住,GIT中是一种非常灵活的工具,而且有许多不同的方式来使用它。上述工作流程对于小补丁,或者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许可证的,因此可以安装在其他服务器上。

If there is one:

If there isn't one:

增进了信任(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:

检查一切看起来不错,测试了一下,......你也可以检查看看是否能push操作(译者注:加了--dry-run只是假装push了一下,并没有真正提交数据):

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.

随着不断增长的信任和责任,你可能会被邀请维护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.

这样可以清晰地知道谁贡献了代码,而你依然是代码文件的提交者.

发布版本(Releasing)

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

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

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

请务必阅读[MaintainersCorner]以熟悉维护者的其他要求,包括如何创建Git/NewRepository

其他(See also)

参考(References)

其他语言(Other languages)


2024-10-23 11:09