2. Osnove Git
3. Veje Git
7. Orodja Git
10. Notranjost Git-a
5.3 Distribuirani Git - Vzdrževanje projekta
Kot dodatek vedenju, kako efektivno prispevati projektu, boste verjetno morali vedeti, kako ga vzdrževati.
To lahko sestoji iz sprejemanja in uporabe popravkov generiranih preko
format-patch in poslanih preko e-pošte k vam, ali integracije sprememb v oddaljenih vejah za repozitorije, ki ste jih dodali kot daljave v vaš projekt.
Bodisi ali vzdržujete kanonični repozitorij ali želite pomagati s potrditvijo ali odobritvijo popravkov, morate vedeti, kako sprejeti delo na način, ki je najbolj jasen za ostale, ki prispevajo in da naredite trajnostno na dolgi rok.
Delo na tematskih vejah
Ko razmišljate o integraciji novega dela, je v splošnem dobra ideja poskusiti na tematski veji - začasni veji, posebej narejeni za preskušanje tega novega dela.
Na ta način je enostavno prilagoditi popravek individualno ali ga pustiti, če ne deluje dokler nimate časa priti nazaj nanj.
Če ustvarite enostavno ime veje na osnovi teme dela, katerega boste poskusili, kot je
ruby_client ali nekaj podobno opisljivega, si lahko enostavno zapomnite, če jo morate opustiti za nekaj časa in se kasneje vrniti.
Vzdrževalec projekta Git tudi stremi k prostorskemu poimenovanju teh vej - kot je
sc/ruby_client, kjer je
sc kratica za osebno, ki je prispevala delo.
Kot se boste spomnili, lahko ustvarite vejo na osnovi vaše veje master takole:
$ git branch sc/ruby_client master
Ali če želite takoj nanjo tudi preklopiti, lahko uporabite opcijo
$ git checkout -b sc/ruby_client master
Sedaj ste pripravljeni dodati vaše prispevano delo v to tematsko vejo in določiti, če jo želite združiti v vaše veje na dolgi rok.
Uporaba popravkov iz e-pošte
Če prejmete popravek, ki ga morate integrirati v vaš projekt, preko e-pošte, morate uporabiti popravek na vaši tematski veji, da ga ocenite.
Na voljo sta dva načina za uporabo e-poštnega popravka: z
git apply ali z
Uporaba popravka z apply
Če prejmete popravek od nekoga, ki ga je generiral z
git diff ali Unix ukazom
diff (kar ni priporočljivo; glejte naslednjo sekcijo), ga lahko uporabite z ukazom
Predpostavljamo, da ste shranili popravek v
/tmp/patch-ruby-client.patch, lahko uporabite popravek sledeče:
$ git apply /tmp/patch-ruby-client.patch
To spremeni datoteke v vašem delovnem direktoriju.
Je skoraj identično pognati ukaz
patch -p1, da uporabite popravek, vendar je bolj paranoično in sprejema manj nejasna ujemanja kot popravek.
Upravlja tudi dodajanja datotek, brisanja in preimenovanja, če so opisana v obliki
git diff, kar
patch ne naredi.
git apply je model “apply all or abort all”, kjer je bodisi vse uporabljeno ali nič, kjer
patch lahko delno uporablja datoteke popravkov, kar pusti vaš delovni direktorij v čudnem stanju.
git apply je splošno veliko bolj konzervativen kot
Ne bo ustvaril pošiljanja za vas - po tem, ko ga poženete, morate dati v vmesno fazo in poslati spremembe predstavljene ročno.
Lahko uporabite tudi git apply, da vidite, če je popravek uporabljen čisto, preden ga poskusite dejansko uporabiti - lahko poženete
git apply --check s popravkom:
$ git apply --check 0001-seeing-if-this-helps-the-gem.patch error: patch failed: ticgit.gemspec:1 error: ticgit.gemspec: patch does not apply
Če ni nobenega izpisa, potem bi moral biti popravek uporabljen čisto. Ta ukaz lahko obstaja z ne-ničelnim statusom, če preverjanje ni uspešno, da ga lahko uporabite v skriptah, če želite.
Uporaba popravka z
Če je uporabnik, ki prispeva, Git uporabnik in je bilo dovolj dobro uporabiti ukaz
format-patch za generiranje njegovega popravka, potem je vaše delo enostavnejše, ker popravek vsebuje informacije avtorja in sporočilo pošiljanja za vas.
Če lahko, vzpodbudite vaše prispevalce, da uporabljajo
diff za generiranje popravkov za vas.
Morali bi uporabiti samo
git apply pri opuščenih popravkih in podobnih stvareh.
Da uporabite popravek generiran s
git am zgrajen, da prebere datoteko mbox, ki je enostaven tekstovni format za shranjevanje enega ali več e-poštnih sporočil v eni tekstovni datoteki.
Izgleda nekako sledeče:
From 330090432754092d704da8e76ca5c05c198e71a8 Mon Sep 17 00:00:00 2001 From: Jessica Smith <firstname.lastname@example.org> Date: Sun, 6 Apr 2008 10:17:23 -0700 Subject: [PATCH 1/2] add limit to log function Limit log functionality to the first 20
This is the beginning of the output of the format-patch command that you saw in the previous section. This is also a valid mbox e-mail format. If someone has e-mailed you the patch properly using git send-email, and you download that into an mbox format, then you can point git am to that mbox file, and it will start applying all the patches it sees. If you run a mail client that can save several e-mails out in mbox format, you can save entire patch series into a file and then use git am to apply them one at a time.
However, if someone uploaded a patch file generated via
format-patch to a ticketing system or something similar, you can save the file locally and then pass that file saved on your disk to
git am to apply it:
$ git am 0001-limit-log-function.patch Applying: add limit to log function
You can see that it applied cleanly and automatically created the new commit for you.
The author information is taken from the e-mail’s
Date headers, and the message of the commit is taken from the
Subject and body (before the patch) of the e-mail.
For example, if this patch was applied from the mbox example above, the commit generated would look something like this:
$ git log --pretty=fuller -1 commit 6c5e70b984a60b3cecd395edd5b48a7575bf58e0 Author: Jessica Smith <email@example.com> AuthorDate: Sun Apr 6 10:17:23 2008 -0700 Commit: Scott Chacon <firstname.lastname@example.org> CommitDate: Thu Apr 9 09:19:06 2009 -0700 add limit to log function Limit log functionality to the first 20
Commit information indicates the person who applied the patch and the time it was applied.
Author information is the individual who originally created the patch and when it was originally created.
But it’s possible that the patch won’t apply cleanly.
Perhaps your main branch has diverged too far from the branch the patch was built from, or the patch depends on another patch you haven’t applied yet.
In that case, the
git am process will fail and ask you what you want to do:
$ git am 0001-seeing-if-this-helps-the-gem.patch Applying: seeing if this helps the gem error: patch failed: ticgit.gemspec:1 error: ticgit.gemspec: patch does not apply Patch failed at 0001. When you have resolved this problem run "git am --resolved". If you would prefer to skip this patch, instead run "git am --skip". To restore the original branch and stop patching run "git am --abort".
This command puts conflict markers in any files it has issues with, much like a conflicted merge or rebase operation.
You solve this issue much the same way – edit the file to resolve the conflict, stage the new file, and then run
git am --resolved to continue to the next patch:
$ (fix the file) $ git add ticgit.gemspec $ git am --resolved Applying: seeing if this helps the gem
If you want Git to try a bit more intelligently to resolve the conflict, you can pass a
-3 option to it, which makes Git attempt a three-way merge.
This option isn’t on by default because it doesn’t work if the commit the patch says it was based on isn’t in your repository.
If you do have that commit – if the patch was based on a public commit – then the
-3 option is generally much smarter about applying a conflicting patch:
$ git am -3 0001-seeing-if-this-helps-the-gem.patch Applying: seeing if this helps the gem error: patch failed: ticgit.gemspec:1 error: ticgit.gemspec: patch does not apply Using index info to reconstruct a base tree... Falling back to patching base and 3-way merge... No changes -- Patch already applied.
In this case, this patch had already been applied.
-3 option, it looks like a conflict.
If you’re applying a number of patches from an mbox, you can also run the
am command in interactive mode, which stops at each patch it finds and asks if you want to apply it:
$ git am -3 -i mbox Commit Body is: -------------------------- seeing if this helps the gem -------------------------- Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all
This is nice if you have a number of patches saved, because you can view the patch first if you don’t remember what it is, or not apply the patch if you’ve already done so.
When all the patches for your topic are applied and committed into your branch, you can choose whether and how to integrate them into a longer-running branch.
Checking Out Remote Branches
If your contribution came from a Git user who set up their own repository, pushed a number of changes into it, and then sent you the URL to the repository and the name of the remote branch the changes are in, you can add them as a remote and do merges locally.
For instance, if Jessica sends you an e-mail saying that she has a great new feature in the
ruby-client branch of her repository, you can test it by adding the remote and checking out that branch locally:
$ git remote add jessica git://github.com/jessica/myproject.git $ git fetch jessica $ git checkout -b rubyclient jessica/ruby-client
If she e-mails you again later with another branch containing another great feature, you can fetch and check out because you already have the remote setup.
This is most useful if you’re working with a person consistently. If someone only has a single patch to contribute once in a while, then accepting it over e-mail may be less time consuming than requiring everyone to run their own server and having to continually add and remove remotes to get a few patches. You’re also unlikely to want to have hundreds of remotes, each for someone who contributes only a patch or two. However, scripts and hosted services may make this easier – it depends largely on how you develop and how your contributors develop.
The other advantage of this approach is that you get the history of the commits as well.
Although you may have legitimate merge issues, you know where in your history their work is based; a proper three-way merge is the default rather than having to supply a
-3 and hope the patch was generated off a public commit to which you have access.
If you aren’t working with a person consistently but still want to pull from them in this way, you can provide the URL of the remote repository to the
git pull command.
This does a one-time pull and doesn’t save the URL as a remote reference:
$ git pull https://github.com/onetimeguy/project From https://github.com/onetimeguy/project * branch HEAD -> FETCH_HEAD Merge made by recursive.
Determining What Is Introduced
Now you have a topic branch that contains contributed work. At this point, you can determine what you’d like to do with it. This section revisits a couple of commands so you can see how you can use them to review exactly what you’ll be introducing if you merge this into your main branch.
It’s often helpful to get a review of all the commits that are in this branch but that aren’t in your master branch.
You can exclude commits in the master branch by adding the
--not option before the branch name.
This does the same thing as the
master..contrib format that we used earlier.
For example, if your contributor sends you two patches and you create a branch called
contrib and applied those patches there, you can run this:
$ git log contrib --not master commit 5b6235bd297351589efc4d73316f0a68d484f118 Author: Scott Chacon <email@example.com> Date: Fri Oct 24 09:53:59 2008 -0700 seeing if this helps the gem commit 7482e0d16d04bea79d0dba8988cc78df655f16a0 Author: Scott Chacon <firstname.lastname@example.org> Date: Mon Oct 22 19:38:36 2008 -0700 updated the gemspec to hopefully work better
To see what changes each commit introduces, remember that you can pass the
-p option to
git log and it will append the diff introduced to each commit.
To see a full diff of what would happen if you were to merge this topic branch with another branch, you may have to use a weird trick to get the correct results. You may think to run this:
$ git diff master
This command gives you a diff, but it may be misleading.
master branch has moved forward since you created the topic branch from it, then you’ll get seemingly strange results.
This happens because Git directly compares the snapshots of the last commit of the topic branch you’re on and the snapshot of the last commit on the
For example, if you’ve added a line in a file on the
master branch, a direct comparison of the snapshots will look like the topic branch is going to remove that line.
master is a direct ancestor of your topic branch, this isn’t a problem; but if the two histories have diverged, the diff will look like you’re adding all the new stuff in your topic branch and removing everything unique to the
What you really want to see are the changes added to the topic branch – the work you’ll introduce if you merge this branch with master. You do that by having Git compare the last commit on your topic branch with the first common ancestor it has with the master branch.
Technically, you can do that by explicitly figuring out the common ancestor and then running your diff on it:
$ git merge-base contrib master 36c7dba2c95e6bbb78dfa822519ecfec6e1ca649 $ git diff 36c7db
However, that isn’t convenient, so Git provides another shorthand for doing the same thing: the triple-dot syntax.
In the context of the
diff command, you can put three periods after another branch to do a
diff between the last commit of the branch you’re on and its common ancestor with another branch:
$ git diff master...contrib
This command shows you only the work your current topic branch has introduced since its common ancestor with master. That is a very useful syntax to remember.
Integrating Contributed Work
When all the work in your topic branch is ready to be integrated into a more mainline branch, the question is how to do it. Furthermore, what overall workflow do you want to use to maintain your project? You have a number of choices, so we’ll cover a few of them.
One simple workflow merges your work into your
In this scenario, you have a
master branch that contains basically stable code.
When you have work in a topic branch that you’ve done or that someone has contributed and you’ve verified, you merge it into your master branch, delete the topic branch, and then continue the process.
If we have a repository with work in two branches named
php_client that looks like History with several topic branches. and merge
ruby_client first and then
php_client next, then your history will end up looking like After a topic branch merge..
That is probably the simplest workflow, but it can possibly be problematic if you’re dealing with larger or more stable projects where you want to be really careful about what you introduce.
If you have a more important project, you might want to use a two-phase merge cycle.
In this scenario, you have two long-running branches,
develop, in which you determine that
master is updated only when a very stable release is cut and all new code is integrated into the
You regularly push both of these branches to the public repository.
Each time you have a new topic branch to merge in (Before a topic branch merge.), you merge it into
develop (After a topic branch merge.); then, when you tag a release, you fast-forward
master to wherever the now-stable
develop branch is (After a project release.).
This way, when people clone your project’s repository, they can either check out master to build the latest stable version and keep up to date on that easily, or they can check out develop, which is the more cutting-edge stuff. You can also continue this concept, having an integrate branch where all the work is merged together. Then, when the codebase on that branch is stable and passes tests, you merge it into a develop branch; and when that has proven itself stable for a while, you fast-forward your master branch.
The Git project has four long-running branches:
pu (proposed updates) for new work, and
maint for maintenance backports.
When new work is introduced by contributors, it’s collected into topic branches in the maintainer’s repository in a manner similar to what we’ve described (see Managing a complex series of parallel contributed topic branches.).
At this point, the topics are evaluated to determine whether they’re safe and ready for consumption or whether they need more work.
If they’re safe, they’re merged into
next, and that branch is pushed up so everyone can try the topics integrated together.
If the topics still need work, they’re merged into
When it’s determined that they’re totally stable, the topics are re-merged into
master and are then rebuilt from the topics that were in
next but didn’t yet graduate to
master almost always moves forward,
next is rebased occasionally, and
pu is rebased even more often:
When a topic branch has finally been merged into
master, it’s removed from the repository.
The Git project also has a
maint branch that is forked off from the last release to provide backported patches in case a maintenance release is required.
Thus, when you clone the Git repository, you have four branches that you can check out to evaluate the project in different stages of development, depending on how cutting edge you want to be or how you want to contribute; and the maintainer has a structured workflow to help them vet new contributions.
Rebasing and Cherry Picking Workflows
Other maintainers prefer to rebase or cherry-pick contributed work on top of their master branch, rather than merging it in, to keep a mostly linear history.
When you have work in a topic branch and have determined that you want to integrate it, you move to that branch and run the rebase command to rebuild the changes on top of your current master (or
develop, and so on) branch.
If that works well, you can fast-forward your
master branch, and you’ll end up with a linear project history.
The other way to move introduced work from one branch to another is to cherry-pick it. A cherry-pick in Git is like a rebase for a single commit. It takes the patch that was introduced in a commit and tries to reapply it on the branch you’re currently on. This is useful if you have a number of commits on a topic branch and you want to integrate only one of them, or if you only have one commit on a topic branch and you’d prefer to cherry-pick it rather than run rebase. For example, suppose you have a project that looks like this:
If you want to pull commit
e43a6 into your master branch, you can run
$ git cherry-pick e43a6fd3e94888d76779ad79fb568ed180e5fcdf Finished one cherry-pick. [master]: created a0a41a9: "More friendly message when locking the index fails." 3 files changed, 17 insertions(+), 3 deletions(-)
This pulls the same change introduced in
e43a6, but you get a new commit SHA-1 value, because the date applied is different.
Now your history looks like this:
Now you can remove your topic branch and drop the commits you didn’t want to pull in.
If you’re doing lots of merging and rebasing, or you’re maintaining a long-lived topic branch, Git has a feature called “rerere” that can help.
Rerere stands for “reuse recorded resolution” – it’s a way of shortcutting manual conflict resolution. When rerere is enabled, Git will keep a set of pre- and post-images from successful merges, and if it notices that there’s a conflict that looks exactly like one you’ve already fixed, it’ll just use the fix from last time, without bothering you with it.
This feature comes in two parts: a configuration setting and a command.
The configuration setting is
rerere.enabled, and it’s handy enough to put in your global config:
$ git config --global rerere.enabled true
Now, whenever you do a merge that resolves conflicts, the resolution will be recorded in the cache in case you need it in the future.
If you need to, you can interact with the rerere cache using the
git rerere command.
When it’s invoked alone, Git checks its database of resolutions and tries to find a match with any current merge conflicts and resolve them (although this is done automatically if
rerere.enabled is set to
There are also subcommands to see what will be recorded, to erase specific resolution from the cache, and to clear the entire cache. We will cover rerere in more detail in Rerere.
Tagging Your Releases
When you’ve decided to cut a release, you’ll probably want to drop a tag so you can re-create that release at any point going forward. You can create a new tag as discussed in [ch02-git-basics]. If you decide to sign the tag as the maintainer, the tagging may look something like this:
$ git tag -s v1.5 -m 'my signed 1.5 tag' You need a passphrase to unlock the secret key for user: "Scott Chacon <email@example.com>" 1024-bit DSA key, ID F721C45A, created 2009-02-09
If you do sign your tags, you may have the problem of distributing the public PGP key used to sign your tags.
The maintainer of the Git project has solved this issue by including their public key as a blob in the repository and then adding a tag that points directly to that content.
To do this, you can figure out which key you want by running
$ gpg --list-keys /Users/schacon/.gnupg/pubring.gpg --------------------------------- pub 1024D/F721C45A 2009-02-09 [expires: 2010-02-09] uid Scott Chacon <firstname.lastname@example.org> sub 2048g/45D02282 2009-02-09 [expires: 2010-02-09]
Then, you can directly import the key into the Git database by exporting it and piping that through
git hash-object, which writes a new blob with those contents into Git and gives you back the SHA-1 of the blob:
$ gpg -a --export F721C45A | git hash-object -w --stdin 659ef797d181633c87ec71ac3f9ba29fe5775b92
Now that you have the contents of your key in Git, you can create a tag that points directly to it by specifying the new SHA-1 value that the
hash-object command gave you:
$ git tag -a maintainer-pgp-pub 659ef797d181633c87ec71ac3f9ba29fe5775b92
If you run
git push --tags, the
maintainer-pgp-pub tag will be shared with everyone.
If anyone wants to verify a tag, they can directly import your PGP key by pulling the blob directly out of the database and importing it into GPG:
$ git show maintainer-pgp-pub | gpg --import
They can use that key to verify all your signed tags.
Also, if you include instructions in the tag message, running
git show <tag> will let you give the end user more specific instructions about tag verification.
Generating a Build Number
Because Git doesn’t have monotonically increasing numbers like v123 or the equivalent to go with each commit, if you want to have a human-readable name to go with a commit, you can run
git describe on that commit.
Git gives you the name of the nearest tag with the number of commits on top of that tag and a partial SHA-1 value of the commit you’re describing:
$ git describe master v1.6.2-rc1-20-g8c5b85c
This way, you can export a snapshot or build and name it something understandable to people.
In fact, if you build Git from source code cloned from the Git repository,
git --version gives you something that looks like this.
If you’re describing a commit that you have directly tagged, it gives you the tag name.
git describe command favors annotated tags (tags created with the
-s flag), so release tags should be created this way if you’re using
git describe, to ensure the commit is named properly when described.
You can also use this string as the target of a checkout or show command, although it relies on the abbreviated SHA-1 value at the end, so it may not be valid forever.
For instance, the Linux kernel recently jumped from 8 to 10 characters to ensure SHA-1 object uniqueness, so older
git describe output names were invalidated.
Preparing a Release
Now you want to release a build.
One of the things you’ll want to do is create an archive of the latest snapshot of your code for those poor souls who don’t use Git.
The command to do this is
$ git archive master --prefix='project/' | gzip > `git describe master`.tar.gz $ ls *.tar.gz v1.6.2-rc1-20-g8c5b85c.tar.gz
If someone opens that tarball, they get the latest snapshot of your project under a project directory.
You can also create a zip archive in much the same way, but by passing the
--format=zip option to
$ git archive master --prefix='project/' --format=zip > `git describe master`.zip
You now have a nice tarball and a zip archive of your project release that you can upload to your website or e-mail to people.
It’s time to e-mail your mailing list of people who want to know what’s happening in your project.
A nice way of quickly getting a sort of changelog of what has been added to your project since your last release or e-mail is to use the
git shortlog command.
It summarizes all the commits in the range you give it; for example, the following gives you a summary of all the commits since your last release, if your last release was named v1.0.1:
$ git shortlog --no-merges master --not v1.0.1 Chris Wanstrath (8): Add support for annotated tags to Grit::Tag Add packed-refs annotated tag support. Add Grit::Commit#to_patch Update version and History.txt Remove stray `puts` Make ls_tree ignore nils Tom Preston-Werner (4): fix dates in history dynamic version method Version bump to 1.0.2 Regenerated gemspec for version 1.0.2
You get a clean summary of all the commits since v1.0.1, grouped by author, that you can e-mail to your list.