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