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