Code

3f231811523f41cd67d11f7de884e5d572e10f9e
[git.git] / Documentation / user-manual.txt
1 Git User's Manual
2 _________________
4 This manual is designed to be readable by someone with basic unix
5 commandline skills, but no previous knowledge of git.
7 Chapter 1 gives a brief overview of git commands, without any
8 explanation; you can skip to chapter 2 on a first reading.
10 Chapters 2 and 3 explain how to fetch and study a project using
11 git--the tools you'd need to build and test a particular version of a
12 software project, to search for regressions, and so on.
14 Chapter 4 explains how to do development with git, and chapter 5 how
15 to share that development with others.
17 Further chapters cover more specialized topics.
19 Comprehensive reference documentation is available through the man
20 pages.  For a command such as "git clone", just use
22 ------------------------------------------------
23 $ man git-clone
24 ------------------------------------------------
26 Git Quick Start
27 ===============
29 This is a quick summary of the major commands; the following chapters
30 will explain how these work in more detail.
32 Creating a new repository
33 -------------------------
35 From a tarball:
37 -----------------------------------------------
38 $ tar xzf project.tar.gz
39 $ cd project
40 $ git init
41 Initialized empty Git repository in .git/
42 $ git add .
43 $ git commit
44 -----------------------------------------------
46 From a remote repository:
48 -----------------------------------------------
49 $ git clone git://example.com/pub/project.git
50 $ cd project
51 -----------------------------------------------
53 Managing branches
54 -----------------
56 -----------------------------------------------
57 $ git branch         # list all branches in this repo
58 $ git checkout test  # switch working directory to branch "test"
59 $ git branch new     # create branch "new" starting at current HEAD
60 $ git branch -d new  # delete branch "new"
61 -----------------------------------------------
63 Instead of basing new branch on current HEAD (the default), use:
65 -----------------------------------------------
66 $ git branch new test    # branch named "test"
67 $ git branch new v2.6.15 # tag named v2.6.15
68 $ git branch new HEAD^   # commit before the most recent
69 $ git branch new HEAD^^  # commit before that
70 $ git branch new test~10 # ten commits before tip of branch "test"
71 -----------------------------------------------
73 Create and switch to a new branch at the same time:
75 -----------------------------------------------
76 $ git checkout -b new v2.6.15
77 -----------------------------------------------
79 Update and examine branches from the repository you cloned from:
81 -----------------------------------------------
82 $ git fetch             # update
83 $ git branch -r         # list
84   origin/master
85   origin/next
86   ...
87 $ git branch checkout -b masterwork origin/master
88 -----------------------------------------------
90 Fetch a branch from a different repository, and give it a new
91 name in your repository:
93 -----------------------------------------------
94 $ git fetch git://example.com/project.git theirbranch:mybranch
95 $ git fetch git://example.com/project.git v2.6.15:mybranch
96 -----------------------------------------------
98 Keep a list of repositories you work with regularly:
100 -----------------------------------------------
101 $ git remote add example git://example.com/project.git
102 $ git remote            # list remote repositories
103 example
104 origin
105 $ git remote show example # get details
106 * remote example
107   URL: git://example.com/project.git
108   Tracked remote branches
109     master next ...
110 $ git fetch example     # update branches from example
111 $ git branch -r         # list all remote branches
112 -----------------------------------------------
115 Exploring history
116 -----------------
118 -----------------------------------------------
119 $ gitk                      # visualize and browse history
120 $ git log                   # list all commits
121 $ git log src/              # ...modifying src/
122 $ git log v2.6.15..v2.6.16  # ...in v2.6.16, not in v2.6.15
123 $ git log master..test      # ...in branch test, not in branch master
124 $ git log test..master      # ...in branch master, but not in test
125 $ git log test...master     # ...in one branch, not in both
126 $ git log -S'foo()'         # ...where difference contain "foo()"
127 $ git log --since="2 weeks ago"
128 $ git log -p                # show patches as well
129 $ git show                  # most recent commit
130 $ git diff v2.6.15..v2.6.16 # diff between two tagged versions
131 $ git diff v2.6.15..HEAD    # diff with current head
132 $ git grep "foo()"          # search working directory for "foo()"
133 $ git grep v2.6.15 "foo()"  # search old tree for "foo()"
134 $ git show v2.6.15:a.txt    # look at old version of a.txt
135 -----------------------------------------------
137 Searching for regressions:
139 -----------------------------------------------
140 $ git bisect start
141 $ git bisect bad                # current version is bad
142 $ git bisect good v2.6.13-rc2   # last known good revision
143 Bisecting: 675 revisions left to test after this
144                                 # test here, then:
145 $ git bisect good               # if this revision is good, or
146 $ git bisect bad                # if this revision is bad.
147                                 # repeat until done.
148 -----------------------------------------------
150 Making changes
151 --------------
153 Make sure git knows who to blame:
155 ------------------------------------------------
156 $ cat >~/.gitconfig <<\EOF
157 [user]
158 name = Your Name Comes Here
159 email = you@yourdomain.example.com
160 EOF
161 ------------------------------------------------
163 Select file contents to include in the next commit, then make the
164 commit:
166 -----------------------------------------------
167 $ git add a.txt    # updated file
168 $ git add b.txt    # new file
169 $ git rm c.txt     # old file
170 $ git commit
171 -----------------------------------------------
173 Or, prepare and create the commit in one step:
175 -----------------------------------------------
176 $ git commit d.txt # use latest content of d.txt
177 $ git commit -a    # use latest content of all tracked files
178 -----------------------------------------------
180 Merging
181 -------
183 -----------------------------------------------
184 $ git merge test   # merge branch "test" into the current branch
185 $ git pull git://example.com/project.git master
186                    # fetch and merge in remote branch
187 $ git pull . test  # equivalent to git merge test
188 -----------------------------------------------
190 Sharing your changes
191 --------------------
193 Importing or exporting patches:
195 -----------------------------------------------
196 $ git format-patch origin..HEAD # format a patch for each commit
197                                 # in HEAD but not in origin
198 $ git-am mbox # import patches from the mailbox "mbox"
199 -----------------------------------------------
201 Fetch a branch in a different git repository, then merge into the
202 current branch:
204 -----------------------------------------------
205 $ git pull git://example.com/project.git theirbranch
206 -----------------------------------------------
208 Store the fetched branch into a local branch before merging into the
209 current branch:
211 -----------------------------------------------
212 $ git pull git://example.com/project.git theirbranch:mybranch
213 -----------------------------------------------
215 After creating commits on a local branch, update the remote
216 branch with your commits:
218 -----------------------------------------------
219 $ git push ssh://example.com/project.git mybranch:theirbranch
220 -----------------------------------------------
222 When remote and local branch are both named "test":
224 -----------------------------------------------
225 $ git push ssh://example.com/project.git test
226 -----------------------------------------------
228 Shortcut version for a frequently used remote repository:
230 -----------------------------------------------
231 $ git remote add example ssh://example.com/project.git
232 $ git push example test
233 -----------------------------------------------
235 Repositories and Branches
236 =========================
238 How to get a git repository
239 ---------------------------
241 It will be useful to have a git repository to experiment with as you
242 read this manual.
244 The best way to get one is by using the gitlink:git-clone[1] command
245 to download a copy of an existing repository for a project that you
246 are interested in.  If you don't already have a project in mind, here
247 are some interesting examples:
249 ------------------------------------------------
250         # git itself (approx. 10MB download):
251 $ git clone git://git.kernel.org/pub/scm/git/git.git
252         # the linux kernel (approx. 150MB download):
253 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
254 ------------------------------------------------
256 The initial clone may be time-consuming for a large project, but you
257 will only need to clone once.
259 The clone command creates a new directory named after the project
260 ("git" or "linux-2.6" in the examples above).  After you cd into this
261 directory, you will see that it contains a copy of the project files,
262 together with a special top-level directory named ".git", which
263 contains all the information about the history of the project.
265 In most of the following, examples will be taken from one of the two
266 repositories above.
268 How to check out a different version of a project
269 -------------------------------------------------
271 Git is best thought of as a tool for storing the history of a
272 collection of files.  It stores the history as a compressed
273 collection of interrelated snapshots (versions) of the project's
274 contents.
276 A single git repository may contain multiple branches.  Each branch
277 is a bookmark referencing a particular point in the project history.
278 The gitlink:git-branch[1] command shows you the list of branches:
280 ------------------------------------------------
281 $ git branch
282 * master
283 ------------------------------------------------
285 A freshly cloned repository contains a single branch, named "master",
286 and the working directory contains the version of the project
287 referred to by the master branch.
289 Most projects also use tags.  Tags, like branches, are references
290 into the project's history, and can be listed using the
291 gitlink:git-tag[1] command:
293 ------------------------------------------------
294 $ git tag -l
295 v2.6.11
296 v2.6.11-tree
297 v2.6.12
298 v2.6.12-rc2
299 v2.6.12-rc3
300 v2.6.12-rc4
301 v2.6.12-rc5
302 v2.6.12-rc6
303 v2.6.13
304 ...
305 ------------------------------------------------
307 Create a new branch pointing to one of these versions and check it
308 out using gitlink:git-checkout[1]:
310 ------------------------------------------------
311 $ git checkout -b new v2.6.13
312 ------------------------------------------------
314 The working directory then reflects the contents that the project had
315 when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
316 branches, with an asterisk marking the currently checked-out branch:
318 ------------------------------------------------
319 $ git branch
320   master
321 * new
322 ------------------------------------------------
324 If you decide that you'd rather see version 2.6.17, you can modify
325 the current branch to point at v2.6.17 instead, with
327 ------------------------------------------------
328 $ git reset --hard v2.6.17
329 ------------------------------------------------
331 Note that if the current branch was your only reference to a
332 particular point in history, then resetting that branch may leave you
333 with no way to find the history it used to point to; so use this
334 command carefully.
336 Understanding History: Commits
337 ------------------------------
339 Every change in the history of a project is represented by a commit.
340 The gitlink:git-show[1] command shows the most recent commit on the
341 current branch:
343 ------------------------------------------------
344 $ git show
345 commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
346 Author: Jamal Hadi Salim <hadi@cyberus.ca>
347 Date:   Sat Dec 2 22:22:25 2006 -0800
349     [XFRM]: Fix aevent structuring to be more complete.
350     
351     aevents can not uniquely identify an SA. We break the ABI with this
352     patch, but consensus is that since it is not yet utilized by any
353     (known) application then it is fine (better do it now than later).
354     
355     Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
356     Signed-off-by: David S. Miller <davem@davemloft.net>
358 diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
359 index 8be626f..d7aac9d 100644
360 --- a/Documentation/networking/xfrm_sync.txt
361 +++ b/Documentation/networking/xfrm_sync.txt
362 @@ -47,10 +47,13 @@ aevent_id structure looks like:
363  
364     struct xfrm_aevent_id {
365               struct xfrm_usersa_id           sa_id;
366 +             xfrm_address_t                  saddr;
367               __u32                           flags;
368 +             __u32                           reqid;
369     };
370 ...
371 ------------------------------------------------
373 As you can see, a commit shows who made the latest change, what they
374 did, and why.
376 Every commit has a 40-hexdigit id, sometimes called the "SHA1 id", shown
377 on the first line of the "git show" output.  You can usually refer to
378 a commit by a shorter name, such as a tag or a branch name, but this
379 longer id can also be useful.  In particular, it is a globally unique
380 name for this commit: so if you tell somebody else the SHA1 id (for
381 example in email), then you are guaranteed they will see the same
382 commit in their repository that you do in yours.
384 Understanding history: commits, parents, and reachability
385 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
387 Every commit (except the very first commit in a project) also has a
388 parent commit which shows what happened before this commit.
389 Following the chain of parents will eventually take you back to the
390 beginning of the project.
392 However, the commits do not form a simple list; git allows lines of
393 development to diverge and then reconverge, and the point where two
394 lines of development reconverge is called a "merge".  The commit
395 representing a merge can therefore have more than one parent, with
396 each parent representing the most recent commit on one of the lines
397 of development leading to that point.
399 The best way to see how this works is using the gitlink:gitk[1]
400 command; running gitk now on a git repository and looking for merge
401 commits will help understand how the git organizes history.
403 In the following, we say that commit X is "reachable" from commit Y
404 if commit X is an ancestor of commit Y.  Equivalently, you could say
405 that Y is a descendent of X, or that there is a chain of parents
406 leading from commit Y to commit X.
408 Undestanding history: History diagrams
409 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411 We will sometimes represent git history using diagrams like the one
412 below.  Commits are shown as "o", and the links between them with
413 lines drawn with - / and \.  Time goes left to right:
415          o--o--o <-- Branch A
416         /
417  o--o--o <-- master
418         \
419          o--o--o <-- Branch B
421 If we need to talk about a particular commit, the character "o" may
422 be replaced with another letter or number.
424 Understanding history: What is a branch?
425 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
427 Though we've been using the word "branch" to mean a kind of reference
428 to a particular commit, the word branch is also commonly used to
429 refer to the line of commits leading up to that point.  In the
430 example above, git may think of the branch named "A" as just a
431 pointer to one particular commit, but we may refer informally to the
432 line of three commits leading up to that point as all being part of
433 "branch A".
435 If we need to make it clear that we're just talking about the most
436 recent commit on the branch, we may refer to that commit as the
437 "head" of the branch.
439 Manipulating branches
440 ---------------------
442 Creating, deleting, and modifying branches is quick and easy; here's
443 a summary of the commands:
445 git branch::
446         list all branches
447 git branch <branch>::
448         create a new branch named <branch>, referencing the same
449         point in history as the current branch
450 git branch <branch> <start-point>::
451         create a new branch named <branch>, referencing
452         <start-point>, which may be specified any way you like,
453         including using a branch name or a tag name
454 git branch -d <branch>::
455         delete the branch <branch>; if the branch you are deleting
456         points to a commit which is not reachable from this branch,
457         this command will fail with a warning.
458 git branch -D <branch>::
459         even if the branch points to a commit not reachable
460         from the current branch, you may know that that commit
461         is still reachable from some other branch or tag.  In that
462         case it is safe to use this command to force git to delete
463         the branch.
464 git checkout <branch>::
465         make the current branch <branch>, updating the working
466         directory to reflect the version referenced by <branch>
467 git checkout -b <new> <start-point>::
468         create a new branch <new> referencing <start-point>, and
469         check it out.
471 It is also useful to know that the special symbol "HEAD" can always
472 be used to refer to the current branch.
474 Examining branches from a remote repository
475 -------------------------------------------
477 The "master" branch that was created at the time you cloned is a copy
478 of the HEAD in the repository that you cloned from.  That repository
479 may also have had other branches, though, and your local repository
480 keeps branches which track each of those remote branches, which you
481 can view using the "-r" option to gitlink:git-branch[1]:
483 ------------------------------------------------
484 $ git branch -r
485   origin/HEAD
486   origin/html
487   origin/maint
488   origin/man
489   origin/master
490   origin/next
491   origin/pu
492   origin/todo
493 ------------------------------------------------
495 You cannot check out these remote-tracking branches, but you can
496 examine them on a branch of your own, just as you would a tag:
498 ------------------------------------------------
499 $ git checkout -b my-todo-copy origin/todo
500 ------------------------------------------------
502 Note that the name "origin" is just the name that git uses by default
503 to refer to the repository that you cloned from.
505 [[how-git-stores-references]]
506 How git stores references
507 -------------------------
509 Branches, remote-tracking branches, and tags are all references to
510 commits.  Git stores these references in the ".git" directory.  Most
511 of them are stored in .git/refs/:
513         - branches are stored in .git/refs/heads
514         - tags are stored in .git/refs/tags
515         - remote-tracking branches for "origin" are stored in
516           .git/refs/remotes/origin/
518 If you look at one of these files you will see that they usually
519 contain just the SHA1 id of a commit:
521 ------------------------------------------------
522 $ ls .git/refs/heads/
523 master
524 $ cat .git/refs/heads/master
525 c0f982dcf188d55db9d932a39d4ea7becaa55fed
526 ------------------------------------------------
528 You can refer to a reference by its path relative to the .git
529 directory.  However, we've seen above that git will also accept
530 shorter names; for example, "master" is an acceptable shortcut for
531 "refs/heads/master", and "origin/master" is a shortcut for
532 "refs/remotes/origin/master".
534 As another useful shortcut, you can also refer to the "HEAD" of
535 "origin" (or any other remote), using just the name of the remote.
537 For the complete list of paths which git checks for references, and
538 how it decides which to choose when there are multiple references
539 with the same name, see the "SPECIFYING REVISIONS" section of
540 gitlink:git-rev-parse[1].
542 [[Updating-a-repository-with-git-fetch]]
543 Updating a repository with git fetch
544 ------------------------------------
546 Eventually the developer cloned from will do additional work in her
547 repository, creating new commits and advancing the branches to point
548 at the new commits.
550 The command "git fetch", with no arguments, will update all of the
551 remote-tracking branches to the latest version found in her
552 repository.  It will not touch any of your own branches--not even the
553 "master" branch that was created for you on clone.
555 Fetching branches from other repositories
556 -----------------------------------------
558 You can also track branches from repositories other than the one you
559 cloned from, using gitlink:git-remote[1]:
561 -------------------------------------------------
562 $ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
563 $ git fetch
564 * refs/remotes/linux-nfs/master: storing branch 'master' ...
565   commit: bf81b46
566 -------------------------------------------------
568 New remote-tracking branches will be stored under the shorthand name
569 that you gave "git remote add", in this case linux-nfs:
571 -------------------------------------------------
572 $ git branch -r
573 linux-nfs/master
574 origin/master
575 -------------------------------------------------
577 If you run "git fetch <remote>" later, the tracking branches for the
578 named <remote> will be updated.
580 If you examine the file .git/config, you will see that git has added
581 a new stanza:
583 -------------------------------------------------
584 $ cat .git/config
585 ...
586 [remote "linux-nfs"]
587         url = git://linux-nfs.org/~bfields/git.git
588         fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
589 ...
590 -------------------------------------------------
592 This is what causes git to track the remote's branches; you may
593 modify or delete these configuration options by editing .git/config
594 with a text editor.
596 Fetching individual branches
597 ----------------------------
599 TODO: find another home for this, later on:
601 You can also choose to update just one branch at a time:
603 -------------------------------------------------
604 $ git fetch origin todo:refs/remotes/origin/todo
605 -------------------------------------------------
607 The first argument, "origin", just tells git to fetch from the
608 repository you originally cloned from.  The second argument tells git
609 to fetch the branch named "todo" from the remote repository, and to
610 store it locally under the name refs/remotes/origin/todo; as we saw
611 above, remote-tracking branches are stored under
612 refs/remotes/<name-of-repository>/<name-of-branch>.
614 You can also fetch branches from other repositories; so
616 -------------------------------------------------
617 $ git fetch git://example.com/proj.git master:refs/remotes/example/master
618 -------------------------------------------------
620 will create a new reference named "refs/remotes/example/master" and
621 store in it the branch named "master" from the repository at the
622 given URL.  If you already have a branch named
623 "refs/remotes/example/master", it will attempt to "fast-forward" to
624 the commit given by example.com's master branch.  So next we explain
625 what a fast-forward is:
627 [[fast-forwards]]
628 Understanding git history: fast-forwards
629 ----------------------------------------
631 In the previous example, when updating an existing branch, "git
632 fetch" checks to make sure that the most recent commit on the remote
633 branch is a descendant of the most recent commit on your copy of the
634 branch before updating your copy of the branch to point at the new
635 commit.  Git calls this process a "fast forward".
637 A fast forward looks something like this:
639  o--o--o--o <-- old head of the branch
640            \
641             o--o--o <-- new head of the branch
644 In some cases it is possible that the new head will *not* actually be
645 a descendant of the old head.  For example, the developer may have
646 realized she made a serious mistake, and decided to backtrack,
647 resulting in a situation like:
649  o--o--o--o--a--b <-- old head of the branch
650            \
651             o--o--o <-- new head of the branch
655 In this case, "git fetch" will fail, and print out a warning.
657 In that case, you can still force git to update to the new head, as
658 described in the following section.  However, note that in the
659 situation above this may mean losing the commits labeled "a" and "b",
660 unless you've already created a reference of your own pointing to
661 them.
663 Forcing git fetch to do non-fast-forward updates
664 ------------------------------------------------
666 If git fetch fails because the new head of a branch is not a
667 descendant of the old head, you may force the update with:
669 -------------------------------------------------
670 $ git fetch git://example.com/proj.git +master:refs/remotes/example/master
671 -------------------------------------------------
673 Note the addition of the "+" sign.  Be aware that commits which the
674 old version of example/master pointed at may be lost, as we saw in
675 the previous section.
677 Configuring remote branches
678 ---------------------------
680 We saw above that "origin" is just a shortcut to refer to the
681 repository which you originally cloned from.  This information is
682 stored in git configuration variables, which you can see using
683 gitlink:git-repo-config[1]:
685 -------------------------------------------------
686 $ git-repo-config -l
687 core.repositoryformatversion=0
688 core.filemode=true
689 core.logallrefupdates=true
690 remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
691 remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
692 branch.master.remote=origin
693 branch.master.merge=refs/heads/master
694 -------------------------------------------------
696 If there are other repositories that you also use frequently, you can
697 create similar configuration options to save typing; for example,
698 after
700 -------------------------------------------------
701 $ git repo-config remote.example.url git://example.com/proj.git
702 -------------------------------------------------
704 then the following two commands will do the same thing:
706 -------------------------------------------------
707 $ git fetch git://example.com/proj.git master:refs/remotes/example/master
708 $ git fetch example master:refs/remotes/example/master
709 -------------------------------------------------
711 Even better, if you add one more option:
713 -------------------------------------------------
714 $ git repo-config remote.example.fetch master:refs/remotes/example/master
715 -------------------------------------------------
717 then the following commands will all do the same thing:
719 -------------------------------------------------
720 $ git fetch git://example.com/proj.git master:ref/remotes/example/master
721 $ git fetch example master:ref/remotes/example/master
722 $ git fetch example example/master
723 $ git fetch example
724 -------------------------------------------------
726 You can also add a "+" to force the update each time:
728 -------------------------------------------------
729 $ git repo-config remote.example.fetch +master:ref/remotes/example/master
730 -------------------------------------------------
732 Don't do this unless you're sure you won't mind "git fetch" possibly
733 throwing away commits on mybranch.
735 Also note that all of the above configuration can be performed by
736 directly editing the file .git/config instead of using
737 gitlink:git-repo-config[1].
739 See gitlink:git-repo-config[1] for more details on the configuration
740 options mentioned above.
742 Exploring git history
743 =====================
745 Git is best thought of as a tool for storing the history of a
746 collection of files.  It does this by storing compressed snapshots of
747 the contents of a file heirarchy, together with "commits" which show
748 the relationships between these snapshots.
750 Git provides extremely flexible and fast tools for exploring the
751 history of a project.
753 We start with one specialized tool which is useful for finding the
754 commit that introduced a bug into a project.
756 How to use bisect to find a regression
757 --------------------------------------
759 Suppose version 2.6.18 of your project worked, but the version at
760 "master" crashes.  Sometimes the best way to find the cause of such a
761 regression is to perform a brute-force search through the project's
762 history to find the particular commit that caused the problem.  The
763 gitlink:git-bisect[1] command can help you do this:
765 -------------------------------------------------
766 $ git bisect start
767 $ git bisect good v2.6.18
768 $ git bisect bad master
769 Bisecting: 3537 revisions left to test after this
770 [65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
771 -------------------------------------------------
773 If you run "git branch" at this point, you'll see that git has
774 temporarily moved you to a new branch named "bisect".  This branch
775 points to a commit (with commit id 65934...) that is reachable from
776 v2.6.19 but not from v2.6.18.  Compile and test it, and see whether
777 it crashes.  Assume it does crash.  Then:
779 -------------------------------------------------
780 $ git bisect bad
781 Bisecting: 1769 revisions left to test after this
782 [7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
783 -------------------------------------------------
785 checks out an older version.  Continue like this, telling git at each
786 stage whether the version it gives you is good or bad, and notice
787 that the number of revisions left to test is cut approximately in
788 half each time.
790 After about 13 tests (in this case), it will output the commit id of
791 the guilty commit.  You can then examine the commit with
792 gitlink:git-show[1], find out who wrote it, and mail them your bug
793 report with the commit id.  Finally, run
795 -------------------------------------------------
796 $ git bisect reset
797 -------------------------------------------------
799 to return you to the branch you were on before and delete the
800 temporary "bisect" branch.
802 Note that the version which git-bisect checks out for you at each
803 point is just a suggestion, and you're free to try a different
804 version if you think it would be a good idea.  For example,
805 occasionally you may land on a commit that broke something unrelated;
806 run
808 -------------------------------------------------
809 $ git bisect-visualize
810 -------------------------------------------------
812 which will run gitk and label the commit it chose with a marker that
813 says "bisect".  Chose a safe-looking commit nearby, note its commit
814 id, and check it out with:
816 -------------------------------------------------
817 $ git reset --hard fb47ddb2db...
818 -------------------------------------------------
820 then test, run "bisect good" or "bisect bad" as appropriate, and
821 continue.
823 Naming commits
824 --------------
826 We have seen several ways of naming commits already:
828         - 40-hexdigit SHA1 id
829         - branch name: refers to the commit at the head of the given
830           branch
831         - tag name: refers to the commit pointed to by the given tag
832           (we've seen branches and tags are special cases of
833           <<how-git-stores-references,references>>).
834         - HEAD: refers to the head of the current branch
836 There are many more; see the "SPECIFYING REVISIONS" section of the
837 gitlink:git-rev-parse[1] man page for the complete list of ways to
838 name revisions.  Some examples:
840 -------------------------------------------------
841 $ git show fb47ddb2 # the first few characters of the SHA1 id
842                     # are usually enough to specify it uniquely
843 $ git show HEAD^    # the parent of the HEAD commit
844 $ git show HEAD^^   # the grandparent
845 $ git show HEAD~4   # the great-great-grandparent
846 -------------------------------------------------
848 Recall that merge commits may have more than one parent; by default,
849 ^ and ~ follow the first parent listed in the commit, but you can
850 also choose:
852 -------------------------------------------------
853 $ git show HEAD^1   # show the first parent of HEAD
854 $ git show HEAD^2   # show the second parent of HEAD
855 -------------------------------------------------
857 In addition to HEAD, there are several other special names for
858 commits:
860 Merges (to be discussed later), as well as operations such as
861 git-reset, which change the currently checked-out commit, generally
862 set ORIG_HEAD to the value HEAD had before the current operation.
864 The git-fetch operation always stores the head of the last fetched
865 branch in FETCH_HEAD.  For example, if you run git fetch without
866 specifying a local branch as the target of the operation
868 -------------------------------------------------
869 $ git fetch git://example.com/proj.git theirbranch
870 -------------------------------------------------
872 the fetched commits will still be available from FETCH_HEAD.
874 When we discuss merges we'll also see the special name MERGE_HEAD,
875 which refers to the other branch that we're merging in to the current
876 branch.
878 The gitlink:git-rev-parse[1] command is a low-level command that is
879 occasionally useful for translating some name for a commit to the SHA1 id for
880 that commit:
882 -------------------------------------------------
883 $ git rev-parse origin
884 e05db0fd4f31dde7005f075a84f96b360d05984b
885 -------------------------------------------------
887 Creating tags
888 -------------
890 We can also create a tag to refer to a particular commit; after
891 running
893 -------------------------------------------------
894 $ git-tag stable-1 1b2e1d63ff
895 -------------------------------------------------
897 You can use stable-1 to refer to the commit 1b2e1d63ff.
899 This creates a "lightweight" tag.  If the tag is a tag you wish to
900 share with others, and possibly sign cryptographically, then you
901 should create a tag object instead; see the gitlink:git-tag[1] man
902 page for details.
904 Browsing revisions
905 ------------------
907 The gitlink:git-log[1] command can show lists of commits.  On its
908 own, it shows all commits reachable from the parent commit; but you
909 can also make more specific requests:
911 -------------------------------------------------
912 $ git log v2.5..        # commits since (not reachable from) v2.5
913 $ git log test..master  # commits reachable from master but not test
914 $ git log master..test  # ...reachable from test but not master
915 $ git log master...test # ...reachable from either test or master,
916                         #    but not both
917 $ git log --since="2 weeks ago" # commits from the last 2 weeks
918 $ git log Makefile      # commits which modify Makefile
919 $ git log fs/           # ... which modify any file under fs/
920 $ git log -S'foo()'     # commits which add or remove any file data
921                         # matching the string 'foo()'
922 -------------------------------------------------
924 And of course you can combine all of these; the following finds
925 commits since v2.5 which touch the Makefile or any file under fs:
927 -------------------------------------------------
928 $ git log v2.5.. Makefile fs/
929 -------------------------------------------------
931 You can also ask git log to show patches:
933 -------------------------------------------------
934 $ git log -p
935 -------------------------------------------------
937 See the "--pretty" option in the gitlink:git-log[1] man page for more
938 display options.
940 Note that git log starts with the most recent commit and works
941 backwards through the parents; however, since git history can contain
942 multiple independant lines of development, the particular order that
943 commits are listed in may be somewhat arbitrary.
945 Generating diffs
946 ----------------
948 You can generate diffs between any two versions using
949 gitlink:git-diff[1]:
951 -------------------------------------------------
952 $ git diff master..test
953 -------------------------------------------------
955 Sometimes what you want instead is a set of patches:
957 -------------------------------------------------
958 $ git format-patch master..test
959 -------------------------------------------------
961 will generate a file with a patch for each commit reachable from test
962 but not from master.  Note that if master also has commits which are
963 not reachable from test, then the combined result of these patches
964 will not be the same as the diff produced by the git-diff example.
966 Viewing old file versions
967 -------------------------
969 You can always view an old version of a file by just checking out the
970 correct revision first.  But sometimes it is more convenient to be
971 able to view an old version of a single file without checking
972 anything out; this command does that:
974 -------------------------------------------------
975 $ git show v2.5:fs/locks.c
976 -------------------------------------------------
978 Before the colon may be anything that names a commit, and after it
979 may be any path to a file tracked by git.
981 Examples
982 --------
984 Check whether two branches point at the same history
985 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
987 Suppose you want to check whether two branches point at the same point
988 in history.
990 -------------------------------------------------
991 $ git diff origin..master
992 -------------------------------------------------
994 will tell you whether the contents of the project are the same at the
995 two branches; in theory, however, it's possible that the same project
996 contents could have been arrived at by two different historical
997 routes.  You could compare the SHA1 id's:
999 -------------------------------------------------
1000 $ git rev-list origin
1001 e05db0fd4f31dde7005f075a84f96b360d05984b
1002 $ git rev-list master
1003 e05db0fd4f31dde7005f075a84f96b360d05984b
1004 -------------------------------------------------
1006 Or you could recall that the ... operator selects all commits
1007 contained reachable from either one reference or the other but not
1008 both: so
1010 -------------------------------------------------
1011 $ git log origin...master
1012 -------------------------------------------------
1014 will return no commits when the two branches are equal.
1016 Check which tagged version a given fix was first included in
1017 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1019 Suppose you know that the commit e05db0fd fixed a certain problem.
1020 You'd like to find the earliest tagged release that contains that
1021 fix.
1023 Of course, there may be more than one answer--if the history branched
1024 after commit e05db0fd, then there could be multiple "earliest" tagged
1025 releases.
1027 You could just visually inspect the commits since e05db0fd:
1029 -------------------------------------------------
1030 $ gitk e05db0fd..
1031 -------------------------------------------------
1033 ...
1035 Developing with git
1036 ===================
1038 Telling git your name
1039 ---------------------
1041 Before creating any commits, you should introduce yourself to git.  The
1042 easiest way to do so is:
1044 ------------------------------------------------
1045 $ cat >~/.gitconfig <<\EOF
1046 [user]
1047         name = Your Name Comes Here
1048         email = you@yourdomain.example.com
1049 EOF
1050 ------------------------------------------------
1053 Creating a new repository
1054 -------------------------
1056 Creating a new repository from scratch is very easy:
1058 -------------------------------------------------
1059 $ mkdir project
1060 $ cd project
1061 $ git init
1062 -------------------------------------------------
1064 If you have some initial content (say, a tarball):
1066 -------------------------------------------------
1067 $ tar -xzvf project.tar.gz
1068 $ cd project
1069 $ git init
1070 $ git add . # include everything below ./ in the first commit:
1071 $ git commit
1072 -------------------------------------------------
1074 [[how-to-make-a-commit]]
1075 how to make a commit
1076 --------------------
1078 Creating a new commit takes three steps:
1080         1. Making some changes to the working directory using your
1081            favorite editor.
1082         2. Telling git about your changes.
1083         3. Creating the commit using the content you told git about
1084            in step 2.
1086 In practice, you can interleave and repeat steps 1 and 2 as many
1087 times as you want: in order to keep track of what you want committed
1088 at step 3, git maintains a snapshot of the tree's contents in a
1089 special staging area called "the index."
1091 At the beginning, the content of the index will be identical to
1092 that of the HEAD.  The command "git diff --cached", which shows
1093 the difference between the HEAD and the index, should therefore
1094 produce no output at that point.
1096 Modifying the index is easy:
1098 To update the index with the new contents of a modified file, use
1100 -------------------------------------------------
1101 $ git add path/to/file
1102 -------------------------------------------------
1104 To add the contents of a new file to the index, use
1106 -------------------------------------------------
1107 $ git add path/to/file
1108 -------------------------------------------------
1110 To remove a file from the index and from the working tree,
1112 -------------------------------------------------
1113 $ git rm path/to/file
1114 -------------------------------------------------
1116 After each step you can verify that
1118 -------------------------------------------------
1119 $ git diff --cached
1120 -------------------------------------------------
1122 always shows the difference between the HEAD and the index file--this
1123 is what you'd commit if you created the commit now--and that
1125 -------------------------------------------------
1126 $ git diff
1127 -------------------------------------------------
1129 shows the difference between the working tree and the index file.
1131 Note that "git add" always adds just the current contents of a file
1132 to the index; further changes to the same file will be ignored unless
1133 you run git-add on the file again.
1135 When you're ready, just run
1137 -------------------------------------------------
1138 $ git commit
1139 -------------------------------------------------
1141 and git will prompt you for a commit message and then create the new
1142 commmit.  Check to make sure it looks like what you expected with
1144 -------------------------------------------------
1145 $ git show
1146 -------------------------------------------------
1148 As a special shortcut,
1149                 
1150 -------------------------------------------------
1151 $ git commit -a
1152 -------------------------------------------------
1154 will update the index with any files that you've modified or removed
1155 and create a commit, all in one step.
1157 A number of commands are useful for keeping track of what you're
1158 about to commit:
1160 -------------------------------------------------
1161 $ git diff --cached # difference between HEAD and the index; what
1162                     # would be commited if you ran "commit" now.
1163 $ git diff          # difference between the index file and your
1164                     # working directory; changes that would not
1165                     # be included if you ran "commit" now.
1166 $ git status        # a brief per-file summary of the above.
1167 -------------------------------------------------
1169 creating good commit messages
1170 -----------------------------
1172 Though not required, it's a good idea to begin the commit message
1173 with a single short (less than 50 character) line summarizing the
1174 change, followed by a blank line and then a more thorough
1175 description.  Tools that turn commits into email, for example, use
1176 the first line on the Subject line and the rest of the commit in the
1177 body.
1179 how to merge
1180 ------------
1182 You can rejoin two diverging branches of development using
1183 gitlink:git-merge[1]:
1185 -------------------------------------------------
1186 $ git merge branchname
1187 -------------------------------------------------
1189 merges the development in the branch "branchname" into the current
1190 branch.  If there are conflicts--for example, if the same file is
1191 modified in two different ways in the remote branch and the local
1192 branch--then you are warned; the output may look something like this:
1194 -------------------------------------------------
1195 $ git pull . next
1196 Trying really trivial in-index merge...
1197 fatal: Merge requires file-level merging
1198 Nope.
1199 Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
1200 Merging:
1201 15e2162 world
1202 77976da goodbye
1203 found 1 common ancestor(s):
1204 d122ed4 initial
1205 Auto-merging file.txt
1206 CONFLICT (content): Merge conflict in file.txt
1207 Automatic merge failed; fix conflicts and then commit the result.
1208 -------------------------------------------------
1210 Conflict markers are left in the problematic files, and after
1211 you resolve the conflicts manually, you can update the index
1212 with the contents and run git commit, as you normally would when
1213 creating a new file.
1215 If you examine the resulting commit using gitk, you will see that it
1216 has two parents, one pointing to the top of the current branch, and
1217 one to the top of the other branch.
1219 In more detail:
1221 [[resolving-a-merge]]
1222 Resolving a merge
1223 -----------------
1225 When a merge isn't resolved automatically, git leaves the index and
1226 the working tree in a special state that gives you all the
1227 information you need to help resolve the merge.
1229 Files with conflicts are marked specially in the index, so until you
1230 resolve the problem and update the index, git commit will fail:
1232 -------------------------------------------------
1233 $ git commit
1234 file.txt: needs merge
1235 -------------------------------------------------
1237 Also, git status will list those files as "unmerged".
1239 All of the changes that git was able to merge automatically are
1240 already added to the index file, so gitlink:git-diff[1] shows only
1241 the conflicts.  Also, it uses a somewhat unusual syntax:
1243 -------------------------------------------------
1244 $ git diff
1245 diff --cc file.txt
1246 index 802992c,2b60207..0000000
1247 --- a/file.txt
1248 +++ b/file.txt
1249 @@@ -1,1 -1,1 +1,5 @@@
1250 ++<<<<<<< HEAD:file.txt
1251  +Hello world
1252 ++=======
1253 + Goodbye
1254 ++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1255 -------------------------------------------------
1257 Recall that the commit which will be commited after we resolve this
1258 conflict will have two parents instead of the usual one: one parent
1259 will be HEAD, the tip of the current branch; the other will be the
1260 tip of the other branch, which is stored temporarily in MERGE_HEAD.
1262 The diff above shows the differences between the working-tree version
1263 of file.txt and two previous version: one version from HEAD, and one
1264 from MERGE_HEAD.  So instead of preceding each line by a single "+"
1265 or "-", it now uses two columns: the first column is used for
1266 differences between the first parent and the working directory copy,
1267 and the second for differences between the second parent and the
1268 working directory copy.  Thus after resolving the conflict in the
1269 obvious way, the diff will look like:
1271 -------------------------------------------------
1272 $ git diff
1273 diff --cc file.txt
1274 index 802992c,2b60207..0000000
1275 --- a/file.txt
1276 +++ b/file.txt
1277 @@@ -1,1 -1,1 +1,1 @@@
1278 - Hello world
1279  -Goodbye
1280 ++Goodbye world
1281 -------------------------------------------------
1283 This shows that our resolved version deleted "Hello world" from the
1284 first parent, deleted "Goodbye" from the second parent, and added
1285 "Goodbye world", which was previously absent from both.
1287 The gitlink:git-log[1] command also provides special help for merges:
1289 -------------------------------------------------
1290 $ git log --merge
1291 -------------------------------------------------
1293 This will list all commits which exist only on HEAD or on MERGE_HEAD,
1294 and which touch an unmerged file.
1296 We can now add the resolved version to the index and commit:
1298 -------------------------------------------------
1299 $ git add file.txt
1300 $ git commit
1301 -------------------------------------------------
1303 Note that the commit message will already be filled in for you with
1304 some information about the merge.  Normally you can just use this
1305 default message unchanged, but you may add additional commentary of
1306 your own if desired.
1308 [[undoing-a-merge]]
1309 undoing a merge
1310 ---------------
1312 If you get stuck and decide to just give up and throw the whole mess
1313 away, you can always return to the pre-merge state with
1315 -------------------------------------------------
1316 $ git reset --hard HEAD
1317 -------------------------------------------------
1319 Or, if you've already commited the merge that you want to throw away,
1321 -------------------------------------------------
1322 $ git reset --hard HEAD^
1323 -------------------------------------------------
1325 However, this last command can be dangerous in some cases--never
1326 throw away a commit you have already committed if that commit may
1327 itself have been merged into another branch, as doing so may confuse
1328 further merges.
1330 Fast-forward merges
1331 -------------------
1333 There is one special case not mentioned above, which is treated
1334 differently.  Normally, a merge results in a merge commit, with two
1335 parents, one pointing at each of the two lines of development that
1336 were merged.
1338 However, if one of the two lines of development is completely
1339 contained within the other--so every commit present in the one is
1340 already contained in the other--then git just performs a
1341 <<fast-forwards,fast forward>>; the head of the current branch is
1342 moved forward to point at the head of the merged-in branch, without
1343 any new commits being created.
1345 Fixing mistakes
1346 ---------------
1348 If you've messed up the working tree, but haven't yet committed your
1349 mistake, you can return the entire working tree to the last committed
1350 state with
1352 -------------------------------------------------
1353 $ git reset --hard HEAD
1354 -------------------------------------------------
1356 If you make a commit that you later wish you hadn't, there are two
1357 fundamentally different ways to fix the problem:
1359         1. You can create a new commit that undoes whatever was done
1360         by the previous commit.  This is the correct thing if your
1361         mistake has already been made public.
1363         2. You can go back and modify the old commit.  You should
1364         never do this if you have already made the history public;
1365         git does not normally expect the "history" of a project to
1366         change, and cannot correctly perform repeated merges from
1367         a branch that has had its history changed.
1369 Fixing a mistake with a new commit
1370 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1372 Creating a new commit that reverts an earlier change is very easy;
1373 just pass the gitlink:git-revert[1] command a reference to the bad
1374 commit; for example, to revert the most recent commit:
1376 -------------------------------------------------
1377 $ git revert HEAD
1378 -------------------------------------------------
1380 This will create a new commit which undoes the change in HEAD.  You
1381 will be given a chance to edit the commit message for the new commit.
1383 You can also revert an earlier change, for example, the next-to-last:
1385 -------------------------------------------------
1386 $ git revert HEAD^
1387 -------------------------------------------------
1389 In this case git will attempt to undo the old change while leaving
1390 intact any changes made since then.  If more recent changes overlap
1391 with the changes to be reverted, then you will be asked to fix
1392 conflicts manually, just as in the case of <<resolving-a-merge,
1393 resolving a merge>>.
1395 Fixing a mistake by editing history
1396 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1398 If the problematic commit is the most recent commit, and you have not
1399 yet made that commit public, then you may just
1400 <<undoing-a-merge,destroy it using git-reset>>.
1402 Alternatively, you
1403 can edit the working directory and update the index to fix your
1404 mistake, just as if you were going to <<how-to-make-a-commit,create a
1405 new commit>>, then run
1407 -------------------------------------------------
1408 $ git commit --amend
1409 -------------------------------------------------
1411 which will replace the old commit by a new commit incorporating your
1412 changes, giving you a chance to edit the old commit message first.
1414 Again, you should never do this to a commit that may already have
1415 been merged into another branch; use gitlink:git-revert[1] instead in
1416 that case.
1418 It is also possible to edit commits further back in the history, but
1419 this is an advanced topic to be left for
1420 <<cleaning-up-history,another chapter>>.
1422 Checking out an old version of a file
1423 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1425 In the process of undoing a previous bad change, you may find it
1426 useful to check out an older version of a particular file using
1427 gitlink:git-checkout[1].  We've used git checkout before to switch
1428 branches, but it has quite different behavior if it is given a path
1429 name: the command
1431 -------------------------------------------------
1432 $ git checkout HEAD^ path/to/file
1433 -------------------------------------------------
1435 replaces path/to/file by the contents it had in the commit HEAD^, and
1436 also updates the index to match.  It does not change branches.
1438 If you just want to look at an old version of the file, without
1439 modifying the working directory, you can do that with
1440 gitlink:git-show[1]:
1442 -------------------------------------------------
1443 $ git show HEAD^ path/to/file
1444 -------------------------------------------------
1446 which will display the given version of the file.
1448 Ensuring good performance
1449 -------------------------
1451 On large repositories, git depends on compression to keep the history
1452 information from taking up to much space on disk or in memory.
1454 This compression is not performed automatically.  Therefore you
1455 should occasionally run
1457 -------------------------------------------------
1458 $ git gc
1459 -------------------------------------------------
1461 to recompress the archive and to prune any commits which are no
1462 longer referred to anywhere.  This can be very time-consuming, and
1463 you should not modify the repository while it is working, so you
1464 should run it while you are not working.
1466 Sharing development with others
1467 ===============================
1469 [[getting-updates-with-git-pull]]
1470 Getting updates with git pull
1471 -----------------------------
1473 After you clone a repository and make a few changes of your own, you
1474 may wish to check the original repository for updates and merge them
1475 into your own work.
1477 We have already seen <<Updating-a-repository-with-git-fetch,how to
1478 keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1479 and how to merge two branches.  So you can merge in changes from the
1480 original repository's master branch with:
1482 -------------------------------------------------
1483 $ git fetch
1484 $ git merge origin/master
1485 -------------------------------------------------
1487 However, the gitlink:git-pull[1] command provides a way to do this in
1488 one step:
1490 -------------------------------------------------
1491 $ git pull origin master
1492 -------------------------------------------------
1494 In fact, "origin" is normally the default repository to pull from,
1495 and the default branch is normally the HEAD of the remote repository,
1496 so often you can accomplish the above with just
1498 -------------------------------------------------
1499 $ git pull
1500 -------------------------------------------------
1502 See the descriptions of the branch.<name>.remote and
1503 branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1504 how to control these defaults depending on the current branch.
1506 In addition to saving you keystrokes, "git pull" also helps you by
1507 producing a default commit message documenting the branch and
1508 repository that you pulled from.
1510 (But note that no such commit will be created in the case of a
1511 <<fast-forwards,fast forward>>; instead, your branch will just be
1512 updated to point to the latest commit from the upstream branch).
1514 The git-pull command can also be given "." as the "remote" repository, in
1515 which case it just merges in a branch from the current repository; so
1516 the commands
1518 -------------------------------------------------
1519 $ git pull . branch
1520 $ git merge branch
1521 -------------------------------------------------
1523 are roughly equivalent.  The former is actually very commonly used.
1525 Submitting patches to a project
1526 -------------------------------
1528 If you just have a few changes, the simplest way to submit them may
1529 just be to send them as patches in email:
1531 First, use gitlink:git-format-patches[1]; for example:
1533 -------------------------------------------------
1534 $ git format-patch origin
1535 -------------------------------------------------
1537 will produce a numbered series of files in the current directory, one
1538 for each patch in the current branch but not in origin/HEAD.
1540 You can then import these into your mail client and send them by
1541 hand.  However, if you have a lot to send at once, you may prefer to
1542 use the gitlink:git-send-email[1] script to automate the process.
1543 Consult the mailing list for your project first to determine how they
1544 prefer such patches be handled.
1546 Importing patches to a project
1547 ------------------------------
1549 Git also provides a tool called gitlink:git-am[1] (am stands for
1550 "apply mailbox"), for importing such an emailed series of patches.
1551 Just save all of the patch-containing messages, in order, into a
1552 single mailbox file, say "patches.mbox", then run
1554 -------------------------------------------------
1555 $ git am -3 patches.mbox
1556 -------------------------------------------------
1558 Git will apply each patch in order; if any conflicts are found, it
1559 will stop, and you can fix the conflicts as described in
1560 "<<resolving-a-merge,Resolving a merge>>".  (The "-3" option tells
1561 git to perform a merge; if you would prefer it just to abort and
1562 leave your tree and index untouched, you may omit that option.)
1564 Once the index is updated with the results of the conflict
1565 resolution, instead of creating a new commit, just run
1567 -------------------------------------------------
1568 $ git am --resolved
1569 -------------------------------------------------
1571 and git will create the commit for you and continue applying the
1572 remaining patches from the mailbox.
1574 The final result will be a series of commits, one for each patch in
1575 the original mailbox, with authorship and commit log message each
1576 taken from the message containing each patch.
1578 [[setting-up-a-public-repository]]
1579 Setting up a public repository
1580 ------------------------------
1582 Another way to submit changes to a project is to simply tell the
1583 maintainer of that project to pull from your repository, exactly as
1584 you did in the section "<<getting-updates-with-git-pull, Getting
1585 updates with git pull>>".
1587 If you and maintainer both have accounts on the same machine, then
1588 then you can just pull changes from each other's repositories
1589 directly; note that all of the command (gitlink:git-clone[1],
1590 git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1591 will also accept a local file patch; so, for example, you can
1592 use
1594 -------------------------------------------------
1595 $ git clone /path/to/repository
1596 $ git pull /path/to/other/repository
1597 -------------------------------------------------
1599 If this sort of setup is inconvenient or impossible, another (more
1600 common) option is to set up a public repository on a public server.
1601 This also allows you to cleanly separate private work in progress
1602 from publicly visible work.
1604 You will continue to do your day-to-day work in your personal
1605 repository, but periodically "push" changes from your personal
1606 repository into your public repository, allowing other developers to
1607 pull from that repository.  So the flow of changes, in a situation
1608 where there is one other developer with a public repository, looks
1609 like this:
1611                         you push
1612   your personal repo ------------------> your public repo
1613         ^                                     |
1614         |                                     |
1615         | you pull                            | they pull
1616         |                                     |
1617         |                                     |
1618         |               they push             V
1619   their public repo <------------------- their repo
1621 Now, assume your personal repository is in the directory ~/proj.  We
1622 first create a new clone of the repository:
1624 -------------------------------------------------
1625 $ git clone --bare proj-clone.git
1626 -------------------------------------------------
1628 The resulting directory proj-clone.git will contains a "bare" git
1629 repository--it is just the contents of the ".git" directory, without
1630 a checked-out copy of a working directory.
1632 Next, copy proj-clone.git to the server where you plan to host the
1633 public repository.  You can use scp, rsync, or whatever is most
1634 convenient.
1636 If somebody else maintains the public server, they may already have
1637 set up a git service for you, and you may skip to the section
1638 "<<pushing-changes-to-a-public-repository,Pushing changes to a public
1639 repository>>", below.
1641 Otherwise, the following sections explain how to export your newly
1642 created public repository:
1644 [[exporting-via-http]]
1645 Exporting a git repository via http
1646 -----------------------------------
1648 The git protocol gives better performance and reliability, but on a
1649 host with a web server set up, http exports may be simpler to set up.
1651 All you need to do is place the newly created bare git repository in
1652 a directory that is exported by the web server, and make some
1653 adjustments to give web clients some extra information they need:
1655 -------------------------------------------------
1656 $ mv proj.git /home/you/public_html/proj.git
1657 $ cd proj.git
1658 $ git update-server-info
1659 $ chmod a+x hooks/post-update
1660 -------------------------------------------------
1662 (For an explanation of the last two lines, see
1663 gitlink:git-update-server-info[1], and the documentation
1664 link:hooks.txt[Hooks used by git].)
1666 Advertise the url of proj.git.  Anybody else should then be able to
1667 clone or pull from that url, for example with a commandline like:
1669 -------------------------------------------------
1670 $ git clone http://yourserver.com/~you/proj.git
1671 -------------------------------------------------
1673 (See also
1674 link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1675 for a slightly more sophisticated setup using WebDAV which also
1676 allows pushing over http.)
1678 [[exporting-via-git]]
1679 Exporting a git repository via the git protocol
1680 -----------------------------------------------
1682 This is the preferred method.
1684 For now, we refer you to the gitlink:git-daemon[1] man page for
1685 instructions.  (See especially the examples section.)
1687 [[pushing-changes-to-a-public-repository]]
1688 Pushing changes to a public repository
1689 --------------------------------------
1691 Note that the two techniques outline above (exporting via
1692 <<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1693 maintainers to fetch your latest changes, but they do not allow write
1694 access, which you will need to update the public repository with the
1695 latest changes created in your private repository.
1697 The simplest way to do this is using gitlink:git-push[1] and ssh; to
1698 update the remote branch named "master" with the latest state of your
1699 branch named "master", run
1701 -------------------------------------------------
1702 $ git push ssh://yourserver.com/~you/proj.git master:master
1703 -------------------------------------------------
1705 or just
1707 -------------------------------------------------
1708 $ git push ssh://yourserver.com/~you/proj.git master
1709 -------------------------------------------------
1711 As with git-fetch, git-push will complain if this does not result in
1712 a <<fast-forwards,fast forward>>.  Normally this is a sign of
1713 something wrong.  However, if you are sure you know what you're
1714 doing, you may force git-push to perform the update anyway by
1715 proceeding the branch name by a plus sign:
1717 -------------------------------------------------
1718 $ git push ssh://yourserver.com/~you/proj.git +master
1719 -------------------------------------------------
1721 As with git-fetch, you may also set up configuration options to
1722 save typing; so, for example, after
1724 -------------------------------------------------
1725 $ cat >.git/config <<EOF
1726 [remote "public-repo"]
1727         url = ssh://yourserver.com/~you/proj.git
1728 EOF
1729 -------------------------------------------------
1731 you should be able to perform the above push with just
1733 -------------------------------------------------
1734 $ git push public-repo master
1735 -------------------------------------------------
1737 See the explanations of the remote.<name>.url, branch.<name>.remote,
1738 and remote.<name>.push options in gitlink:git-repo-config[1] for
1739 details.
1741 Setting up a shared repository
1742 ------------------------------
1744 Another way to collaborate is by using a model similar to that
1745 commonly used in CVS, where several developers with special rights
1746 all push to and pull from a single shared repository.  See
1747 link:cvs-migration.txt[git for CVS users] for instructions on how to
1748 set this up.
1750 Allow web browsing of a repository
1751 ----------------------------------
1753 TODO: Brief setup-instructions for gitweb
1755 Examples
1756 --------
1758 TODO: topic branches, typical roles as in everyday.txt, ?
1761 Working with other version control systems
1762 ==========================================
1764 TODO: CVS, Subversion, series-of-release-tarballs, ?
1766 [[cleaning-up-history]]
1767 Rewriting history and maintaining patch series
1768 ==============================================
1770 Normally commits are only added to a project, never taken away or
1771 replaced.  Git is designed with this assumption, and violating it will
1772 cause git's merge machinery (for example) to do the wrong thing.
1774 However, there is a situation in which it can be useful to violate this
1775 assumption.
1777 Creating the perfect patch series
1778 ---------------------------------
1780 Suppose you are a contributor to a large project, and you want to add a
1781 complicated feature, and to present it to the other developers in a way
1782 that makes it easy for them to read your changes, verify that they are
1783 correct, and understand why you made each change.
1785 If you present all of your changes as a single patch (or commit), they may
1786 find it is too much to digest all at once.
1788 If you present them with the entire history of your work, complete with
1789 mistakes, corrections, and dead ends, they may be overwhelmed.
1791 So the ideal is usually to produce a series of patches such that:
1793         1. Each patch can be applied in order.
1795         2. Each patch includes a single logical change, together with a
1796            message explaining the change.
1798         3. No patch introduces a regression: after applying any initial
1799            part of the series, the resulting project still compiles and
1800            works, and has no bugs that it didn't have before.
1802         4. The complete series produces the same end result as your own
1803            (probably much messier!) development process did.
1805 We will introduce some tools that can help you do this, explain how to use
1806 them, and then explain some of the problems that can arise because you are
1807 rewriting history.
1809 Keeping a patch series up to date using git-rebase
1810 --------------------------------------------------
1812 Suppose you have a series of commits in a branch "mywork", which
1813 originally branched off from "origin".
1815 Suppose you create a branch "mywork" on a remote-tracking branch "origin",
1816 and created some commits on top of it:
1818 -------------------------------------------------
1819 $ git checkout -b mywork origin
1820 $ vi file.txt
1821 $ git commit
1822 $ vi otherfile.txt
1823 $ git commit
1824 ...
1825 -------------------------------------------------
1827 You have performed no merges into mywork, so it is just a simple linear
1828 sequence of patches on top of "origin":
1831  o--o--o <-- origin
1832         \
1833          o--o--o <-- mywork
1835 Some more interesting work has been done in the upstream project, and
1836 "origin" has advanced:
1838  o--o--O--o--o--o <-- origin
1839         \
1840          a--b--c <-- mywork
1842 At this point, you could use "pull" to merge your changes back in;
1843 the result would create a new merge commit, like this:
1846  o--o--O--o--o--o <-- origin
1847         \        \
1848          a--b--c--m <-- mywork
1849  
1850 However, if you prefer to keep the history in mywork a simple series of
1851 commits without any merges, you may instead choose to use
1852 gitlink:git-rebase[1]:
1854 -------------------------------------------------
1855 $ git checkout mywork
1856 $ git rebase origin
1857 -------------------------------------------------
1859 This will remove each of your commits from mywork, temporarily saving them
1860 as patches (in a directory named ".dotest"), update mywork to point at the
1861 latest version of origin, then apply each of the saved patches to the new
1862 mywork.  The result will look like:
1865  o--o--O--o--o--o <-- origin
1866                  \
1867                   a'--b'--c' <-- mywork
1869 In the process, it may discover conflicts.  In that case it will stop and
1870 allow you to fix the conflicts as described in
1871 "<<resolving-a-merge,Resolving a merge>>".
1873 XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1874 no MERGE_HEAD.
1876 Once the index is updated with
1877 the results of the conflict resolution, instead of creating a new commit,
1878 just run
1880 -------------------------------------------------
1881 $ git rebase --continue
1882 -------------------------------------------------
1884 and git will continue applying the rest of the patches.
1886 At any point you may use the --abort option to abort this process and
1887 return mywork to the state it had before you started the rebase:
1889 -------------------------------------------------
1890 $ git rebase --abort
1891 -------------------------------------------------
1893 Reordering or selecting from a patch series
1894 -------------------------------------------
1896 Given one existing commit, the gitlink:git-cherry-pick[1] command allows
1897 you to apply the change introduced by that commit and create a new commit
1898 that records it.
1900 This can be useful for modifying a patch series.
1902 TODO: elaborate
1904 Other tools
1905 -----------
1907 There are numerous other tools, such as stgit, which exist for the purpose
1908 of maintianing a patch series.  These are out of the scope of this manual.
1910 Problems with rewriting history
1911 -------------------------------
1913 The primary problem with rewriting the history of a branch has to do with
1914 merging.
1916 TODO: elaborate
1919 Git internals
1920 =============
1922 Architectural overview
1923 ----------------------
1925 TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1927 Glossary of git terms
1928 =====================
1930 include::glossary.txt[]
1932 Notes and todo list for this manual
1933 ===================================
1935 This is a work in progress.
1937 The basic requirements:
1938         - It must be readable in order, from beginning to end, by
1939           someone intelligent with a basic grasp of the unix
1940           commandline, but without any special knowledge of git.  If
1941           necessary, any other prerequisites should be specifically
1942           mentioned as they arise.
1943         - Whenever possible, section headings should clearly describe
1944           the task they explain how to do, in language that requires
1945           no more knowledge than necessary: for example, "importing
1946           patches into a project" rather than "the git-am command"
1948 Think about how to create a clear chapter dependency graph that will
1949 allow people to get to important topics without necessarily reading
1950 everything in between.
1952 Scan Documentation/ for other stuff left out; in particular:
1953         howto's
1954         README
1955         some of technical/?
1956         hooks
1957         etc.
1959 Scan email archives for other stuff left out
1961 Scan man pages to see if any assume more background than this manual
1962 provides.
1964 Simplify beginning by suggesting disconnected head instead of
1965 temporary branch creation.
1967 Explain how to refer to file stages in the "how to resolve a merge"
1968 section: diff -1, -2, -3, --ours, --theirs :1:/path notation.  The
1969 "git ls-files --unmerged --stage" thing is sorta useful too,
1970 actually.  And note gitk --merge.  Also what's easiest way to see
1971 common merge base?  Note also text where I claim rebase and am
1972 conflicts are resolved like merges isn't generally true, at least by
1973 default--fix.
1975 Add more good examples.  Entire sections of just cookbook examples
1976 might be a good idea; maybe make an "advanced examples" section a
1977 standard end-of-chapter section?
1979 Include cross-references to the glossary, where appropriate.
1981 Add quickstart as first chapter.
1983 To document:
1984         reflogs, git reflog expire
1985         shallow clones??  See draft 1.5.0 release notes for some documentation.