4 This manual is designed to be readable by someone with basic unix
5 commandline skills, but no previous knowledge of git.
7 Chapters 1 and 2 explain how to fetch and study a project using
8 git--the tools you'd need to build and test a particular version of a
9 software project, to search for regressions, and so on.
11 Chapter 3 explains how to do development with git, and chapter 4 how
12 to share that development with others.
14 Further chapters cover more specialized topics.
16 Comprehensive reference documentation is available through the man
17 pages. For a command such as "git clone", just use
19 ------------------------------------------------
21 ------------------------------------------------
23 Repositories and Branches
24 =========================
26 How to get a git repository
27 ---------------------------
29 It will be useful to have a git repository to experiment with as you
32 The best way to get one is by using the gitlink:git-clone[1] command
33 to download a copy of an existing repository for a project that you
34 are interested in. If you don't already have a project in mind, here
35 are some interesting examples:
37 ------------------------------------------------
38 # git itself (approx. 10MB download):
39 $ git clone git://git.kernel.org/pub/scm/git/git.git
40 # the linux kernel (approx. 150MB download):
41 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
42 ------------------------------------------------
44 The initial clone may be time-consuming for a large project, but you
45 will only need to clone once.
47 The clone command creates a new directory named after the project
48 ("git" or "linux-2.6" in the examples above). After you cd into this
49 directory, you will see that it contains a copy of the project files,
50 together with a special top-level directory named ".git", which
51 contains all the information about the history of the project.
53 In most of the following, examples will be taken from one of the two
56 How to check out a different version of a project
57 -------------------------------------------------
59 Git is best thought of as a tool for storing the history of a
60 collection of files. It stores the history as a compressed
61 collection of interrelated snapshots (versions) of the project's
64 A single git repository may contain multiple branches. Each branch
65 is a bookmark referencing a particular point in the project history.
66 The gitlink:git-branch[1] command shows you the list of branches:
68 ------------------------------------------------
71 ------------------------------------------------
73 A freshly cloned repository contains a single branch, named "master",
74 and the working directory contains the version of the project
75 referred to by the master branch.
77 Most projects also use tags. Tags, like branches, are references
78 into the project's history, and can be listed using the
79 gitlink:git-tag[1] command:
81 ------------------------------------------------
93 ------------------------------------------------
95 Create a new branch pointing to one of these versions and check it
96 out using gitlink:git-checkout[1]:
98 ------------------------------------------------
99 $ git checkout -b new v2.6.13
100 ------------------------------------------------
102 The working directory then reflects the contents that the project had
103 when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
104 branches, with an asterisk marking the currently checked-out branch:
106 ------------------------------------------------
110 ------------------------------------------------
112 If you decide that you'd rather see version 2.6.17, you can modify
113 the current branch to point at v2.6.17 instead, with
115 ------------------------------------------------
116 $ git reset --hard v2.6.17
117 ------------------------------------------------
119 Note that if the current branch was your only reference to a
120 particular point in history, then resetting that branch may leave you
121 with no way to find the history it used to point to; so use this
124 Understanding History: Commits
125 ------------------------------
127 Every change in the history of a project is represented by a commit.
128 The gitlink:git-show[1] command shows the most recent commit on the
131 ------------------------------------------------
133 commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
134 Author: Jamal Hadi Salim <hadi@cyberus.ca>
135 Date: Sat Dec 2 22:22:25 2006 -0800
137 [XFRM]: Fix aevent structuring to be more complete.
139 aevents can not uniquely identify an SA. We break the ABI with this
140 patch, but consensus is that since it is not yet utilized by any
141 (known) application then it is fine (better do it now than later).
143 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
144 Signed-off-by: David S. Miller <davem@davemloft.net>
146 diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
147 index 8be626f..d7aac9d 100644
148 --- a/Documentation/networking/xfrm_sync.txt
149 +++ b/Documentation/networking/xfrm_sync.txt
150 @@ -47,10 +47,13 @@ aevent_id structure looks like:
152 struct xfrm_aevent_id {
153 struct xfrm_usersa_id sa_id;
154 + xfrm_address_t saddr;
159 ------------------------------------------------
161 As you can see, a commit shows who made the latest change, what they
164 Every commit has a 20-digit id, sometimes called the "SHA1 id", shown
165 on the first line of the "git show" output. You can usually refer to
166 a commit by a shorter name, such as a tag or a branch name, but this
167 longer id can also be useful. In particular, it is a globally unique
168 name for this commit: so if you tell somebody else the SHA1 id (for
169 example in email), then you are guaranteed they will see the same
170 commit in their repository that you do in yours.
172 Understanding history: commits, parents, and reachability
173 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175 Every commit (except the very first commit in a project) also has a
176 parent commit which shows what happened before this commit.
177 Following the chain of parents will eventually take you back to the
178 beginning of the project.
180 However, the commits do not form a simple list; git allows lines of
181 development to diverge and then reconverge, and the point where two
182 lines of development reconverge is called a "merge". The commit
183 representing a merge can therefore have more than one parent, with
184 each parent representing the most recent commit on one of the lines
185 of development leading to that point.
187 The best way to see how this works is using the gitlink:gitk[1]
188 command; running gitk now on a git repository and looking for merge
189 commits will help understand how the git organizes history.
191 In the following, we say that commit X is "reachable" from commit Y
192 if commit X is an ancestor of commit Y. Equivalently, you could say
193 that Y is a descendent of X, or that there is a chain of parents
194 leading from commit Y to commit X.
196 Undestanding history: History diagrams
197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199 We will sometimes represent git history using diagrams like the one
200 below. Commits are shown as "o", and the links between them with
201 lines drawn with - / and \. Time goes left to right:
209 If we need to talk about a particular commit, the character "o" may
210 be replaced with another letter or number.
212 Understanding history: What is a branch?
213 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215 Though we've been using the word "branch" to mean a kind of reference
216 to a particular commit, the word branch is also commonly used to
217 refer to the line of commits leading up to that point. In the
218 example above, git may think of the branch named "A" as just a
219 pointer to one particular commit, but we may refer informally to the
220 line of three commits leading up to that point as all being part of
223 If we need to make it clear that we're just talking about the most
224 recent commit on the branch, we may refer to that commit as the
225 "head" of the branch.
227 Manipulating branches
228 ---------------------
230 Creating, deleting, and modifying branches is quick and easy; here's
231 a summary of the commands:
235 git branch <branch>::
236 create a new branch named <branch>, referencing the same
237 point in history as the current branch
238 git branch <branch> <start-point>::
239 create a new branch named <branch>, referencing
240 <start-point>, which may be specified any way you like,
241 including using a branch name or a tag name
242 git branch -d <branch>::
243 delete the branch <branch>; if the branch you are deleting
244 points to a commit which is not reachable from this branch,
245 this command will fail with a warning.
246 git branch -D <branch>::
247 even if the branch points to a commit not reachable
248 from the current branch, you may know that that commit
249 is still reachable from some other branch or tag. In that
250 case it is safe to use this command to force git to delete
252 git checkout <branch>::
253 make the current branch <branch>, updating the working
254 directory to reflect the version referenced by <branch>
255 git checkout -b <new> <start-point>::
256 create a new branch <new> referencing <start-point>, and
259 It is also useful to know that the special symbol "HEAD" can always
260 be used to refer to the current branch.
262 Examining branches from a remote repository
263 -------------------------------------------
265 The "master" branch that was created at the time you cloned is a copy
266 of the HEAD in the repository that you cloned from. That repository
267 may also have had other branches, though, and your local repository
268 keeps branches which track each of those remote branches, which you
269 can view using the "-r" option to gitlink:git-branch[1]:
271 ------------------------------------------------
281 ------------------------------------------------
283 You cannot check out these remote-tracking branches, but you can
284 examine them on a branch of your own, just as you would a tag:
286 ------------------------------------------------
287 $ git checkout -b my-todo-copy origin/todo
288 ------------------------------------------------
290 Note that the name "origin" is just the name that git uses by default
291 to refer to the repository that you cloned from.
293 [[how-git-stores-references]]
294 How git stores references
295 -------------------------
297 Branches, remote-tracking branches, and tags are all references to
298 commits. Git stores these references in the ".git" directory. Most
299 of them are stored in .git/refs/:
301 - branches are stored in .git/refs/heads
302 - tags are stored in .git/refs/tags
303 - remote-tracking branches for "origin" are stored in
304 .git/refs/remotes/origin/
306 If you look at one of these files you will see that they usually
307 contain just the SHA1 id of a commit:
309 ------------------------------------------------
310 $ ls .git/refs/heads/
312 $ cat .git/refs/heads/master
313 c0f982dcf188d55db9d932a39d4ea7becaa55fed
314 ------------------------------------------------
316 You can refer to a reference by its path relative to the .git
317 directory. However, we've seen above that git will also accept
318 shorter names; for example, "master" is an acceptable shortcut for
319 "refs/heads/master", and "origin/master" is a shortcut for
320 "refs/remotes/origin/master".
322 As another useful shortcut, you can also refer to the "HEAD" of
323 "origin" (or any other remote), using just the name of the remote.
325 For the complete list of paths which git checks for references, and
326 how it decides which to choose when there are multiple references
327 with the same name, see the "SPECIFYING REVISIONS" section of
328 gitlink:git-rev-parse[1].
330 [[Updating-a-repository-with-git-fetch]]
331 Updating a repository with git fetch
332 ------------------------------------
334 Eventually the developer cloned from will do additional work in her
335 repository, creating new commits and advancing the branches to point
338 The command "git fetch", with no arguments, will update all of the
339 remote-tracking branches to the latest version found in her
340 repository. It will not touch any of your own branches--not even the
341 "master" branch that was created for you on clone.
343 Fetching branches from other repositories
344 -----------------------------------------
346 You can also track branches from repositories other than the one you
347 cloned from, using gitlink:git-remote[1]:
349 -------------------------------------------------
350 $ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
352 * refs/remotes/linux-nfs/master: storing branch 'master' ...
354 -------------------------------------------------
356 New remote-tracking branches will be stored under the shorthand name
357 that you gave "git remote add", in this case linux-nfs:
359 -------------------------------------------------
363 -------------------------------------------------
365 If you run "git fetch <remote>" later, the tracking branches for the
366 named <remote> will be updated.
368 If you examine the file .git/config, you will see that git has added
371 -------------------------------------------------
375 url = git://linux-nfs.org/~bfields/git.git
376 fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
378 -------------------------------------------------
380 This is what causes git to track the remote's branches; you may
381 modify or delete these configuration options by editing .git/config
384 Fetching individual branches
385 ----------------------------
387 TODO: find another home for this, later on:
389 You can also choose to update just one branch at a time:
391 -------------------------------------------------
392 $ git fetch origin todo:refs/remotes/origin/todo
393 -------------------------------------------------
395 The first argument, "origin", just tells git to fetch from the
396 repository you originally cloned from. The second argument tells git
397 to fetch the branch named "todo" from the remote repository, and to
398 store it locally under the name refs/remotes/origin/todo; as we saw
399 above, remote-tracking branches are stored under
400 refs/remotes/<name-of-repository>/<name-of-branch>.
402 You can also fetch branches from other repositories; so
404 -------------------------------------------------
405 $ git fetch git://example.com/proj.git master:refs/remotes/example/master
406 -------------------------------------------------
408 will create a new reference named "refs/remotes/example/master" and
409 store in it the branch named "master" from the repository at the
410 given URL. If you already have a branch named
411 "refs/remotes/example/master", it will attempt to "fast-forward" to
412 the commit given by example.com's master branch. So next we explain
413 what a fast-forward is:
416 Understanding git history: fast-forwards
417 ----------------------------------------
419 In the previous example, when updating an existing branch, "git
420 fetch" checks to make sure that the most recent commit on the remote
421 branch is a descendant of the most recent commit on your copy of the
422 branch before updating your copy of the branch to point at the new
423 commit. Git calls this process a "fast forward".
425 A fast forward looks something like this:
427 o--o--o--o <-- old head of the branch
429 o--o--o <-- new head of the branch
432 In some cases it is possible that the new head will *not* actually be
433 a descendant of the old head. For example, the developer may have
434 realized she made a serious mistake, and decided to backtrack,
435 resulting in a situation like:
437 o--o--o--o--a--b <-- old head of the branch
439 o--o--o <-- new head of the branch
443 In this case, "git fetch" will fail, and print out a warning.
445 In that case, you can still force git to update to the new head, as
446 described in the following section. However, note that in the
447 situation above this may mean losing the commits labeled "a" and "b",
448 unless you've already created a reference of your own pointing to
451 Forcing git fetch to do non-fast-forward updates
452 ------------------------------------------------
454 If git fetch fails because the new head of a branch is not a
455 descendant of the old head, you may force the update with:
457 -------------------------------------------------
458 $ git fetch git://example.com/proj.git +master:refs/remotes/example/master
459 -------------------------------------------------
461 Note the addition of the "+" sign. Be aware that commits which the
462 old version of example/master pointed at may be lost, as we saw in
463 the previous section.
465 Configuring remote branches
466 ---------------------------
468 We saw above that "origin" is just a shortcut to refer to the
469 repository which you originally cloned from. This information is
470 stored in git configuration variables, which you can see using
471 gitlink:git-repo-config[1]:
473 -------------------------------------------------
475 core.repositoryformatversion=0
477 core.logallrefupdates=true
478 remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
479 remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
480 branch.master.remote=origin
481 branch.master.merge=refs/heads/master
482 -------------------------------------------------
484 If there are other repositories that you also use frequently, you can
485 create similar configuration options to save typing; for example,
488 -------------------------------------------------
489 $ git repo-config remote.example.url=git://example.com/proj.git
490 -------------------------------------------------
492 then the following two commands will do the same thing:
494 -------------------------------------------------
495 $ git fetch git://example.com/proj.git master:refs/remotes/example/master
496 $ git fetch example master:refs/remotes/example/master
497 -------------------------------------------------
499 Even better, if you add one more option:
501 -------------------------------------------------
502 $ git repo-config remote.example.fetch=master:refs/remotes/example/master
503 -------------------------------------------------
505 then the following commands will all do the same thing:
507 -------------------------------------------------
508 $ git fetch git://example.com/proj.git master:ref/remotes/example/master
509 $ git fetch example master:ref/remotes/example/master
510 $ git fetch example example/master
512 -------------------------------------------------
514 You can also add a "+" to force the update each time:
516 -------------------------------------------------
517 $ git repo-config +master:ref/remotes/example/master
518 -------------------------------------------------
520 Don't do this unless you're sure you won't mind "git fetch" possibly
521 throwing away commits on mybranch.
523 Also note that all of the above configuration can be performed by
524 directly editing the file .git/config instead of using
525 gitlink:git-repo-config[1].
527 See gitlink:git-repo-config[1] for more details on the configuration
528 options mentioned above.
530 Exploring git history
531 =====================
533 Git is best thought of as a tool for storing the history of a
534 collection of files. It does this by storing compressed snapshots of
535 the contents of a file heirarchy, together with "commits" which show
536 the relationships between these snapshots.
538 Git provides extremely flexible and fast tools for exploring the
539 history of a project.
541 We start with one specialized tool which is useful for finding the
542 commit that introduced a bug into a project.
544 How to use bisect to find a regression
545 --------------------------------------
547 Suppose version 2.6.18 of your project worked, but the version at
548 "master" crashes. Sometimes the best way to find the cause of such a
549 regression is to perform a brute-force search through the project's
550 history to find the particular commit that caused the problem. The
551 gitlink:git-bisect[1] command can help you do this:
553 -------------------------------------------------
555 $ git bisect good v2.6.18
556 $ git bisect bad master
557 Bisecting: 3537 revisions left to test after this
558 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
559 -------------------------------------------------
561 If you run "git branch" at this point, you'll see that git has
562 temporarily moved you to a new branch named "bisect". This branch
563 points to a commit (with commit id 65934...) that is reachable from
564 v2.6.19 but not from v2.6.18. Compile and test it, and see whether
565 it crashes. Assume it does crash. Then:
567 -------------------------------------------------
569 Bisecting: 1769 revisions left to test after this
570 [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
571 -------------------------------------------------
573 checks out an older version. Continue like this, telling git at each
574 stage whether the version it gives you is good or bad, and notice
575 that the number of revisions left to test is cut approximately in
578 After about 13 tests (in this case), it will output the commit id of
579 the guilty commit. You can then examine the commit with
580 gitlink:git-show[1], find out who wrote it, and mail them your bug
581 report with the commit id. Finally, run
583 -------------------------------------------------
585 -------------------------------------------------
587 to return you to the branch you were on before and delete the
588 temporary "bisect" branch.
590 Note that the version which git-bisect checks out for you at each
591 point is just a suggestion, and you're free to try a different
592 version if you think it would be a good idea. For example,
593 occasionally you may land on a commit that broke something unrelated;
596 -------------------------------------------------
597 $ git bisect-visualize
598 -------------------------------------------------
600 which will run gitk and label the commit it chose with a marker that
601 says "bisect". Chose a safe-looking commit nearby, note its commit
602 id, and check it out with:
604 -------------------------------------------------
605 $ git reset --hard fb47ddb2db...
606 -------------------------------------------------
608 then test, run "bisect good" or "bisect bad" as appropriate, and
614 We have seen several ways of naming commits already:
617 - branch name: refers to the commit at the head of the given
619 - tag name: refers to the commit pointed to by the given tag
620 (we've seen branches and tags are special cases of
621 <<how-git-stores-references,references>>).
622 - HEAD: refers to the head of the current branch
624 There are many more; see the "SPECIFYING REVISION" section of the
625 gitlink:git-rev-parse[1] man page for the complete list of ways to
626 name revisions. Some examples:
628 -------------------------------------------------
629 $ git show fb47ddb2 # the first few characters of the SHA1 id
630 # are usually enough to specify it uniquely
631 $ git show HEAD^ # the parent of the HEAD commit
632 $ git show HEAD^^ # the grandparent
633 $ git show HEAD~4 # the great-great-grandparent
634 -------------------------------------------------
636 Recall that merge commits may have more than one parent; by default,
637 ^ and ~ follow the first parent listed in the commit, but you can
640 -------------------------------------------------
641 $ git show HEAD^1 # show the first parent of HEAD
642 $ git show HEAD^2 # show the second parent of HEAD
643 -------------------------------------------------
645 In addition to HEAD, there are several other special names for
648 Merges (to be discussed later), as well as operations such as
649 git-reset, which change the currently checked-out commit, generally
650 set ORIG_HEAD to the value HEAD had before the current operation.
652 The git-fetch operation always stores the head of the last fetched
653 branch in FETCH_HEAD. For example, if you run git fetch without
654 specifying a local branch as the target of the operation
656 -------------------------------------------------
657 $ git fetch git://example.com/proj.git theirbranch
658 -------------------------------------------------
660 the fetched commits will still be available from FETCH_HEAD.
662 When we discuss merges we'll also see the special name MERGE_HEAD,
663 which refers to the other branch that we're merging in to the current
666 The gitlink:git-rev-parse[1] command is a low-level command that is
667 occasionally useful for translating some name for a commit to the SHA1 id for
670 -------------------------------------------------
671 $ git rev-parse origin
672 e05db0fd4f31dde7005f075a84f96b360d05984b
673 -------------------------------------------------
678 We can also create a tag to refer to a particular commit; after
681 -------------------------------------------------
682 $ git-tag stable-1 1b2e1d63ff
683 -------------------------------------------------
685 You can use stable-1 to refer to the commit 1b2e1d63ff.
687 This creates a "lightweight" tag. If the tag is a tag you wish to
688 share with others, and possibly sign cryptographically, then you
689 should create a tag object instead; see the gitlink:git-tag[1] man
695 The gitlink:git-log[1] command can show lists of commits. On its
696 own, it shows all commits reachable from the parent commit; but you
697 can also make more specific requests:
699 -------------------------------------------------
700 $ git log v2.5.. # commits since (not reachable from) v2.5
701 $ git log test..master # commits reachable from master but not test
702 $ git log master..test # ...reachable from test but not master
703 $ git log master...test # ...reachable from either test or master,
705 $ git log --since="2 weeks ago" # commits from the last 2 weeks
706 $ git log Makefile # commits which modify Makefile
707 $ git log fs/ # ... which modify any file under fs/
708 $ git log -S'foo()' # commits which add or remove any file data
709 # matching the string 'foo()'
710 -------------------------------------------------
712 And of course you can combine all of these; the following finds
713 commits since v2.5 which touch the Makefile or any file under fs:
715 -------------------------------------------------
716 $ git log v2.5.. Makefile fs/
717 -------------------------------------------------
719 You can also ask git log to show patches:
721 -------------------------------------------------
723 -------------------------------------------------
725 See the "--pretty" option in the gitlink:git-log[1] man page for more
728 Note that git log starts with the most recent commit and works
729 backwards through the parents; however, since git history can contain
730 multiple independant lines of development, the particular order that
731 commits are listed in may be somewhat arbitrary.
736 You can generate diffs between any two versions using
739 -------------------------------------------------
740 $ git diff master..test
741 -------------------------------------------------
743 Sometimes what you want instead is a set of patches:
745 -------------------------------------------------
746 $ git format-patch master..test
747 -------------------------------------------------
749 will generate a file with a patch for each commit reachable from test
750 but not from master. Note that if master also has commits which are
751 not reachable from test, then the combined result of these patches
752 will not be the same as the diff produced by the git-diff example.
754 Viewing old file versions
755 -------------------------
757 You can always view an old version of a file by just checking out the
758 correct revision first. But sometimes it is more convenient to be
759 able to view an old version of a single file without checking
760 anything out; this command does that:
762 -------------------------------------------------
763 $ git show v2.5:fs/locks.c
764 -------------------------------------------------
766 Before the colon may be anything that names a commit, and after it
767 may be any path to a file tracked by git.
772 Check whether two branches point at the same history
773 ----------------------------------------------------
775 Suppose you want to check whether two branches point at the same point
778 -------------------------------------------------
779 $ git diff origin..master
780 -------------------------------------------------
782 will tell you whether the contents of the project are the same at the two
783 branches; in theory, however, it's possible that the same project contents
784 could have been arrived at by two different historical routes. You could
785 compare the SHA1 id's:
787 -------------------------------------------------
788 $ git rev-list origin
789 e05db0fd4f31dde7005f075a84f96b360d05984b
790 $ git rev-list master
791 e05db0fd4f31dde7005f075a84f96b360d05984b
792 -------------------------------------------------
794 Or you could recall that the ... operator selects all commits contained
795 reachable from either one reference or the other but not both: so
797 -------------------------------------------------
798 $ git log origin...master
799 -------------------------------------------------
801 will return no commits when the two branches are equal.
803 Check which tagged version a given fix was first included in
804 ------------------------------------------------------------
806 Suppose you know that a critical fix made it into the linux kernel with commit
807 e05db0fd... You'd like to find which kernel version that commit first made it
813 Telling git your name
814 ---------------------
816 Before creating any commits, you should introduce yourself to git. The
817 easiest way to do so is:
819 ------------------------------------------------
820 $ cat >~/.gitconfig <<\EOF
822 name = Your Name Comes Here
823 email = you@yourdomain.example.com
825 ------------------------------------------------
828 Creating a new repository
829 -------------------------
831 Creating a new repository from scratch is very easy:
833 -------------------------------------------------
837 -------------------------------------------------
839 If you have some initial content (say, a tarball):
841 -------------------------------------------------
842 $ tar -xzvf project.tar.gz
845 $ git add . # include everything below ./ in the first commit:
847 -------------------------------------------------
849 [[how-to-make-a-commit]]
853 Creating a new commit takes three steps:
855 1. Making some changes to the working directory using your
857 2. Telling git about your changes.
858 3. Creating the commit using the content you told git about
861 In practice, you can interleave and repeat steps 1 and 2 as many
862 times as you want: in order to keep track of what you want committed
863 at step 3, git maintains a snapshot of the tree's contents in a
864 special staging area called "the index."
866 By default, the content of the index is identical to that of the
867 HEAD. The command "git diff --cached" shows the difference between
868 HEAD and the index, so you should no output from that command.
870 Modifying the index is easy:
872 To update the index with the new contents of a modified file, use
874 -------------------------------------------------
875 $ git add path/to/file
876 -------------------------------------------------
878 To add the contents of a new file to the index, use
880 -------------------------------------------------
881 $ git add path/to/file
882 -------------------------------------------------
884 To remove a file from the index that you've removed from the working
887 -------------------------------------------------
888 $ git rm path/to/file
889 -------------------------------------------------
891 After each step you can verify that
893 -------------------------------------------------
895 -------------------------------------------------
897 always shows the difference between the HEAD and the index file--this
898 is what you'd commit if you created the commit now--and that
900 -------------------------------------------------
902 -------------------------------------------------
904 shows the difference between the working tree and the index file.
906 Note that "git add" always adds just the current contents of a file
907 to the index; further changes to the same file will be ignored unless
908 you run git-add on the file again.
910 When you're ready, just run
912 -------------------------------------------------
914 -------------------------------------------------
916 and git will prompt you for a commit message and then create the new
917 commmit. Check to make sure it looks like what you expected with
919 -------------------------------------------------
921 -------------------------------------------------
923 As a special shortcut,
925 -------------------------------------------------
927 -------------------------------------------------
929 will update the index with any files that you've modified or removed
930 and create a commit, all in one step.
932 A number of commands are useful for keeping track of what you're
935 -------------------------------------------------
936 $ git diff --cached # difference between HEAD and the index; what
937 # would be commited if you ran "commit" now.
938 $ git diff # difference between the index file and your
939 # working directory; changes that would not
940 # be included if you ran "commit" now.
941 $ git status # a brief per-file summary of the above.
942 -------------------------------------------------
944 creating good commit messages
945 -----------------------------
947 Though not required, it's a good idea to begin the commit message
948 with a single short (less than 50 character) line summarizing the
949 change, followed by a blank line and then a more thorough
950 description. Tools that turn commits into email, for example, use
951 the first line on the Subject line and the rest of the commit in the
957 You can rejoin two diverging branches of development using
958 gitlink:git-merge[1]:
960 -------------------------------------------------
961 $ git merge branchname
962 -------------------------------------------------
964 merges the development in the branch "branchname" into the current
965 branch. If there are conflicts--for example, if the same file is
966 modified in two different ways in the remote branch and the local
967 branch--then you are warned; the output may look something like this:
969 -------------------------------------------------
971 Trying really trivial in-index merge...
972 fatal: Merge requires file-level merging
974 Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
978 found 1 common ancestor(s):
980 Auto-merging file.txt
981 CONFLICT (content): Merge conflict in file.txt
982 Automatic merge failed; fix conflicts and then commit the result.
983 -------------------------------------------------
985 Conflict markers are left in the problematic files, and after
986 you resolve the conflicts manually, you can update the index
987 with the contents and run git commit, as you normally would when
990 If you examine the resulting commit using gitk, you will see that it
991 has two parents, one pointing to the top of the current branch, and
992 one to the top of the other branch.
996 [[resolving-a-merge]]
1000 When a merge isn't resolved automatically, git leaves the index and
1001 the working tree in a special state that gives you all the
1002 information you need to help resolve the merge.
1004 Files with conflicts are marked specially in the index, so until you
1005 resolve the problem and update the index, git commit will fail:
1007 -------------------------------------------------
1009 file.txt: needs merge
1010 -------------------------------------------------
1012 Also, git status will list those files as "unmerged".
1014 All of the changes that git was able to merge automatically are
1015 already added to the index file, so gitlink:git-diff[1] shows only
1016 the conflicts. Also, it uses a somewhat unusual syntax:
1018 -------------------------------------------------
1021 index 802992c,2b60207..0000000
1024 @@@ -1,1 -1,1 +1,5 @@@
1025 ++<<<<<<< HEAD:file.txt
1029 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1030 -------------------------------------------------
1032 Recall that the commit which will be commited after we resolve this
1033 conflict will have two parents instead of the usual one: one parent
1034 will be HEAD, the tip of the current branch; the other will be the
1035 tip of the other branch, which is stored temporarily in MERGE_HEAD.
1037 The diff above shows the differences between the working-tree version
1038 of file.txt and two previous version: one version from HEAD, and one
1039 from MERGE_HEAD. So instead of preceding each line by a single "+"
1040 or "-", it now uses two columns: the first column is used for
1041 differences between the first parent and the working directory copy,
1042 and the second for differences between the second parent and the
1043 working directory copy. Thus after resolving the conflict in the
1044 obvious way, the diff will look like:
1046 -------------------------------------------------
1049 index 802992c,2b60207..0000000
1052 @@@ -1,1 -1,1 +1,1 @@@
1056 -------------------------------------------------
1058 This shows that our resolved version deleted "Hello world" from the
1059 first parent, deleted "Goodbye" from the second parent, and added
1060 "Goodbye world", which was previously absent from both.
1062 The gitlink:git-log[1] command also provides special help for merges:
1064 -------------------------------------------------
1066 -------------------------------------------------
1068 This will list all commits which exist only on HEAD or on MERGE_HEAD,
1069 and which touch an unmerged file.
1071 We can now add the resolved version to the index and commit:
1073 -------------------------------------------------
1076 -------------------------------------------------
1078 Note that the commit message will already be filled in for you with
1079 some information about the merge. Normally you can just use this
1080 default message unchanged, but you may add additional commentary of
1081 your own if desired.
1087 If you get stuck and decide to just give up and throw the whole mess
1088 away, you can always return to the pre-merge state with
1090 -------------------------------------------------
1091 $ git reset --hard HEAD
1092 -------------------------------------------------
1094 Or, if you've already commited the merge that you want to throw away,
1096 -------------------------------------------------
1097 $ git reset --hard HEAD^
1098 -------------------------------------------------
1100 However, this last command can be dangerous in some cases--never
1101 throw away a commit you have already committed if that commit may
1102 itself have been merged into another branch, as doing so may confuse
1108 There is one special case not mentioned above, which is treated
1109 differently. Normally, a merge results in a merge commit, with two
1110 parents, one pointing at each of the two lines of development that
1113 However, if one of the two lines of development is completely
1114 contained within the other--so every commit present in the one is
1115 already contained in the other--then git just performs a
1116 <<fast-forwards,fast forward>>; the head of the current branch is
1117 moved forward to point at the head of the merged-in branch, without
1118 any new commits being created.
1123 If you've messed up the working tree, but haven't yet committed your
1124 mistake, you can return the entire working tree to the last committed
1127 -------------------------------------------------
1128 $ git reset --hard HEAD
1129 -------------------------------------------------
1131 If you make a commit that you later wish you hadn't, there are two
1132 fundamentally different ways to fix the problem:
1134 1. You can create a new commit that undoes whatever was done
1135 by the previous commit. This is the correct thing if your
1136 mistake has already been made public.
1138 2. You can go back and modify the old commit. You should
1139 never do this if you have already made the history public;
1140 git does not normally expect the "history" of a project to
1141 change, and cannot correctly perform repeated merges from
1142 a branch that has had its history changed.
1144 Fixing a mistake with a new commit
1145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1147 Creating a new commit that reverts an earlier change is very easy;
1148 just pass the gitlink:git-revert[1] command a reference to the bad
1149 commit; for example, to revert the most recent commit:
1151 -------------------------------------------------
1153 -------------------------------------------------
1155 This will create a new commit which undoes the change in HEAD. You
1156 will be given a chance to edit the commit message for the new commit.
1158 You can also revert an earlier change, for example, the next-to-last:
1160 -------------------------------------------------
1162 -------------------------------------------------
1164 In this case git will attempt to undo the old change while leaving
1165 intact any changes made since then. If more recent changes overlap
1166 with the changes to be reverted, then you will be asked to fix
1167 conflicts manually, just as in the case of <<resolving-a-merge,
1168 resolving a merge>>.
1170 Fixing a mistake by editing history
1171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1173 If the problematic commit is the most recent commit, and you have not
1174 yet made that commit public, then you may just
1175 <<undoing-a-merge,destroy it using git-reset>>.
1178 can edit the working directory and update the index to fix your
1179 mistake, just as if you were going to <<how-to-make-a-commit,create a
1180 new commit>>, then run
1182 -------------------------------------------------
1183 $ git commit --amend
1184 -------------------------------------------------
1186 which will replace the old commit by a new commit incorporating your
1187 changes, giving you a chance to edit the old commit message first.
1189 Again, you should never do this to a commit that may already have
1190 been merged into another branch; use gitlink:git-revert[1] instead in
1193 It is also possible to edit commits further back in the history, but
1194 this is an advanced topic to be left for
1195 <<cleaning-up-history,another chapter>>.
1197 Checking out an old version of a file
1198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1200 In the process of undoing a previous bad change, you may find it
1201 useful to check out an older version of a particular file using
1202 gitlink:git-checkout[1]. We've used git checkout before to switch
1203 branches, but it has quite different behavior if it is given a path
1206 -------------------------------------------------
1207 $ git checkout HEAD^ path/to/file
1208 -------------------------------------------------
1210 replaces path/to/file by the contents it had in the commit HEAD^, and
1211 also updates the index to match. It does not change branches.
1213 If you just want to look at an old version of the file, without
1214 modifying the working directory, you can do that with
1215 gitlink:git-show[1]:
1217 -------------------------------------------------
1218 $ git show HEAD^ path/to/file
1219 -------------------------------------------------
1221 which will display the given version of the file.
1223 Ensuring good performance
1224 -------------------------
1226 On large repositories, git depends on compression to keep the history
1227 information from taking up to much space on disk or in memory.
1229 This compression is not performed automatically. Therefore you
1230 should occasionally run
1232 -------------------------------------------------
1234 -------------------------------------------------
1236 to recompress the archive and to prune any commits which are no
1237 longer referred to anywhere. This can be very time-consuming, and
1238 you should not modify the repository while it is working, so you
1239 should run it while you are not working.
1241 Sharing development with others
1242 ===============================
1244 [[getting-updates-with-git-pull]]
1245 Getting updates with git pull
1246 -----------------------------
1248 After you clone a repository and make a few changes of your own, you
1249 may wish to check the original repository for updates and merge them
1252 We have already seen <<Updating-a-repository-with-git-fetch,how to
1253 keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1254 and how to merge two branches. So you can merge in changes from the
1255 original repository's master branch with:
1257 -------------------------------------------------
1259 $ git merge origin/master
1260 -------------------------------------------------
1262 However, the gitlink:git-pull[1] command provides a way to do this in
1265 -------------------------------------------------
1266 $ git pull origin master
1267 -------------------------------------------------
1269 In fact, "origin" is normally the default repository to pull from,
1270 and the default branch is normally the HEAD of the remote repository,
1271 so often you can accomplish the above with just
1273 -------------------------------------------------
1275 -------------------------------------------------
1277 See the descriptions of the branch.<name>.remote and
1278 branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1279 how to control these defaults depending on the current branch.
1281 In addition to saving you keystrokes, "git pull" also helps you by
1282 producing a default commit message documenting the branch and
1283 repository that you pulled from.
1285 (But note that no such commit will be created in the case of a
1286 <<fast-forwards,fast forward>>; instead, your branch will just be
1287 updated to point to the latest commit from the upstream branch).
1289 The git-pull command can also be given "." as the "remote" repository, in
1290 which case it just merges in a branch from the current repository; so
1293 -------------------------------------------------
1296 -------------------------------------------------
1298 are roughly equivalent. The former is actually very commonly used.
1300 Submitting patches to a project
1301 -------------------------------
1303 If you just have a few changes, the simplest way to submit them may
1304 just be to send them as patches in email:
1306 First, use gitlink:git-format-patches[1]; for example:
1308 -------------------------------------------------
1309 $ git format-patches origin
1310 -------------------------------------------------
1312 will produce a numbered series of files in the current directory, one
1313 for each patch in the current branch but not in origin/HEAD.
1315 You can then import these into your mail client and send them by
1316 hand. However, if you have a lot to send at once, you may prefer to
1317 use the gitlink:git-send-email[1] script to automate the process.
1318 Consult the mailing list for your project first to determine how they
1319 prefer such patches be handled.
1321 Importing patches to a project
1322 ------------------------------
1324 Git also provides a tool called gitlink:git-am[1] (am stands for
1325 "apply mailbox"), for importing such an emailed series of patches.
1326 Just save all of the patch-containing messages, in order, into a
1327 single mailbox file, say "patches.mbox", then run
1329 -------------------------------------------------
1330 $ git am patches.mbox
1331 -------------------------------------------------
1333 Git will apply each patch in order; if any conflicts are found, it
1334 will stop, and you can fix the conflicts as described in
1335 "<<resolving-a-merge,Resolving a merge>>". Once the index is updated
1336 with the results of the conflict resolution, instead of creating a
1337 new commit, just run
1339 -------------------------------------------------
1341 -------------------------------------------------
1343 and git will create the commit for you and continue applying the
1344 remaining patches from the mailbox.
1346 The final result will be a series of commits, one for each patch in
1347 the original mailbox, with authorship and commit log message each
1348 taken from the message containing each patch.
1350 [[setting-up-a-public-repository]]
1351 Setting up a public repository
1352 ------------------------------
1354 Another way to submit changes to a project is to simply tell the
1355 maintainer of that project to pull from your repository, exactly as
1356 you did in the section "<<getting-updates-with-git-pull, Getting
1357 updates with git pull>>".
1359 If you and maintainer both have accounts on the same machine, then
1360 then you can just pull changes from each other's repositories
1361 directly; note that all of the command (gitlink:git-clone[1],
1362 git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1363 will also accept a local file patch; so, for example, you can
1366 -------------------------------------------------
1367 $ git clone /path/to/repository
1368 $ git pull /path/to/other/repository
1369 -------------------------------------------------
1371 If this sort of setup is inconvenient or impossible, another (more
1372 common) option is to set up a public repository on a public server.
1373 This also allows you to cleanly separate private work in progress
1374 from publicly visible work.
1376 You will continue to do your day-to-day work in your personal
1377 repository, but periodically "push" changes from your personal
1378 repository into your public repository, allowing other developers to
1379 pull from that repository. So the flow of changes, in a situation
1380 where there is one other developer with a public repository, looks
1384 your personal repo ------------------> your public repo
1387 | you pull | they pull
1391 their public repo <------------------- their repo
1393 Now, assume your personal repository is in the directory ~/proj. We
1394 first create a new clone of the repository:
1396 -------------------------------------------------
1397 $ git clone --bare proj-clone.git
1398 -------------------------------------------------
1400 The resulting directory proj-clone.git will contains a "bare" git
1401 repository--it is just the contents of the ".git" directory, without
1402 a checked-out copy of a working directory.
1404 Next, copy proj-clone.git to the server where you plan to host the
1405 public repository. You can use scp, rsync, or whatever is most
1408 If somebody else maintains the public server, they may already have
1409 set up a git service for you, and you may skip to the section
1410 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
1411 repository>>", below.
1413 Otherwise, the following sections explain how to export your newly
1414 created public repository:
1416 [[exporting-via-http]]
1417 Exporting a git repository via http
1418 -----------------------------------
1420 The git protocol gives better performance and reliability, but on a
1421 host with a web server set up, http exports may be simpler to set up.
1423 All you need to do is place the newly created bare git repository in
1424 a directory that is exported by the web server, and make some
1425 adjustments to give web clients some extra information they need:
1427 -------------------------------------------------
1428 $ mv proj.git /home/you/public_html/proj.git
1430 $ git update-server-info
1431 $ chmod a+x hooks/post-update
1432 -------------------------------------------------
1434 (For an explanation of the last two lines, see
1435 gitlink:git-update-server-info[1], and the documentation
1436 link:hooks.txt[Hooks used by git].)
1438 Advertise the url of proj.git. Anybody else should then be able to
1439 clone or pull from that url, for example with a commandline like:
1441 -------------------------------------------------
1442 $ git clone http://yourserver.com/~you/proj.git
1443 -------------------------------------------------
1446 link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1447 for a slightly more sophisticated setup using WebDAV which also
1448 allows pushing over http.)
1450 [[exporting-via-git]]
1451 Exporting a git repository via the git protocol
1452 -----------------------------------------------
1454 This is the preferred method.
1456 For now, we refer you to the gitlink:git-daemon[1] man page for
1457 instructions. (See especially the examples section.)
1459 [[pushing-changes-to-a-public-repository]]
1460 Pushing changes to a public repository
1461 --------------------------------------
1463 Note that the two techniques outline above (exporting via
1464 <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1465 maintainers to fetch your latest changes, but they do not allow write
1466 access, which you will need to update the public repository with the
1467 latest changes created in your private repository.
1469 The simplest way to do this is using gitlink:git-push[1] and ssh; to
1470 update the remote branch named "master" with the latest state of your
1471 branch named "master", run
1473 -------------------------------------------------
1474 $ git push ssh://yourserver.com/~you/proj.git master:master
1475 -------------------------------------------------
1479 -------------------------------------------------
1480 $ git push ssh://yourserver.com/~you/proj.git master
1481 -------------------------------------------------
1483 As with git-fetch, git-push will complain if this does not result in
1484 a <<fast-forwards,fast forward>>. Normally this is a sign of
1485 something wrong. However, if you are sure you know what you're
1486 doing, you may force git-push to perform the update anyway by
1487 proceeding the branch name by a plus sign:
1489 -------------------------------------------------
1490 $ git push ssh://yourserver.com/~you/proj.git +master
1491 -------------------------------------------------
1493 As with git-fetch, you may also set up configuration options to
1494 save typing; so, for example, after
1496 -------------------------------------------------
1497 $ cat >.git/config <<EOF
1498 [remote "public-repo"]
1499 url = ssh://yourserver.com/~you/proj.git
1501 -------------------------------------------------
1503 you should be able to perform the above push with just
1505 -------------------------------------------------
1506 $ git push public-repo master
1507 -------------------------------------------------
1509 See the explanations of the remote.<name>.url, branch.<name>.remote,
1510 and remote.<name>.push options in gitlink:git-repo-config[1] for
1513 Setting up a shared repository
1514 ------------------------------
1516 Another way to collaborate is by using a model similar to that
1517 commonly used in CVS, where several developers with special rights
1518 all push to and pull from a single shared repository. See
1519 link:cvs-migration.txt[git for CVS users] for instructions on how to
1522 Allow web browsing of a repository
1523 ----------------------------------
1525 TODO: Brief setup-instructions for gitweb
1530 TODO: topic branches, typical roles as in everyday.txt, ?
1533 Working with other version control systems
1534 ==========================================
1536 TODO: CVS, Subversion, series-of-release-tarballs, ?
1538 [[cleaning-up-history]]
1539 Rewriting history and maintaining patch series
1540 ==============================================
1542 Normally commits are only added to a project, never taken away or
1543 replaced. Git is designed with this assumption, and violating it will
1544 cause git's merge machinery (for example) to do the wrong thing.
1546 However, there is a situation in which it can be useful to violate this
1549 Creating the perfect patch series
1550 ---------------------------------
1552 Suppose you are a contributor to a large project, and you want to add a
1553 complicated feature, and to present it to the other developers in a way
1554 that makes it easy for them to read your changes, verify that they are
1555 correct, and understand why you made each change.
1557 If you present all of your changes as a single patch (or commit), they may
1558 find it is too much to digest all at once.
1560 If you present them with the entire history of your work, complete with
1561 mistakes, corrections, and dead ends, they may be overwhelmed.
1563 So the ideal is usually to produce a series of patches such that:
1565 1. Each patch can be applied in order.
1567 2. Each patch includes a single logical change, together with a
1568 message explaining the change.
1570 3. No patch introduces a regression: after applying any initial
1571 part of the series, the resulting project still compiles and
1572 works, and has no bugs that it didn't have before.
1574 4. The complete series produces the same end result as your own
1575 (probably much messier!) development process did.
1577 We will introduce some tools that can help you do this, explain how to use
1578 them, and then explain some of the problems that can arise because you are
1581 Keeping a patch series up to date using git-rebase
1582 --------------------------------------------------
1584 Suppose you have a series of commits in a branch "mywork", which
1585 originally branched off from "origin".
1587 Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1588 and created some commits on top of it:
1590 -------------------------------------------------
1591 $ git checkout -b mywork origin
1597 -------------------------------------------------
1599 You have performed no merges into mywork, so it is just a simple linear
1600 sequence of patches on top of "origin":
1607 Some more interesting work has been done in the upstream project, and
1608 "origin" has advanced:
1610 o--o--O--o--o--o <-- origin
1614 At this point, you could use "pull" to merge your changes back in;
1615 the result would create a new merge commit, like this:
1618 o--o--O--o--o--o <-- origin
1620 a--b--c--m <-- mywork
1622 However, if you prefer to keep the history in mywork a simple series of
1623 commits without any merges, you may instead choose to use
1624 gitlink:git-rebase[1]:
1626 -------------------------------------------------
1627 $ git checkout mywork
1629 -------------------------------------------------
1631 This will remove each of your commits from mywork, temporarily saving them
1632 as patches (in a directory named ".dotest"), update mywork to point at the
1633 latest version of origin, then apply each of the saved patches to the new
1634 mywork. The result will look like:
1637 o--o--O--o--o--o <-- origin
1639 a'--b'--c' <-- mywork
1641 In the process, it may discover conflicts. In that case it will stop and
1642 allow you to fix the conflicts as described in
1643 "<<resolving-a-merge,Resolving a merge>>".
1645 XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1648 Once the index is updated with
1649 the results of the conflict resolution, instead of creating a new commit,
1652 -------------------------------------------------
1653 $ git rebase --continue
1654 -------------------------------------------------
1656 and git will continue applying the rest of the patches.
1658 At any point you may use the --abort option to abort this process and
1659 return mywork to the state it had before you started the rebase:
1661 -------------------------------------------------
1662 $ git rebase --abort
1663 -------------------------------------------------
1665 Reordering or selecting from a patch series
1666 -------------------------------------------
1668 Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1669 you to apply the change introduced by that commit and create a new commit
1672 This can be useful for modifying a patch series.
1679 There are numerous other tools, such as stgit, which exist for the purpose
1680 of maintianing a patch series. These are out of the scope of this manual.
1682 Problems with rewriting history
1683 -------------------------------
1685 The primary problem with rewriting the history of a branch has to do with
1694 Architectural overview
1695 ----------------------
1697 TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1699 Glossary of git terms
1700 =====================
1702 include::glossary.txt[]
1704 Notes and todo list for this manual
1705 ===================================
1707 This is a work in progress.
1709 The basic requirements:
1710 - It must be readable in order, from beginning to end, by someone
1711 intelligent with a basic grasp of the unix commandline, but
1712 without any special knowledge of git. If necessary, any other
1713 prerequisites should be specifically mentioned as they arise.
1714 - Whenever possible, section headings should clearly describe the
1715 task they explain how to do, in language that requires no more
1716 knowledge than necessary: for example, "importing patches into a
1717 project" rather than "the git-am command"
1719 Think about how to create a clear chapter dependency graph that will
1720 allow people to get to important topics without necessarily reading
1721 everything in between.
1723 Scan Documentation/ for other stuff left out; in particular:
1730 Scan email archives for other stuff left out
1732 Scan man pages to see if any assume more background than this manual
1735 Simplify beginning by suggesting disconnected head instead of temporary
1738 Explain how to refer to file stages in the "how to resolve a merge"
1739 section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The
1740 "git ls-files --unmerged --stage" thing is sorta useful too, actually. And
1741 note gitk --merge. Also what's easiest way to see common merge base?
1743 Add more good examples. Entire sections of just cookbook examples might
1744 be a good idea; maybe make an "advanced examples" section a standard
1745 end-of-chapter section?
1747 Include cross-references to the glossary, where appropriate.
1750 reflogs, git reflog expire
1751 shallow clones?? See draft 1.5.0 release notes for some documentation.