Documentation: add git user's manual
[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
7Comprehensive reference documentation is available through the man
8pages. For a command such as "git clone", just use
9
10------------------------------------------------
11$ man git-clone
12------------------------------------------------
13
14Repositories and Branches
15=========================
16
17How to get a git repository
18---------------------------
19
20It will be useful to have a git repository to experiment with as you
21read this manual.
22
23The best way to get one is by using the gitlink:git-clone[1] command
24to download a copy of an existing repository for a project that you
25are interested in. If you don't already have a project in mind, here
26are some interesting examples:
27
28------------------------------------------------
29 # git itself (approx. 10MB download):
30$ git clone git://git.kernel.org/pub/scm/git/git.git
31 # the linux kernel (approx. 150MB download):
32$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
33------------------------------------------------
34
35The initial clone may be time-consuming for a large project, but you
36will only need to clone once.
37
38The clone command creates a new directory named after the project
39("git" or "linux-2.6" in the examples above). After you cd into this
40directory, you will see that it contains a copy of the project files,
41together with a special top-level directory named ".git", which
42contains all the information about the history of the project.
43
44In the following, examples will be taken from one of the two
45repositories above.
46
47How to check out a different version of a project
48-------------------------------------------------
49
50Git is best thought of as a tool for storing the history of a
51collection of files. It stores the history as a compressed
52collection of interrelated snapshots (versions) of the project's
53contents.
54
55A single git repository may contain multiple branches. Each branch
56is a bookmark referencing a particular point in the project history.
57The gitlink:git-branch[1] command shows you the list of branches:
58
59------------------------------------------------
60$ git branch
61* master
62------------------------------------------------
63
64A freshly cloned repository contains a single branch, named "master",
65and the working directory contains the version of the project
66referred to by the master branch.
67
68Most projects also use tags. Tags, like branches, are references
69into the project's history, and can be listed using the
70gitlink:git-tag[1] command:
71
72------------------------------------------------
73$ git tag -l
74v2.6.11
75v2.6.11-tree
76v2.6.12
77v2.6.12-rc2
78v2.6.12-rc3
79v2.6.12-rc4
80v2.6.12-rc5
81v2.6.12-rc6
82v2.6.13
83...
84------------------------------------------------
85
86Create a new branch pointing to one of these versions and check it
87out using gitlink:git-checkout[1]:
88
89------------------------------------------------
90$ git checkout -b new v2.6.13
91------------------------------------------------
92
93The working directory then reflects the contents that the project had
94when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
95branches, with an asterisk marking the currently checked-out branch:
96
97------------------------------------------------
98$ git branch
99 master
100* new
101------------------------------------------------
102
103If you decide that you'd rather see version 2.6.17, you can modify
104the current branch to point at v2.6.17 instead, with
105
106------------------------------------------------
107$ git reset --hard v2.6.17
108------------------------------------------------
109
110Note that if the current branch was your only reference to a
111particular point in history, then resetting that branch may leave you
112with no way to find the history it used to point to; so use this
113command carefully.
114
115Understanding History: Commits
116------------------------------
117
118Every change in the history of a project is represented by a commit.
119The gitlink:git-show[1] command shows the most recent commit on the
120current branch:
121
122------------------------------------------------
123$ git show
124commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
125Author: Jamal Hadi Salim <hadi@cyberus.ca>
126Date: Sat Dec 2 22:22:25 2006 -0800
127
128 [XFRM]: Fix aevent structuring to be more complete.
129
130 aevents can not uniquely identify an SA. We break the ABI with this
131 patch, but consensus is that since it is not yet utilized by any
132 (known) application then it is fine (better do it now than later).
133
134 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
135 Signed-off-by: David S. Miller <davem@davemloft.net>
136
137diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
138index 8be626f..d7aac9d 100644
139--- a/Documentation/networking/xfrm_sync.txt
140+++ b/Documentation/networking/xfrm_sync.txt
141@@ -47,10 +47,13 @@ aevent_id structure looks like:
142
143 struct xfrm_aevent_id {
144 struct xfrm_usersa_id sa_id;
145+ xfrm_address_t saddr;
146 __u32 flags;
147+ __u32 reqid;
148 };
149...
150------------------------------------------------
151
152As you can see, a commit shows who made the latest change, what they
153did, and why.
154
155Every commit has a 20-digit id, sometimes called the "SHA1 id", shown
156on the first line of the "git show" output. You can usually refer to
157a commit by a shorter name, such as a tag or a branch name, but this
158longer id can also be useful. In particular, it is a globally unique
159name for this commit: so if you tell somebody else the SHA1 id (for
160example in email), then you are guaranteed they will see the same
161commit in their repository that you do in yours.
162
163Understanding history: commits, parents, and reachability
164~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165
166Every commit (except the very first commit in a project) also has a
167parent commit which shows what happened before this commit.
168Following the chain of parents will eventually take you back to the
169beginning of the project.
170
171However, the commits do not form a simple list; git allows lines of
172development to diverge and then reconverge, and the point where two
173lines of development reconverge is called a "merge". The commit
174representing a merge can therefore have more than one parent, with
175each parent representing the most recent commit on one of the lines
176of development leading to that point.
177
178The best way to see how this works is using the gitlink:gitk[1]
179command; running gitk now on a git repository and looking for merge
180commits will help understand how the git organizes history.
181
182In the following, we say that commit X is "reachable" from commit Y
183if commit X is an ancestor of commit Y. Equivalently, you could say
184that Y is a descendent of X, or that there is a chain of parents
185leading from commit Y to commit X.
186
187Undestanding history: History diagrams
188~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
190We will sometimes represent git history using diagrams like the one
191below. Commits are shown as "o", and the links between them with
192lines drawn with - / and \. Time goes left to right:
193
194 o--o--o <-- Branch A
195 /
196 o--o--o <-- master
197 \
198 o--o--o <-- Branch B
199
200If we need to talk about a particular commit, the character "o" may
201be replaced with another letter or number.
202
203Understanding history: What is a branch?
204~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205
206Though we've been using the word "branch" to mean a kind of reference
207to a particular commit, the word branch is also commonly used to
208refer to the line of commits leading up to that point. In the
209example above, git may think of the branch named "A" as just a
210pointer to one particular commit, but we may refer informally to the
211line of three commits leading up to that point as all being part of
212"branch A".
213
214If we need to make it clear that we're just talking about the most
215recent commit on the branch, we may refer to that commit as the
216"head" of the branch.
217
218Manipulating branches
219---------------------
220
221Creating, deleting, and modifying branches is quick and easy; here's
222a summary of the commands:
223
224git branch::
225 list all branches
226git branch <branch>::
227 create a new branch named <branch>, referencing the same
228 point in history as the current branch
229git branch <branch> <start-point>::
230 create a new branch named <branch>, referencing
231 <start-point>, which may be specified any way you like,
232 including using a branch name or a tag name
233git branch -d <branch>::
234 delete the branch <branch>; if the branch you are deleting
235 points to a commit which is not reachable from this branch,
236 this command will fail with a warning.
237git branch -D <branch>::
238 even if the branch points to a commit not reachable
239 from the current branch, you may know that that commit
240 is still reachable from some other branch or tag. In that
241 case it is safe to use this command to force git to delete
242 the branch.
243git checkout <branch>::
244 make the current branch <branch>, updating the working
245 directory to reflect the version referenced by <branch>
246git checkout -b <new> <start-point>::
247 create a new branch <new> referencing <start-point>, and
248 check it out.
249
250It is also useful to know that the special symbol "HEAD" can always
251be used to refer to the current branch.
252
253Examining branches from a remote repository
254-------------------------------------------
255
256The "master" branch that was created at the time you cloned is a copy
257of the HEAD in the repository that you cloned from. That repository
258may also have had other branches, though, and your local repository
259keeps branches which track each of those remote branches, which you
260can view using the "-r" option to gitlink:git-branch[1]:
261
262------------------------------------------------
263$ git branch -r
264 origin/HEAD
265 origin/html
266 origin/maint
267 origin/man
268 origin/master
269 origin/next
270 origin/pu
271 origin/todo
272------------------------------------------------
273
274You cannot check out these remote-tracking branches, but you can
275examine them on a branch of your own, just as you would a tag:
276
277------------------------------------------------
278$ git checkout -b my-todo-copy origin/todo
279------------------------------------------------
280
281Note that the name "origin" is just the name that git uses by default
282to refer to the repository that you cloned from.
283
284[[how-git-stores-references]]
285How git stores references
286-------------------------
287
288Branches, remote-tracking branches, and tags are all references to
289commits. Git stores these references in the ".git" directory. Most
290of them are stored in .git/refs/:
291
292 - branches are stored in .git/refs/heads
293 - tags are stored in .git/refs/tags
294 - remote-tracking branches for "origin" are stored in
295 .git/refs/remotes/origin/
296
297If you look at one of these files you will see that they usually
298contain just the SHA1 id of a commit:
299
300------------------------------------------------
301$ ls .git/refs/heads/
302master
303$ cat .git/refs/heads/master
304c0f982dcf188d55db9d932a39d4ea7becaa55fed
305------------------------------------------------
306
307You can refer to a reference by its path relative to the .git
308directory. However, we've seen above that git will also accept
309shorter names; for example, "master" is an acceptable shortcut for
310"refs/heads/master", and "origin/master" is a shortcut for
311"refs/remotes/origin/master".
312
313As another useful shortcut, you can also refer to the "HEAD" of
314"origin" (or any other remote), using just the name of the remote.
315
316For the complete list of paths which git checks for references, and
317how it decides which to choose when there are multiple references
318with the same name, see the "SPECIFYING REVISIONS" section of
319gitlink:git-rev-parse[1].
320
321[[Updating-a-repository-with-git-fetch]]
322Updating a repository with git fetch
323------------------------------------
324
325Eventually the developer cloned from will do additional work in her
326repository, creating new commits and advancing the branches to point
327at the new commits.
328
329The command "git fetch", with no arguments, will update all of the
330remote-tracking branches to the latest version found in her
331repository. It will not touch any of your own branches--not even the
332"master" branch that was created for you on clone.
333
334Fetching individual branches
335----------------------------
336
337You can also choose to update just one branch at a time:
338
339-------------------------------------------------
340$ git fetch origin todo:refs/remotes/origin/todo
341-------------------------------------------------
342
343The first argument, "origin", just tells git to fetch from the
344repository you originally cloned from. The second argument tells git
345to fetch the branch named "todo" from the remote repository, and to
346store it locally under the name refs/remotes/origin/todo; as we saw
347above, remote-tracking branches are stored under
348refs/remotes/<name-of-repository>/<name-of-branch>.
349
350You can also fetch branches from other repositories; so
351
352-------------------------------------------------
353$ git fetch git://example.com/proj.git master:refs/remotes/example/master
354-------------------------------------------------
355
356will create a new reference named "refs/remotes/example/master" and
357store in it the branch named "master" from the repository at the
358given URL. If you already have a branch named
359"refs/remotes/example/master", it will attempt to "fast-forward" to
360the commit given by example.com's master branch. So next we explain
361what a fast-forward is:
362
363[[fast-forwards]]
364Understanding git history: fast-forwards
365----------------------------------------
366
367In the previous example, when updating an existing branch, "git
368fetch" checks to make sure that the most recent commit on the remote
369branch is a descendant of the most recent commit on your copy of the
370branch before updating your copy of the branch to point at the new
371commit. Git calls this process a "fast forward".
372
373A fast forward looks something like this:
374
375 o--o--o--o <-- old head of the branch
376 \
377 o--o--o <-- new head of the branch
378
379
380In some cases it is possible that the new head will *not* actually be
381a descendant of the old head. For example, the developer may have
382realized she made a serious mistake, and decided to backtrack,
383resulting in a situation like:
384
385 o--o--o--o--a--b <-- old head of the branch
386 \
387 o--o--o <-- new head of the branch
388
389
390
391In this case, "git fetch" will fail, and print out a warning.
392
393In that case, you can still force git to update to the new head, as
394described in the following section. However, note that in the
395situation above this may mean losing the commits labeled "a" and "b",
396unless you've already created a reference of your own pointing to
397them.
398
399Forcing git fetch to do non-fast-forward updates
400------------------------------------------------
401
402If git fetch fails because the new head of a branch is not a
403descendant of the old head, you may force the update with:
404
405-------------------------------------------------
406$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
407-------------------------------------------------
408
409Note the addition of the "+" sign. Be aware that commits which the
410old version of example/master pointed at may be lost, as we saw in
411the previous section.
412
413Configuring remote branches
414---------------------------
415
416We saw above that "origin" is just a shortcut to refer to the
417repository which you originally cloned from. This information is
418stored in git configuration variables, which you can see using
419gitlink:git-repo-config[1]:
420
421-------------------------------------------------
422$ git-repo-config -l
423core.repositoryformatversion=0
424core.filemode=true
425core.logallrefupdates=true
426remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
427remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
428branch.master.remote=origin
429branch.master.merge=refs/heads/master
430-------------------------------------------------
431
432If there are other repositories that you also use frequently, you can
433create similar configuration options to save typing; for example,
434after
435
436-------------------------------------------------
437$ git repo-config remote.example.url=git://example.com/proj.git
438-------------------------------------------------
439
440then the following two commands will do the same thing:
441
442-------------------------------------------------
443$ git fetch git://example.com/proj.git master:refs/remotes/example/master
444$ git fetch example master:refs/remotes/example/master
445-------------------------------------------------
446
447Even better, if you add one more option:
448
449-------------------------------------------------
450$ git repo-config remote.example.fetch=master:refs/remotes/example/master
451-------------------------------------------------
452
453then the following commands will all do the same thing:
454
455-------------------------------------------------
456$ git fetch git://example.com/proj.git master:ref/remotes/example/master
457$ git fetch example master:ref/remotes/example/master
458$ git fetch example example/master
459$ git fetch example
460-------------------------------------------------
461
462You can also add a "+" to force the update each time:
463
464-------------------------------------------------
465$ git repo-config +master:ref/remotes/example/master
466-------------------------------------------------
467
468Don't do this unless you're sure you won't mind "git fetch" possibly
469throwing away commits on mybranch.
470
471Also note that all of the above configuration can be performed by
472directly editing the file .git/config instead of using
473gitlink:git-repo-config[1].
474
475See gitlink:git-repo-config[1] for more details on the configuration
476options mentioned above.
477
478Exploring git history
479=====================
480
481Git is best thought of as a tool for storing the history of a
482collection of files. It does this by storing compressed snapshots of
483the contents of a file heirarchy, together with "commits" which show
484the relationships between these snapshots.
485
486Git provides extremely flexible and fast tools for exploring the
487history of a project.
488
489We start with one specialized tool which is useful for finding the
490commit that introduced a bug into a project.
491
492How to use bisect to find a regression
493--------------------------------------
494
495Suppose version 2.6.18 of your project worked, but the version at
496"master" crashes. Sometimes the best way to find the cause of such a
497regression is to perform a brute-force search through the project's
498history to find the particular commit that caused the problem. The
499gitlink:git-bisect[1] command can help you do this:
500
501-------------------------------------------------
502$ git bisect start
503$ git bisect good v2.6.18
504$ git bisect bad master
505Bisecting: 3537 revisions left to test after this
506[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
507-------------------------------------------------
508
509If you run "git branch" at this point, you'll see that git has
510temporarily moved you to a new branch named "bisect". This branch
511points to a commit (with commit id 65934...) that is reachable from
512v2.6.19 but not from v2.6.18. Compile and test it, and see whether
513it crashes. Assume it does crash. Then:
514
515-------------------------------------------------
516$ git bisect bad
517Bisecting: 1769 revisions left to test after this
518[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
519-------------------------------------------------
520
521checks out an older version. Continue like this, telling git at each
522stage whether the version it gives you is good or bad, and notice
523that the number of revisions left to test is cut approximately in
524half each time.
525
526After about 13 tests (in this case), it will output the commit id of
527the guilty commit. You can then examine the commit with
528gitlink:git-show[1], find out who wrote it, and mail them your bug
529report with the commit id. Finally, run
530
531-------------------------------------------------
532$ git bisect reset
533-------------------------------------------------
534
535to return you to the branch you were on before and delete the
536temporary "bisect" branch.
537
538Note that the version which git-bisect checks out for you at each
539point is just a suggestion, and you're free to try a different
540version if you think it would be a good idea. For example,
541occasionally you may land on a commit that broke something unrelated;
542run
543
544-------------------------------------------------
545$ git bisect-visualize
546-------------------------------------------------
547
548which will run gitk and label the commit it chose with a marker that
549says "bisect". Chose a safe-looking commit nearby, note its commit
550id, and check it out with:
551
552-------------------------------------------------
553$ git reset --hard fb47ddb2db...
554-------------------------------------------------
555
556then test, run "bisect good" or "bisect bad" as appropriate, and
557continue.
558
559Naming commits
560--------------
561
562We have seen several ways of naming commits already:
563
564 - 20-digit SHA1 id
565 - branch name: refers to the commit at the head of the given
566 branch
567 - tag name: refers to the commit pointed to by the given tag
568 (we've seen branches and tags are special cases of
569 <<how-git-stores-references,references>>).
570 - HEAD: refers to the head of the current branch
571
572There are many more; see the "SPECIFYING REVISION" section of the
573gitlink:git-rev-list[1] man page for the complete list of ways to
574name revisions. Some examples:
575
576-------------------------------------------------
577$ git show fb47ddb2 # the first few characters of the SHA1 id
578 # are usually enough to specify it uniquely
579$ git show HEAD^ # the parent of the HEAD commit
580$ git show HEAD^^ # the grandparent
581$ git show HEAD~4 # the great-great-grandparent
582-------------------------------------------------
583
584Recall that merge commits may have more than one parent; by default,
585^ and ~ follow the first parent listed in the commit, but you can
586also choose:
587
588-------------------------------------------------
589$ git show HEAD^1 # show the first parent of HEAD
590$ git show HEAD^2 # show the second parent of HEAD
591-------------------------------------------------
592
593In addition to HEAD, there are several other special names for
594commits:
595
596Merges (to be discussed later), as well as operations such as
597git-reset, which change the currently checked-out commit, generally
598set ORIG_HEAD to the value HEAD had before the current operation.
599
600The git-fetch operation always stores the head of the last fetched
601branch in FETCH_HEAD. For example, if you run git fetch without
602specifying a local branch as the target of the operation
603
604-------------------------------------------------
605$ git fetch git://example.com/proj.git theirbranch
606-------------------------------------------------
607
608the fetched commits will still be available from FETCH_HEAD.
609
610When we discuss merges we'll also see the special name MERGE_HEAD,
611which refers to the other branch that we're merging in to the current
612branch.
613
614Creating tags
615-------------
616
617We can also create a tag to refer to a particular commit; after
618running
619
620-------------------------------------------------
621$ git-tag stable-1 1b2e1d63ff
622-------------------------------------------------
623
624You can use stable-1 to refer to the commit 1b2e1d63ff.
625
626This creates a "lightweight" tag. If the tag is a tag you wish to
627share with others, and possibly sign cryptographically, then you
628should create a tag object instead; see the gitlink:git-tag[1] man
629page for details.
630
631Browsing revisions
632------------------
633
634The gitlink:git-log[1] command can show lists of commits. On its
635own, it shows all commits reachable from the parent commit; but you
636can also make more specific requests:
637
638-------------------------------------------------
639$ git log v2.5.. # commits since (not reachable from) v2.5
640$ git log test..master # commits reachable from master but not test
641$ git log master..test # ...reachable from test but not master
642$ git log master...test # ...reachable from either test or master,
643 # but not both
644$ git log --since="2 weeks ago" # commits from the last 2 weeks
645$ git log Makefile # commits which modify Makefile
646$ git log fs/ # ... which modify any file under fs/
647$ git log -S'foo()' # commits which add or remove any file data
648 # matching the string 'foo()'
649-------------------------------------------------
650
651And of course you can combine all of these; the following finds
652commits since v2.5 which touch the Makefile or any file under fs:
653
654-------------------------------------------------
655$ git log v2.5.. Makefile fs/
656-------------------------------------------------
657
658You can also ask git log to show patches:
659
660-------------------------------------------------
661$ git log -p
662-------------------------------------------------
663
664See the "--pretty" option in the gitlink:git-log[1] man page for more
665display options.
666
667Note that git log starts with the most recent commit and works
668backwards through the parents; however, since git history can contain
669multiple independant lines of development, the particular order that
670commits are listed in may be somewhat arbitrary.
671
672Generating diffs
673----------------
674
675You can generate diffs between any two versions using
676gitlink:git-diff[1]:
677
678-------------------------------------------------
679$ git diff master..test
680-------------------------------------------------
681
682Sometimes what you want instead is a set of patches:
683
684-------------------------------------------------
685$ git format-patch master..test
686-------------------------------------------------
687
688will generate a file with a patch for each commit reachable from test
689but not from master. Note that if master also has commits which are
690not reachable from test, then the combined result of these patches
691will not be the same as the diff produced by the git-diff example.
692
693Viewing old file versions
694-------------------------
695
696You can always view an old version of a file by just checking out the
697correct revision first. But sometimes it is more convenient to be
698able to view an old version of a single file without checking
699anything out; this command does that:
700
701-------------------------------------------------
702$ git show v2.5:fs/locks.c
703-------------------------------------------------
704
705Before the colon may be anything that names a commit, and after it
706may be any path to a file tracked by git.
707
708Developing with git
709===================
710
711Telling git your name
712---------------------
713
714Before creating any commits, you should introduce yourself to git. The
715easiest way to do so is:
716
717------------------------------------------------
718$ cat >~/.gitconfig <<\EOF
719[user]
720 name = Your Name Comes Here
721 email = you@yourdomain.example.com
722EOF
723------------------------------------------------
724
725
726Creating a new repository
727-------------------------
728
729Creating a new repository from scratch is very easy:
730
731-------------------------------------------------
732$ mkdir project
733$ cd project
734$ git init-db
735-------------------------------------------------
736
737If you have some initial content (say, a tarball):
738
739-------------------------------------------------
740$ tar -xzvf project.tar.gz
741$ cd project
742$ git init-db
743$ git add . # include everything below ./ in the first commit:
744$ git commit
745-------------------------------------------------
746
747[[how-to-make-a-commit]]
748how to make a commit
749--------------------
750
751Creating a new commit takes three steps:
752
753 1. Making some changes to the working directory using your
754 favorite editor.
755 2. Telling git about your changes.
756 3. Creating the commit using the content you told git about
757 in step 2.
758
759In practice, you can interleave and repeat steps 1 and 2 as many
760times as you want: in order to keep track of what you want committed
761at step 3, git maintains a snapshot of the tree's contents in a
762special staging area called "the index."
763
764By default, the content of the index is identical to that of the
765HEAD. The command "git diff --cached" shows the difference between
766HEAD and the index, so you should no output from that command.
767
768Modifying the index is easy:
769
770To update the index with the new contents of a modified file, use
771
772-------------------------------------------------
773$ git add path/to/file
774-------------------------------------------------
775
776To add the contents of a new file to the index, use
777
778-------------------------------------------------
779$ git add path/to/file
780-------------------------------------------------
781
782To remove a file from the index that you've removed from the working
783tree,
784
785-------------------------------------------------
786$ git rm path/to/file
787-------------------------------------------------
788
789After each step you can verify that
790
791-------------------------------------------------
792$ git diff --cached
793-------------------------------------------------
794
795always shows the difference between the HEAD and the index file--this
796is what you'd commit if you created the commit now--and that
797
798-------------------------------------------------
799$ git diff
800-------------------------------------------------
801
802shows the difference between the working tree and the index file.
803
804Note that "git add" always adds just the current contents of a file
805to the index; further changes to the same file will be ignored unless
806you run git-add on the file again.
807
808When you're ready, just run
809
810-------------------------------------------------
811$ git commit
812-------------------------------------------------
813
814and git will prompt you for a commit message and then create the new
815commmit. Check to make sure it looks like what you expected with
816
817-------------------------------------------------
818$ git show
819-------------------------------------------------
820
821As a special shortcut,
822
823-------------------------------------------------
824$ git commit -a
825-------------------------------------------------
826
827will update the index with any files that you've modified or removed
828and create a commit, all in one step.
829
830A number of commands are useful for keeping track of what you're
831about to commit:
832
833-------------------------------------------------
834$ git diff --cached # difference between HEAD and the index; what
835 # would be commited if you ran "commit" now.
836$ git diff # difference between the index file and your
837 # working directory; changes that would not
838 # be included if you ran "commit" now.
839$ git status # a brief per-file summary of the above.
840-------------------------------------------------
841
842creating good commit messages
843-----------------------------
844
845Though not required, it's a good idea to begin the commit message
846with a single short (less than 50 character) line summarizing the
847change, followed by a blank line and then a more thorough
848description. Tools that turn commits into email, for example, use
849the first line on the Subject line and the rest of the commit in the
850body.
851
852how to merge
853------------
854
855You can rejoin two diverging branches of development using
856gitlink:git-merge[1]:
857
858-------------------------------------------------
859$ git merge branchname
860-------------------------------------------------
861
862merges the development in the branch "branchname" into the current
863branch. If there are conflicts--for example, if the same file is
864modified in two different ways in the remote branch and the local
865branch--then you are warned; the output may look something like this:
866
867-------------------------------------------------
868$ git pull . next
869Trying really trivial in-index merge...
870fatal: Merge requires file-level merging
871Nope.
872Merging HEAD with 77976da35a11db4580b80ae27e8d65caf5208086
873Merging:
87415e2162 world
87577976da goodbye
876found 1 common ancestor(s):
877d122ed4 initial
878Auto-merging file.txt
879CONFLICT (content): Merge conflict in file.txt
880Automatic merge failed; fix conflicts and then commit the result.
881-------------------------------------------------
882
883Conflict markers are left in the problematic files, and after
884you resolve the conflicts manually, you can update the index
885with the contents and run git commit, as you normally would when
886creating a new file.
887
888If you examine the resulting commit using gitk, you will see that it
889has two parents, one pointing to the top of the current branch, and
890one to the top of the other branch.
891
892In more detail:
893
894[[resolving-a-merge]]
895Resolving a merge
896-----------------
897
898When a merge isn't resolved automatically, git leaves the index and
899the working tree in a special state that gives you all the
900information you need to help resolve the merge.
901
902Files with conflicts are marked specially in the index, so until you
903resolve the problem and update the index, git commit will fail:
904
905-------------------------------------------------
906$ git commit
907file.txt: needs merge
908-------------------------------------------------
909
910Also, git status will list those files as "unmerged".
911
912All of the changes that git was able to merge automatically are
913already added to the index file, so gitlink:git-diff[1] shows only
914the conflicts. Also, it uses a somewhat unusual syntax:
915
916-------------------------------------------------
917$ git diff
918diff --cc file.txt
919index 802992c,2b60207..0000000
920--- a/file.txt
921+++ b/file.txt
922@@@ -1,1 -1,1 +1,5 @@@
923++<<<<<<< HEAD:file.txt
924 +Hello world
925++=======
926+ Goodbye
927++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
928-------------------------------------------------
929
930Recall that the commit which will be commited after we resolve this
931conflict will have two parents instead of the usual one: one parent
932will be HEAD, the tip of the current branch; the other will be the
933tip of the other branch, which is stored temporarily in MERGE_HEAD.
934
935The diff above shows the differences between the working-tree version
936of file.txt and two previous version: one version from HEAD, and one
937from MERGE_HEAD. So instead of preceding each line by a single "+"
938or "-", it now uses two columns: the first column is used for
939differences between the first parent and the working directory copy,
940and the second for differences between the second parent and the
941working directory copy. Thus after resolving the conflict in the
942obvious way, the diff will look like:
943
944-------------------------------------------------
945$ git diff
946diff --cc file.txt
947index 802992c,2b60207..0000000
948--- a/file.txt
949+++ b/file.txt
950@@@ -1,1 -1,1 +1,1 @@@
951- Hello world
952 -Goodbye
953++Goodbye world
954-------------------------------------------------
955
956This shows that our resolved version deleted "Hello world" from the
957first parent, deleted "Goodbye" from the second parent, and added
958"Goodbye world", which was previously absent from both.
959
960The gitlink:git-log[1] command also provides special help for merges:
961
962-------------------------------------------------
963$ git log --merge
964-------------------------------------------------
965
966This will list all commits which exist only on HEAD or on MERGE_HEAD,
967and which touch an unmerged file.
968
969We can now add the resolved version to the index and commit:
970
971-------------------------------------------------
972$ git add file.txt
973$ git commit
974-------------------------------------------------
975
976Note that the commit message will already be filled in for you with
977some information about the merge. Normally you can just use this
978default message unchanged, but you may add additional commentary of
979your own if desired.
980
981[[undoing-a-merge]]
982undoing a merge
983---------------
984
985If you get stuck and decide to just give up and throw the whole mess
986away, you can always return to the pre-merge state with
987
988-------------------------------------------------
989$ git reset --hard HEAD
990-------------------------------------------------
991
992Or, if you've already commited the merge that you want to throw away,
993
994-------------------------------------------------
995$ git reset --hard HEAD^
996-------------------------------------------------
997
998However, this last command can be dangerous in some cases--never
999throw away a commit you have already committed if that commit may
1000itself have been merged into another branch, as doing so may confuse
1001further merges.
1002
1003Fast-forward merges
1004-------------------
1005
1006There is one special case not mentioned above, which is treated
1007differently. Normally, a merge results in a merge commit, with two
1008parents, one pointing at each of the two lines of development that
1009were merged.
1010
1011However, if one of the two lines of development is completely
1012contained within the other--so every commit present in the one is
1013already contained in the other--then git just performs a
1014<<fast-forwards,fast forward>>; the head of the current branch is
1015moved forward to point at the head of the merged-in branch, without
1016any new commits being created.
1017
1018Ensuring good performance
1019-------------------------
1020
1021On large repositories, git depends on compression to keep the history
1022information from taking up to much space on disk or in memory.
1023
1024This compression is not performed automatically. Therefore you
1025should occasionally run
1026
1027-------------------------------------------------
1028$ git gc
1029-------------------------------------------------
1030
1031to recompress the archive and to prune any commits which are no
1032longer referred to anywhere. This can be very time-consuming, and
1033you should not modify the repository while it is working, so you
1034should run it while you are not working.
1035
1036Sharing development with others
1037-------------------------------
1038
1039[[getting-updates-with-git-pull]]
1040Getting updates with git pull
1041~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1042
1043After you clone a repository and make a few changes of your own, you
1044may wish to check the original repository for updates and merge them
1045into your own work.
1046
1047We have already seen <<Updating-a-repository-with-git-fetch,how to
1048keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1049and how to merge two branches. So you can merge in changes from the
1050original repository's master branch with:
1051
1052-------------------------------------------------
1053$ git fetch
1054$ git merge origin/master
1055-------------------------------------------------
1056
1057However, the gitlink:git-pull[1] command provides a way to do this in
1058one step:
1059
1060-------------------------------------------------
1061$ git pull origin master
1062-------------------------------------------------
1063
1064In fact, "origin" is normally the default repository to pull from,
1065and the default branch is normally the HEAD of the remote repository,
1066so often you can accomplish the above with just
1067
1068-------------------------------------------------
1069$ git pull
1070-------------------------------------------------
1071
1072See the descriptions of the branch.<name>.remote and
1073branch.<name>.merge options in gitlink:git-repo-config[1] to learn
1074how to control these defaults depending on the current branch.
1075
1076In addition to saving you keystrokes, "git pull" also helps you by
1077producing a default commit message documenting the branch and
1078repository that you pulled from.
1079
1080(But note that no such commit will be created in the case of a
1081<<fast-forwards,fast forward>>; instead, your branch will just be
1082updated to point to the latest commit from the upstream branch).
1083
1084Submitting patches to a project
1085~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1086
1087If you just have a few changes, the simplest way to submit them may
1088just be to send them as patches in email:
1089
1090First, use gitlink:git-format-patches[1]; for example:
1091
1092-------------------------------------------------
1093$ git format-patches origin
1094-------------------------------------------------
1095
1096will produce a numbered series of files in the current directory, one
1097for each patch in the current branch but not in origin/HEAD.
1098
1099You can then import these into your mail client and send them by
1100hand. However, if you have a lot to send at once, you may prefer to
1101use the gitlink:git-send-email[1] script to automate the process.
1102Consult the mailing list for your project first to determine how they
1103prefer such patches be handled.
1104
1105Importing patches to a project
1106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1107
1108Git also provides a tool called gitlink:git-am[1] (am stands for
1109"apply mailbox"), for importing such an emailed series of patches.
1110Just save all of the patch-containing messages, in order, into a
1111single mailbox file, say "patches.mbox", then run
1112
1113-------------------------------------------------
1114$ git am patches.mbox
1115-------------------------------------------------
1116
1117Git will apply each patch in order; if any conflicts are found, it
1118will stop, and you can fix the conflicts as described in
1119"<<resolving-a-merge,Resolving a merge>>". Once the index is updated
1120with the results of the conflict resolution, instead of creating a
1121new commit, just run
1122
1123-------------------------------------------------
1124$ git am --resolved
1125-------------------------------------------------
1126
1127and git will create the commit for you and continue applying the
1128remaining patches from the mailbox.
1129
1130The final result will be a series of commits, one for each patch in
1131the original mailbox, with authorship and commit log message each
1132taken from the message containing each patch.
1133
1134[[setting-up-a-public-repository]]
1135Setting up a public repository
1136~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1137
1138Another way to submit changes to a project is to simply tell the
1139maintainer of that project to pull from your repository, exactly as
1140you did in the section "<<getting-updates-with-git-pull, Getting
1141updates with git pull>>".
1142
1143If you and maintainer both have accounts on the same machine, then
1144then you can just pull changes from each other's repositories
1145directly; note that all of the command (gitlink:git-clone[1],
1146git-fetch[1], git-pull[1], etc.) which accept a URL as an argument
1147will also accept a local file patch; so, for example, you can
1148use
1149
1150-------------------------------------------------
1151$ git clone /path/to/repository
1152$ git pull /path/to/other/repository
1153-------------------------------------------------
1154
1155If this sort of setup is inconvenient or impossible, another (more
1156common) option is to set up a public repository on a public server.
1157This also allows you to cleanly separate private work in progress
1158from publicly visible work.
1159
1160You will continue to do your day-to-day work in your personal
1161repository, but periodically "push" changes from your personal
1162repository into your public repository, allowing other developers to
1163pull from that repository. So the flow of changes, in a situation
1164where there is one other developer with a public repository, looks
1165like this:
1166
1167 you push
1168 your personal repo ------------------> your public repo
1169 ^ |
1170 | |
1171 | you pull | they pull
1172 | |
1173 | |
1174 | they push V
1175 their public repo <------------------- their repo
1176
1177Now, assume your personal repository is in the directory ~/proj. We
1178first create a new clone of the repository:
1179
1180-------------------------------------------------
1181$ git clone --bare proj-clone.git
1182-------------------------------------------------
1183
1184The resulting directory proj-clone.git will contains a "bare" git
1185repository--it is just the contents of the ".git" directory, without
1186a checked-out copy of a working directory.
1187
1188Next, copy proj-clone.git to the server where you plan to host the
1189public repository. You can use scp, rsync, or whatever is most
1190convenient.
1191
1192If somebody else maintains the public server, they may already have
1193set up a git service for you, and you may skip to the section
1194"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1195repository>>", below.
1196
1197Otherwise, the following sections explain how to export your newly
1198created public repository:
1199
1200[[exporting-via-http]]
1201Exporting a git repository via http
1202~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1203
1204The git protocol gives better performance and reliability, but on a
1205host with a web server set up, http exports may be simpler to set up.
1206
1207All you need to do is place the newly created bare git repository in
1208a directory that is exported by the web server, and make some
1209adjustments to give web clients some extra information they need:
1210
1211-------------------------------------------------
1212$ mv proj.git /home/you/public_html/proj.git
1213$ cd proj.git
1214$ git update-server-info
1215$ chmod a+x hooks/post-update
1216-------------------------------------------------
1217
1218(For an explanation of the last two lines, see
1219gitlink:git-update-server-info[1], and the documentation
1220link:hooks.txt[Hooks used by git].)
1221
1222Advertise the url of proj.git. Anybody else should then be able to
1223clone or pull from that url, for example with a commandline like:
1224
1225-------------------------------------------------
1226$ git clone http://yourserver.com/~you/proj.git
1227-------------------------------------------------
1228
1229(See also
1230link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1231for a slightly more sophisticated setup using WebDAV which also
1232allows pushing over http.)
1233
1234[[exporting-via-git]]
1235Exporting a git repository via the git protocol
1236~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1237
1238This is the preferred method.
1239
1240For now, we refer you to the gitlink:git-daemon[1] man page for
1241instructions. (See especially the examples section.)
1242
1243[[pushing-changes-to-a-public-repository]]
1244Pushing changes to a public repository
1245~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1246
1247Note that the two techniques outline above (exporting via
1248<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1249maintainers to fetch your latest changes, but they do not allow write
1250access, which you will need to update the public repository with the
1251latest changes created in your private repository.
1252
1253The simplest way to do this is using gitlink:git-push[1] and ssh; to
1254update the remote branch named "master" with the latest state of your
1255branch named "master", run
1256
1257-------------------------------------------------
1258$ git push ssh://yourserver.com/~you/proj.git master:master
1259-------------------------------------------------
1260
1261or just
1262
1263-------------------------------------------------
1264$ git push ssh://yourserver.com/~you/proj.git master
1265-------------------------------------------------
1266
1267As with git-fetch, git-push will complain if this does not result in
1268a <<fast-forwards,fast forward>>. Normally this is a sign of
1269something wrong. However, if you are sure you know what you're
1270doing, you may force git-push to perform the update anyway by
1271proceeding the branch name by a plus sign:
1272
1273-------------------------------------------------
1274$ git push ssh://yourserver.com/~you/proj.git +master
1275-------------------------------------------------
1276
1277As with git-fetch, you may also set up configuration options to
1278save typing; so, for example, after
1279
1280-------------------------------------------------
1281$ cat >.git/config <<EOF
1282[remote "public-repo"]
1283 url = ssh://yourserver.com/~you/proj.git
1284EOF
1285-------------------------------------------------
1286
1287you should be able to perform the above push with just
1288
1289-------------------------------------------------
1290$ git push public-repo master
1291-------------------------------------------------
1292
1293See the explanations of the remote.<name>.url, branch.<name>.remote,
1294and remote.<name>.push options in gitlink:git-repo-config[1] for
1295details.
1296
1297Setting up a shared repository
1298~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1299
1300Another way to collaborate is by using a model similar to that
1301commonly used in CVS, where several developers with special rights
1302all push to and pull from a single shared repository. See
1303link:cvs-migration.txt[git for CVS users] for instructions on how to
1304set this up.
1305
1306Fixing mistakes
1307---------------
1308
1309If you've messed up the working tree, but haven't yet committed your
1310mistake, you can return the entire working tree to the last committed
1311state with
1312
1313-------------------------------------------------
1314$ git reset --hard HEAD
1315-------------------------------------------------
1316
1317If you make a commit that you later wish you hadn't, there are two
1318fundamentally different ways to fix the problem:
1319
1320 1. You can create a new commit that undoes whatever was done
1321 by the previous commit. This is the correct thing if your
1322 mistake has already been made public.
1323
1324 2. You can go back and modify the old commit. You should
1325 never do this if you have already made the history public;
1326 git does not normally expect the "history" of a project to
1327 change, and cannot correctly perform repeated merges from
1328 a branch that has had its history changed.
1329
1330Fixing a mistake with a new commit
1331~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1332
1333Creating a new commit that reverts an earlier change is very easy;
1334just pass the gitlink:git-revert[1] command a reference to the bad
1335commit; for example, to revert the most recent commit:
1336
1337-------------------------------------------------
1338$ git revert HEAD
1339-------------------------------------------------
1340
1341This will create a new commit which undoes the change in HEAD. You
1342will be given a chance to edit the commit message for the new commit.
1343
1344You can also revert an earlier change, for example, the next-to-last:
1345
1346-------------------------------------------------
1347$ git revert HEAD^
1348-------------------------------------------------
1349
1350In this case git will attempt to undo the old change while leaving
1351intact any changes made since then. If more recent changes overlap
1352with the changes to be reverted, then you will be asked to fix
1353conflicts manually, just as in the case of <<resolving-a-merge,
1354resolving a merge>>.
1355
1356Fixing a mistake by editing history
1357~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1358
1359If the problematic commit is the most recent commit, and you have not
1360yet made that commit public, then you may just
1361<<undoing-a-merge,destroy it using git-reset>>.
1362
1363Alternatively, you
1364can edit the working directory and update the index to fix your
1365mistake, just as if you were going to <<how-to-make-a-commit,create a
1366new commit>>, then run
1367
1368-------------------------------------------------
1369$ git commit --amend
1370-------------------------------------------------
1371
1372which will replace the old commit by a new commit incorporating your
1373changes, giving you a chance to edit the old commit message first.
1374
1375Again, you should never do this to a commit that may already have
1376been merged into another branch; use gitlink:git-revert[1] instead in
1377that case.
1378
1379It is also possible to edit commits further back in the history, but
1380this is an advanced topic to be left for
1381<<cleaning-up-history,another chapter>>.
1382
1383Checking out an old version of a file
1384~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1385
1386In the process of undoing a previous bad change, you may find it
1387useful to check out an older version of a particular file using
1388gitlink:git-checkout[1]. We've used git checkout before to switch
1389branches, but it has quite different behavior if it is given a path
1390name: the command
1391
1392-------------------------------------------------
1393$ git checkout HEAD^ path/to/file
1394-------------------------------------------------
1395
1396replaces path/to/file by the contents it had in the commit HEAD^, and
1397also updates the index to match. It does not change branches.
1398
1399If you just want to look at an old version of the file, without
1400modifying the working directory, you can do that with
1401gitlink:git-show[1]:
1402
1403-------------------------------------------------
1404$ git show HEAD^ path/to/file
1405-------------------------------------------------
1406
1407which will display the given version of the file.
1408
1409Working with other version control systems
1410==========================================
1411
1412TODO: CVS, Subversion, ?
1413
1414[[cleaning-up-history]]
1415Cleaning up history: rebasing, cherry-picking, and patch series
1416===============================================================
1417
1418TODO: rebase, cherry-pick, pointers to other tools (like stgit)
1419
1420Git internals
1421=============
1422
1423Architectural overview
1424----------------------
1425
1426TODO: Sources, README, core-tutorial, tutorial-2.txt, technical/
1427
1428Glossary of git terms
1429=====================
1430
1431include::glossary.txt[]
1432
1433Todo list for this manual
1434=========================
1435
1436Scan Documentation/ for other stuff left out; in particular:
1437 howto's
1438 README
1439 some of technical/?
1440 hooks
1441 etc.
1442
1443Scan email archives for other stuff left out
1444
1445Scan man pages to see if any assume more background than this manual
1446provides.
1447
1448Mention of gitweb.
1449
1450Update git fetch discussion to use "git remote" setup. That will
1451make things simpler. Maybe wait till git remote is done.
1452
1453Can also simplify beginning by suggesting disconnected head instead
1454of temporary branch creation.
1455
1456Explain how to refer to file stages in the "how to resolve a merge"
1457section: diff -1, -2, -3; :1:/path notation.
1458
1459Include cross-references to the glossary, where appropriate.
1460