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 40-hexdigit 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 remote.example.fetch +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:
616 - 40-hexdigit SHA1 id
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 REVISIONS" 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
783 two branches; in theory, however, it's possible that the same project
784 contents could have been arrived at by two different historical
785 routes. You could 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
795 contained reachable from either one reference or the other but not
798 -------------------------------------------------
799 $ git log origin...master
800 -------------------------------------------------
802 will return no commits when the two branches are equal.
804 Check which tagged version a given fix was first included in
805 ------------------------------------------------------------
807 Suppose you know that the commit e05db0fd fixed a certain problem.
808 You'd like to find the earliest tagged release that contains that
811 Of course, there may be more than one answer--if the history branched
812 after commit e05db0fd, then there could be multiple "earliest" tagged
815 You could just visually inspect the commits since e05db0fd:
817 -------------------------------------------------
819 -------------------------------------------------
826 Telling git your name
827 ---------------------
829 Before creating any commits, you should introduce yourself to git. The
830 easiest way to do so is:
832 ------------------------------------------------
833 $ cat >~/.gitconfig <<\EOF
835 name = Your Name Comes Here
836 email = you@yourdomain.example.com
838 ------------------------------------------------
841 Creating a new repository
842 -------------------------
844 Creating a new repository from scratch is very easy:
846 -------------------------------------------------
850 -------------------------------------------------
852 If you have some initial content (say, a tarball):
854 -------------------------------------------------
855 $ tar -xzvf project.tar.gz
858 $ git add . # include everything below ./ in the first commit:
860 -------------------------------------------------
862 [[how-to-make-a-commit]]
866 Creating a new commit takes three steps:
868 1. Making some changes to the working directory using your
870 2. Telling git about your changes.
871 3. Creating the commit using the content you told git about
874 In practice, you can interleave and repeat steps 1 and 2 as many
875 times as you want: in order to keep track of what you want committed
876 at step 3, git maintains a snapshot of the tree's contents in a
877 special staging area called "the index."
879 At the beginning, the content of the index will be identical to
880 that of the HEAD. The command "git diff --cached", which shows
881 the difference between the HEAD and the index, should therefore
882 produce no output at that point.
884 Modifying the index is easy:
886 To update the index with the new contents of a modified file, use
888 -------------------------------------------------
889 $ git add path/to/file
890 -------------------------------------------------
892 To add the contents of a new file to the index, use
894 -------------------------------------------------
895 $ git add path/to/file
896 -------------------------------------------------
898 To remove a file from the index and from the working tree,
900 -------------------------------------------------
901 $ git rm path/to/file
902 -------------------------------------------------
904 After each step you can verify that
906 -------------------------------------------------
908 -------------------------------------------------
910 always shows the difference between the HEAD and the index file--this
911 is what you'd commit if you created the commit now--and that
913 -------------------------------------------------
915 -------------------------------------------------
917 shows the difference between the working tree and the index file.
919 Note that "git add" always adds just the current contents of a file
920 to the index; further changes to the same file will be ignored unless
921 you run git-add on the file again.
923 When you're ready, just run
925 -------------------------------------------------
927 -------------------------------------------------
929 and git will prompt you for a commit message and then create the new
930 commmit. Check to make sure it looks like what you expected with
932 -------------------------------------------------
934 -------------------------------------------------
936 As a special shortcut,
938 -------------------------------------------------
940 -------------------------------------------------
942 will update the index with any files that you've modified or removed
943 and create a commit, all in one step.
945 A number of commands are useful for keeping track of what you're
948 -------------------------------------------------
949 $ git diff --cached # difference between HEAD and the index; what
950 # would be commited if you ran "commit" now.
951 $ git diff # difference between the index file and your
952 # working directory; changes that would not
953 # be included if you ran "commit" now.
954 $ git status # a brief per-file summary of the above.
955 -------------------------------------------------
957 creating good commit messages
958 -----------------------------
960 Though not required, it's a good idea to begin the commit message
961 with a single short (less than 50 character) line summarizing the
962 change, followed by a blank line and then a more thorough
963 description. Tools that turn commits into email, for example, use
964 the first line on the Subject line and the rest of the commit in the
970 You can rejoin two diverging branches of development using
971 gitlink:git-merge[1]:
973 -------------------------------------------------
974 $ git merge branchname
975 -------------------------------------------------
977 merges the development in the branch "branchname" into the current
978 branch. If there are conflicts--for example, if the same file is
979 modified in two different ways in the remote branch and the local
980 branch--then you are warned; the output may look something like this:
982 -------------------------------------------------
984 Trying really trivial in-index merge...
985 fatal: Merge requires file-level merging
987 Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
991 found 1 common ancestor(s):
993 Auto-merging file.txt
994 CONFLICT (content): Merge conflict in file.txt
995 Automatic merge failed; fix conflicts and then commit the result.
996 -------------------------------------------------
998 Conflict markers are left in the problematic files, and after
999 you resolve the conflicts manually, you can update the index
1000 with the contents and run git commit, as you normally would when
1001 creating a new file.
1003 If you examine the resulting commit using gitk, you will see that it
1004 has two parents, one pointing to the top of the current branch, and
1005 one to the top of the other branch.
1009 [[resolving-a-merge]]
1013 When a merge isn't resolved automatically, git leaves the index and
1014 the working tree in a special state that gives you all the
1015 information you need to help resolve the merge.
1017 Files with conflicts are marked specially in the index, so until you
1018 resolve the problem and update the index, git commit will fail:
1020 -------------------------------------------------
1022 file.txt: needs merge
1023 -------------------------------------------------
1025 Also, git status will list those files as "unmerged".
1027 All of the changes that git was able to merge automatically are
1028 already added to the index file, so gitlink:git-diff[1] shows only
1029 the conflicts. Also, it uses a somewhat unusual syntax:
1031 -------------------------------------------------
1034 index 802992c,2b60207..0000000
1037 @@@ -1,1 -1,1 +1,5 @@@
1038 ++<<<<<<< HEAD:file.txt
1042 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1043 -------------------------------------------------
1045 Recall that the commit which will be commited after we resolve this
1046 conflict will have two parents instead of the usual one: one parent
1047 will be HEAD, the tip of the current branch; the other will be the
1048 tip of the other branch, which is stored temporarily in MERGE_HEAD.
1050 The diff above shows the differences between the working-tree version
1051 of file.txt and two previous version: one version from HEAD, and one
1052 from MERGE_HEAD. So instead of preceding each line by a single "+"
1053 or "-", it now uses two columns: the first column is used for
1054 differences between the first parent and the working directory copy,
1055 and the second for differences between the second parent and the
1056 working directory copy. Thus after resolving the conflict in the
1057 obvious way, the diff will look like:
1059 -------------------------------------------------
1062 index 802992c,2b60207..0000000
1065 @@@ -1,1 -1,1 +1,1 @@@
1069 -------------------------------------------------
1071 This shows that our resolved version deleted "Hello world" from the
1072 first parent, deleted "Goodbye" from the second parent, and added
1073 "Goodbye world", which was previously absent from both.
1075 The gitlink:git-log[1] command also provides special help for merges:
1077 -------------------------------------------------
1079 -------------------------------------------------
1081 This will list all commits which exist only on HEAD or on MERGE_HEAD,
1082 and which touch an unmerged file.
1084 We can now add the resolved version to the index and commit:
1086 -------------------------------------------------
1089 -------------------------------------------------
1091 Note that the commit message will already be filled in for you with
1092 some information about the merge. Normally you can just use this
1093 default message unchanged, but you may add additional commentary of
1094 your own if desired.
1100 If you get stuck and decide to just give up and throw the whole mess
1101 away, you can always return to the pre-merge state with
1103 -------------------------------------------------
1104 $ git reset --hard HEAD
1105 -------------------------------------------------
1107 Or, if you've already commited the merge that you want to throw away,
1109 -------------------------------------------------
1110 $ git reset --hard HEAD^
1111 -------------------------------------------------
1113 However, this last command can be dangerous in some cases--never
1114 throw away a commit you have already committed if that commit may
1115 itself have been merged into another branch, as doing so may confuse
1121 There is one special case not mentioned above, which is treated
1122 differently. Normally, a merge results in a merge commit, with two
1123 parents, one pointing at each of the two lines of development that
1126 However, if one of the two lines of development is completely
1127 contained within the other--so every commit present in the one is
1128 already contained in the other--then git just performs a
1129 <<fast-forwards,fast forward>>; the head of the current branch is
1130 moved forward to point at the head of the merged-in branch, without
1131 any new commits being created.
1136 If you've messed up the working tree, but haven't yet committed your
1137 mistake, you can return the entire working tree to the last committed
1140 -------------------------------------------------
1141 $ git reset --hard HEAD
1142 -------------------------------------------------
1144 If you make a commit that you later wish you hadn't, there are two
1145 fundamentally different ways to fix the problem:
1147 1. You can create a new commit that undoes whatever was done
1148 by the previous commit. This is the correct thing if your
1149 mistake has already been made public.
1151 2. You can go back and modify the old commit. You should
1152 never do this if you have already made the history public;
1153 git does not normally expect the "history" of a project to
1154 change, and cannot correctly perform repeated merges from
1155 a branch that has had its history changed.
1157 Fixing a mistake with a new commit
1158 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1160 Creating a new commit that reverts an earlier change is very easy;
1161 just pass the gitlink:git-revert[1] command a reference to the bad
1162 commit; for example, to revert the most recent commit:
1164 -------------------------------------------------
1166 -------------------------------------------------
1168 This will create a new commit which undoes the change in HEAD. You
1169 will be given a chance to edit the commit message for the new commit.
1171 You can also revert an earlier change, for example, the next-to-last:
1173 -------------------------------------------------
1175 -------------------------------------------------
1177 In this case git will attempt to undo the old change while leaving
1178 intact any changes made since then. If more recent changes overlap
1179 with the changes to be reverted, then you will be asked to fix
1180 conflicts manually, just as in the case of <<resolving-a-merge,
1181 resolving a merge>>.
1183 Fixing a mistake by editing history
1184 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1186 If the problematic commit is the most recent commit, and you have not
1187 yet made that commit public, then you may just
1188 <<undoing-a-merge,destroy it using git-reset>>.
1191 can edit the working directory and update the index to fix your
1192 mistake, just as if you were going to <<how-to-make-a-commit,create a
1193 new commit>>, then run
1195 -------------------------------------------------
1196 $ git commit --amend
1197 -------------------------------------------------
1199 which will replace the old commit by a new commit incorporating your
1200 changes, giving you a chance to edit the old commit message first.
1202 Again, you should never do this to a commit that may already have
1203 been merged into another branch; use gitlink:git-revert[1] instead in
1206 It is also possible to edit commits further back in the history, but
1207 this is an advanced topic to be left for
1208 <<cleaning-up-history,another chapter>>.
1210 Checking out an old version of a file
1211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1213 In the process of undoing a previous bad change, you may find it
1214 useful to check out an older version of a particular file using
1215 gitlink:git-checkout[1]. We've used git checkout before to switch
1216 branches, but it has quite different behavior if it is given a path
1219 -------------------------------------------------
1220 $ git checkout HEAD^ path/to/file
1221 -------------------------------------------------
1223 replaces path/to/file by the contents it had in the commit HEAD^, and
1224 also updates the index to match. It does not change branches.
1226 If you just want to look at an old version of the file, without
1227 modifying the working directory, you can do that with
1228 gitlink:git-show[1]:
1230 -------------------------------------------------
1231 $ git show HEAD^ path/to/file
1232 -------------------------------------------------
1234 which will display the given version of the file.
1236 Ensuring good performance
1237 -------------------------
1239 On large repositories, git depends on compression to keep the history
1240 information from taking up to much space on disk or in memory.
1242 This compression is not performed automatically. Therefore you
1243 should occasionally run
1245 -------------------------------------------------
1247 -------------------------------------------------
1249 to recompress the archive and to prune any commits which are no
1250 longer referred to anywhere. This can be very time-consuming, and
1251 you should not modify the repository while it is working, so you
1252 should run it while you are not working.
1254 Sharing development with others
1255 ===============================
1257 [[getting-updates-with-git-pull]]
1258 Getting updates with git pull
1259 -----------------------------
1261 After you clone a repository and make a few changes of your own, you
1262 may wish to check the original repository for updates and merge them
1265 We have already seen <<Updating-a-repository-with-git-fetch,how to
1266 keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1267 and how to merge two branches. So you can merge in changes from the
1268 original repository's master branch with:
1270 -------------------------------------------------
1272 $ git merge origin/master
1273 -------------------------------------------------
1275 However, the gitlink:git-pull[1] command provides a way to do this in
1278 -------------------------------------------------
1279 $ git pull origin master
1280 -------------------------------------------------
1282 In fact, "origin" is normally the default repository to pull from,
1283 and the default branch is normally the HEAD of the remote repository,
1284 so often you can accomplish the above with just
1286 -------------------------------------------------
1288 -------------------------------------------------
1290 See the descriptions of the branch.<name>.remote and
1291 branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1292 how to control these defaults depending on the current branch.
1294 In addition to saving you keystrokes, "git pull" also helps you by
1295 producing a default commit message documenting the branch and
1296 repository that you pulled from.
1298 (But note that no such commit will be created in the case of a
1299 <<fast-forwards,fast forward>>; instead, your branch will just be
1300 updated to point to the latest commit from the upstream branch).
1302 The git-pull command can also be given "." as the "remote" repository, in
1303 which case it just merges in a branch from the current repository; so
1306 -------------------------------------------------
1309 -------------------------------------------------
1311 are roughly equivalent. The former is actually very commonly used.
1313 Submitting patches to a project
1314 -------------------------------
1316 If you just have a few changes, the simplest way to submit them may
1317 just be to send them as patches in email:
1319 First, use gitlink:git-format-patches[1]; for example:
1321 -------------------------------------------------
1322 $ git format-patch origin
1323 -------------------------------------------------
1325 will produce a numbered series of files in the current directory, one
1326 for each patch in the current branch but not in origin/HEAD.
1328 You can then import these into your mail client and send them by
1329 hand. However, if you have a lot to send at once, you may prefer to
1330 use the gitlink:git-send-email[1] script to automate the process.
1331 Consult the mailing list for your project first to determine how they
1332 prefer such patches be handled.
1334 Importing patches to a project
1335 ------------------------------
1337 Git also provides a tool called gitlink:git-am[1] (am stands for
1338 "apply mailbox"), for importing such an emailed series of patches.
1339 Just save all of the patch-containing messages, in order, into a
1340 single mailbox file, say "patches.mbox", then run
1342 -------------------------------------------------
1343 $ git am -3 patches.mbox
1344 -------------------------------------------------
1346 Git will apply each patch in order; if any conflicts are found, it
1347 will stop, and you can fix the conflicts as described in
1348 "<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells
1349 git to perform a merge; if you would prefer it just to abort and
1350 leave your tree and index untouched, you may omit that option.)
1352 Once the index is updated with the results of the conflict
1353 resolution, instead of creating a new commit, just run
1355 -------------------------------------------------
1357 -------------------------------------------------
1359 and git will create the commit for you and continue applying the
1360 remaining patches from the mailbox.
1362 The final result will be a series of commits, one for each patch in
1363 the original mailbox, with authorship and commit log message each
1364 taken from the message containing each patch.
1366 [[setting-up-a-public-repository]]
1367 Setting up a public repository
1368 ------------------------------
1370 Another way to submit changes to a project is to simply tell the
1371 maintainer of that project to pull from your repository, exactly as
1372 you did in the section "<<getting-updates-with-git-pull, Getting
1373 updates with git pull>>".
1375 If you and maintainer both have accounts on the same machine, then
1376 then you can just pull changes from each other's repositories
1377 directly; note that all of the command (gitlink:git-clone[1],
1378 git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1379 will also accept a local file patch; so, for example, you can
1382 -------------------------------------------------
1383 $ git clone /path/to/repository
1384 $ git pull /path/to/other/repository
1385 -------------------------------------------------
1387 If this sort of setup is inconvenient or impossible, another (more
1388 common) option is to set up a public repository on a public server.
1389 This also allows you to cleanly separate private work in progress
1390 from publicly visible work.
1392 You will continue to do your day-to-day work in your personal
1393 repository, but periodically "push" changes from your personal
1394 repository into your public repository, allowing other developers to
1395 pull from that repository. So the flow of changes, in a situation
1396 where there is one other developer with a public repository, looks
1400 your personal repo ------------------> your public repo
1403 | you pull | they pull
1407 their public repo <------------------- their repo
1409 Now, assume your personal repository is in the directory ~/proj. We
1410 first create a new clone of the repository:
1412 -------------------------------------------------
1413 $ git clone --bare proj-clone.git
1414 -------------------------------------------------
1416 The resulting directory proj-clone.git will contains a "bare" git
1417 repository--it is just the contents of the ".git" directory, without
1418 a checked-out copy of a working directory.
1420 Next, copy proj-clone.git to the server where you plan to host the
1421 public repository. You can use scp, rsync, or whatever is most
1424 If somebody else maintains the public server, they may already have
1425 set up a git service for you, and you may skip to the section
1426 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
1427 repository>>", below.
1429 Otherwise, the following sections explain how to export your newly
1430 created public repository:
1432 [[exporting-via-http]]
1433 Exporting a git repository via http
1434 -----------------------------------
1436 The git protocol gives better performance and reliability, but on a
1437 host with a web server set up, http exports may be simpler to set up.
1439 All you need to do is place the newly created bare git repository in
1440 a directory that is exported by the web server, and make some
1441 adjustments to give web clients some extra information they need:
1443 -------------------------------------------------
1444 $ mv proj.git /home/you/public_html/proj.git
1446 $ git update-server-info
1447 $ chmod a+x hooks/post-update
1448 -------------------------------------------------
1450 (For an explanation of the last two lines, see
1451 gitlink:git-update-server-info[1], and the documentation
1452 link:hooks.txt[Hooks used by git].)
1454 Advertise the url of proj.git. Anybody else should then be able to
1455 clone or pull from that url, for example with a commandline like:
1457 -------------------------------------------------
1458 $ git clone http://yourserver.com/~you/proj.git
1459 -------------------------------------------------
1462 link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1463 for a slightly more sophisticated setup using WebDAV which also
1464 allows pushing over http.)
1466 [[exporting-via-git]]
1467 Exporting a git repository via the git protocol
1468 -----------------------------------------------
1470 This is the preferred method.
1472 For now, we refer you to the gitlink:git-daemon[1] man page for
1473 instructions. (See especially the examples section.)
1475 [[pushing-changes-to-a-public-repository]]
1476 Pushing changes to a public repository
1477 --------------------------------------
1479 Note that the two techniques outline above (exporting via
1480 <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1481 maintainers to fetch your latest changes, but they do not allow write
1482 access, which you will need to update the public repository with the
1483 latest changes created in your private repository.
1485 The simplest way to do this is using gitlink:git-push[1] and ssh; to
1486 update the remote branch named "master" with the latest state of your
1487 branch named "master", run
1489 -------------------------------------------------
1490 $ git push ssh://yourserver.com/~you/proj.git master:master
1491 -------------------------------------------------
1495 -------------------------------------------------
1496 $ git push ssh://yourserver.com/~you/proj.git master
1497 -------------------------------------------------
1499 As with git-fetch, git-push will complain if this does not result in
1500 a <<fast-forwards,fast forward>>. Normally this is a sign of
1501 something wrong. However, if you are sure you know what you're
1502 doing, you may force git-push to perform the update anyway by
1503 proceeding the branch name by a plus sign:
1505 -------------------------------------------------
1506 $ git push ssh://yourserver.com/~you/proj.git +master
1507 -------------------------------------------------
1509 As with git-fetch, you may also set up configuration options to
1510 save typing; so, for example, after
1512 -------------------------------------------------
1513 $ cat >.git/config <<EOF
1514 [remote "public-repo"]
1515 url = ssh://yourserver.com/~you/proj.git
1517 -------------------------------------------------
1519 you should be able to perform the above push with just
1521 -------------------------------------------------
1522 $ git push public-repo master
1523 -------------------------------------------------
1525 See the explanations of the remote.<name>.url, branch.<name>.remote,
1526 and remote.<name>.push options in gitlink:git-repo-config[1] for
1529 Setting up a shared repository
1530 ------------------------------
1532 Another way to collaborate is by using a model similar to that
1533 commonly used in CVS, where several developers with special rights
1534 all push to and pull from a single shared repository. See
1535 link:cvs-migration.txt[git for CVS users] for instructions on how to
1538 Allow web browsing of a repository
1539 ----------------------------------
1541 TODO: Brief setup-instructions for gitweb
1546 TODO: topic branches, typical roles as in everyday.txt, ?
1549 Working with other version control systems
1550 ==========================================
1552 TODO: CVS, Subversion, series-of-release-tarballs, ?
1554 [[cleaning-up-history]]
1555 Rewriting history and maintaining patch series
1556 ==============================================
1558 Normally commits are only added to a project, never taken away or
1559 replaced. Git is designed with this assumption, and violating it will
1560 cause git's merge machinery (for example) to do the wrong thing.
1562 However, there is a situation in which it can be useful to violate this
1565 Creating the perfect patch series
1566 ---------------------------------
1568 Suppose you are a contributor to a large project, and you want to add a
1569 complicated feature, and to present it to the other developers in a way
1570 that makes it easy for them to read your changes, verify that they are
1571 correct, and understand why you made each change.
1573 If you present all of your changes as a single patch (or commit), they may
1574 find it is too much to digest all at once.
1576 If you present them with the entire history of your work, complete with
1577 mistakes, corrections, and dead ends, they may be overwhelmed.
1579 So the ideal is usually to produce a series of patches such that:
1581 1. Each patch can be applied in order.
1583 2. Each patch includes a single logical change, together with a
1584 message explaining the change.
1586 3. No patch introduces a regression: after applying any initial
1587 part of the series, the resulting project still compiles and
1588 works, and has no bugs that it didn't have before.
1590 4. The complete series produces the same end result as your own
1591 (probably much messier!) development process did.
1593 We will introduce some tools that can help you do this, explain how to use
1594 them, and then explain some of the problems that can arise because you are
1597 Keeping a patch series up to date using git-rebase
1598 --------------------------------------------------
1600 Suppose you have a series of commits in a branch "mywork", which
1601 originally branched off from "origin".
1603 Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1604 and created some commits on top of it:
1606 -------------------------------------------------
1607 $ git checkout -b mywork origin
1613 -------------------------------------------------
1615 You have performed no merges into mywork, so it is just a simple linear
1616 sequence of patches on top of "origin":
1623 Some more interesting work has been done in the upstream project, and
1624 "origin" has advanced:
1626 o--o--O--o--o--o <-- origin
1630 At this point, you could use "pull" to merge your changes back in;
1631 the result would create a new merge commit, like this:
1634 o--o--O--o--o--o <-- origin
1636 a--b--c--m <-- mywork
1638 However, if you prefer to keep the history in mywork a simple series of
1639 commits without any merges, you may instead choose to use
1640 gitlink:git-rebase[1]:
1642 -------------------------------------------------
1643 $ git checkout mywork
1645 -------------------------------------------------
1647 This will remove each of your commits from mywork, temporarily saving them
1648 as patches (in a directory named ".dotest"), update mywork to point at the
1649 latest version of origin, then apply each of the saved patches to the new
1650 mywork. The result will look like:
1653 o--o--O--o--o--o <-- origin
1655 a'--b'--c' <-- mywork
1657 In the process, it may discover conflicts. In that case it will stop and
1658 allow you to fix the conflicts as described in
1659 "<<resolving-a-merge,Resolving a merge>>".
1661 XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1664 Once the index is updated with
1665 the results of the conflict resolution, instead of creating a new commit,
1668 -------------------------------------------------
1669 $ git rebase --continue
1670 -------------------------------------------------
1672 and git will continue applying the rest of the patches.
1674 At any point you may use the --abort option to abort this process and
1675 return mywork to the state it had before you started the rebase:
1677 -------------------------------------------------
1678 $ git rebase --abort
1679 -------------------------------------------------
1681 Reordering or selecting from a patch series
1682 -------------------------------------------
1684 Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1685 you to apply the change introduced by that commit and create a new commit
1688 This can be useful for modifying a patch series.
1695 There are numerous other tools, such as stgit, which exist for the purpose
1696 of maintianing a patch series. These are out of the scope of this manual.
1698 Problems with rewriting history
1699 -------------------------------
1701 The primary problem with rewriting the history of a branch has to do with
1710 Architectural overview
1711 ----------------------
1713 TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1715 Glossary of git terms
1716 =====================
1718 include::glossary.txt[]
1720 Notes and todo list for this manual
1721 ===================================
1723 This is a work in progress.
1725 The basic requirements:
1726 - It must be readable in order, from beginning to end, by someone
1727 intelligent with a basic grasp of the unix commandline, but
1728 without any special knowledge of git. If necessary, any other
1729 prerequisites should be specifically mentioned as they arise.
1730 - Whenever possible, section headings should clearly describe the
1731 task they explain how to do, in language that requires no more
1732 knowledge than necessary: for example, "importing patches into a
1733 project" rather than "the git-am command"
1735 Think about how to create a clear chapter dependency graph that will
1736 allow people to get to important topics without necessarily reading
1737 everything in between.
1739 Scan Documentation/ for other stuff left out; in particular:
1746 Scan email archives for other stuff left out
1748 Scan man pages to see if any assume more background than this manual
1751 Simplify beginning by suggesting disconnected head instead of temporary
1754 Explain how to refer to file stages in the "how to resolve a merge"
1755 section: diff -1, -2, -3, --ours, --theirs :1:/path notation. The
1756 "git ls-files --unmerged --stage" thing is sorta useful too, actually. And
1757 note gitk --merge. Also what's easiest way to see common merge base?
1759 Add more good examples. Entire sections of just cookbook examples might
1760 be a good idea; maybe make an "advanced examples" section a standard
1761 end-of-chapter section?
1763 Include cross-references to the glossary, where appropriate.
1766 reflogs, git reflog expire
1767 shallow clones?? See draft 1.5.0 release notes for some documentation.