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