GIT 1.5.3-rc4
[git/git.git] / Documentation / user-manual.txt
CommitLineData
71f4b183
CW
1Git User's Manual (for version 1.5.1 or newer)
2______________________________________________
d19fbc3c 3
99eaefdd
BF
4
5Git is a fast distributed revision control system.
6
d19fbc3c 7This manual is designed to be readable by someone with basic unix
79c96c57 8command-line skills, but no previous knowledge of git.
d19fbc3c 9
2624d9a5
BF
10<<repositories-and-branches>> and <<exploring-git-history>> explain how
11to fetch and study a project using git--read these chapters to learn how
12to build and test a particular version of a software project, search for
13regressions, and so on.
ef89f701 14
2624d9a5
BF
15People needing to do actual development will also want to read
16<<Developing-with-git>> and <<sharing-development>>.
6bd9b682
BF
17
18Further chapters cover more specialized topics.
19
d19fbc3c
BF
20Comprehensive reference documentation is available through the man
21pages. For a command such as "git clone", just use
22
23------------------------------------------------
24$ man git-clone
25------------------------------------------------
26
2624d9a5
BF
27See also <<git-quick-start>> for a brief overview of git commands,
28without any explanation.
b181d57f 29
99f171bb 30Finally, see <<todo>> for ways that you can help make this manual more
2624d9a5 31complete.
b181d57f 32
b181d57f 33
e34caace 34[[repositories-and-branches]]
d19fbc3c
BF
35Repositories and Branches
36=========================
37
e34caace 38[[how-to-get-a-git-repository]]
d19fbc3c
BF
39How to get a git repository
40---------------------------
41
42It will be useful to have a git repository to experiment with as you
43read this manual.
44
45The best way to get one is by using the gitlink:git-clone[1] command
46to download a copy of an existing repository for a project that you
47are interested in. If you don't already have a project in mind, here
48are some interesting examples:
49
50------------------------------------------------
51 # git itself (approx. 10MB download):
52$ git clone git://git.kernel.org/pub/scm/git/git.git
53 # the linux kernel (approx. 150MB download):
54$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
55------------------------------------------------
56
57The initial clone may be time-consuming for a large project, but you
58will only need to clone once.
59
60The clone command creates a new directory named after the project
61("git" or "linux-2.6" in the examples above). After you cd into this
62directory, you will see that it contains a copy of the project files,
63together with a special top-level directory named ".git", which
64contains all the information about the history of the project.
65
d5cd5de4 66In most of the following, examples will be taken from one of the two
d19fbc3c
BF
67repositories above.
68
e34caace 69[[how-to-check-out]]
d19fbc3c
BF
70How to check out a different version of a project
71-------------------------------------------------
72
73Git is best thought of as a tool for storing the history of a
74collection of files. It stores the history as a compressed
75collection of interrelated snapshots (versions) of the project's
76contents.
77
81b6c950
BF
78A single git repository may contain multiple branches. It keeps track
79of them by keeping a list of <<def_head,heads>> which reference the
80latest version on each branch; the gitlink:git-branch[1] command shows
81you the list of branch heads:
d19fbc3c
BF
82
83------------------------------------------------
84$ git branch
85* master
86------------------------------------------------
87
4f752407
BF
88A freshly cloned repository contains a single branch head, by default
89named "master", with the working directory initialized to the state of
90the project referred to by that branch head.
d19fbc3c 91
81b6c950
BF
92Most projects also use <<def_tag,tags>>. Tags, like heads, are
93references into the project's history, and can be listed using the
d19fbc3c
BF
94gitlink:git-tag[1] command:
95
96------------------------------------------------
97$ git tag -l
98v2.6.11
99v2.6.11-tree
100v2.6.12
101v2.6.12-rc2
102v2.6.12-rc3
103v2.6.12-rc4
104v2.6.12-rc5
105v2.6.12-rc6
106v2.6.13
107...
108------------------------------------------------
109
fe4b3e59 110Tags are expected to always point at the same version of a project,
81b6c950 111while heads are expected to advance as development progresses.
fe4b3e59 112
81b6c950 113Create a new branch head pointing to one of these versions and check it
d19fbc3c
BF
114out using gitlink:git-checkout[1]:
115
116------------------------------------------------
117$ git checkout -b new v2.6.13
118------------------------------------------------
119
120The working directory then reflects the contents that the project had
121when it was tagged v2.6.13, and gitlink:git-branch[1] shows two
122branches, with an asterisk marking the currently checked-out branch:
123
124------------------------------------------------
125$ git branch
126 master
127* new
128------------------------------------------------
129
130If you decide that you'd rather see version 2.6.17, you can modify
131the current branch to point at v2.6.17 instead, with
132
133------------------------------------------------
134$ git reset --hard v2.6.17
135------------------------------------------------
136
81b6c950 137Note that if the current branch head was your only reference to a
d19fbc3c 138particular point in history, then resetting that branch may leave you
81b6c950
BF
139with no way to find the history it used to point to; so use this command
140carefully.
d19fbc3c 141
e34caace 142[[understanding-commits]]
d19fbc3c
BF
143Understanding History: Commits
144------------------------------
145
146Every change in the history of a project is represented by a commit.
147The gitlink:git-show[1] command shows the most recent commit on the
148current branch:
149
150------------------------------------------------
151$ git show
152commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
153Author: Jamal Hadi Salim <hadi@cyberus.ca>
154Date: Sat Dec 2 22:22:25 2006 -0800
155
156 [XFRM]: Fix aevent structuring to be more complete.
a6080a0a 157
d19fbc3c
BF
158 aevents can not uniquely identify an SA. We break the ABI with this
159 patch, but consensus is that since it is not yet utilized by any
160 (known) application then it is fine (better do it now than later).
a6080a0a 161
d19fbc3c
BF
162 Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
163 Signed-off-by: David S. Miller <davem@davemloft.net>
164
165diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
166index 8be626f..d7aac9d 100644
167--- a/Documentation/networking/xfrm_sync.txt
168+++ b/Documentation/networking/xfrm_sync.txt
169@@ -47,10 +47,13 @@ aevent_id structure looks like:
a6080a0a 170
d19fbc3c
BF
171 struct xfrm_aevent_id {
172 struct xfrm_usersa_id sa_id;
173+ xfrm_address_t saddr;
174 __u32 flags;
175+ __u32 reqid;
176 };
177...
178------------------------------------------------
179
180As you can see, a commit shows who made the latest change, what they
181did, and why.
182
35121930
BF
183Every commit has a 40-hexdigit id, sometimes called the "object name" or the
184"SHA1 id", shown on the first line of the "git show" output. You can usually
185refer to a commit by a shorter name, such as a tag or a branch name, but this
186longer name can also be useful. Most importantly, it is a globally unique
187name for this commit: so if you tell somebody else the object name (for
188example in email), then you are guaranteed that name will refer to the same
189commit in their repository that it does in yours (assuming their repository
190has that commit at all). Since the object name is computed as a hash over the
191contents of the commit, you are guaranteed that the commit can never change
192without its name also changing.
193
194In fact, in <<git-internals>> we shall see that everything stored in git
195history, including file data and directory contents, is stored in an object
196with a name that is a hash of its contents.
d19fbc3c 197
e34caace 198[[understanding-reachability]]
d19fbc3c
BF
199Understanding history: commits, parents, and reachability
200~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
202Every commit (except the very first commit in a project) also has a
203parent commit which shows what happened before this commit.
204Following the chain of parents will eventually take you back to the
205beginning of the project.
206
207However, the commits do not form a simple list; git allows lines of
208development to diverge and then reconverge, and the point where two
209lines of development reconverge is called a "merge". The commit
210representing a merge can therefore have more than one parent, with
211each parent representing the most recent commit on one of the lines
212of development leading to that point.
213
214The best way to see how this works is using the gitlink:gitk[1]
215command; running gitk now on a git repository and looking for merge
216commits will help understand how the git organizes history.
217
218In the following, we say that commit X is "reachable" from commit Y
219if commit X is an ancestor of commit Y. Equivalently, you could say
220that Y is a descendent of X, or that there is a chain of parents
221leading from commit Y to commit X.
222
e34caace 223[[history-diagrams]]
3dff5379
PR
224Understanding history: History diagrams
225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c
BF
226
227We will sometimes represent git history using diagrams like the one
228below. Commits are shown as "o", and the links between them with
229lines drawn with - / and \. Time goes left to right:
230
1dc71a91
BF
231
232................................................
d19fbc3c
BF
233 o--o--o <-- Branch A
234 /
235 o--o--o <-- master
236 \
237 o--o--o <-- Branch B
1dc71a91 238................................................
d19fbc3c
BF
239
240If we need to talk about a particular commit, the character "o" may
241be replaced with another letter or number.
242
e34caace 243[[what-is-a-branch]]
d19fbc3c
BF
244Understanding history: What is a branch?
245~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246
81b6c950
BF
247When we need to be precise, we will use the word "branch" to mean a line
248of development, and "branch head" (or just "head") to mean a reference
249to the most recent commit on a branch. In the example above, the branch
250head named "A" is a pointer to one particular commit, but we refer to
251the line of three commits leading up to that point as all being part of
d19fbc3c
BF
252"branch A".
253
81b6c950
BF
254However, when no confusion will result, we often just use the term
255"branch" both for branches and for branch heads.
d19fbc3c 256
e34caace 257[[manipulating-branches]]
d19fbc3c
BF
258Manipulating branches
259---------------------
260
261Creating, deleting, and modifying branches is quick and easy; here's
262a summary of the commands:
263
264git branch::
265 list all branches
266git branch <branch>::
267 create a new branch named <branch>, referencing the same
268 point in history as the current branch
269git branch <branch> <start-point>::
270 create a new branch named <branch>, referencing
271 <start-point>, which may be specified any way you like,
272 including using a branch name or a tag name
273git branch -d <branch>::
274 delete the branch <branch>; if the branch you are deleting
c64415e2
BF
275 points to a commit which is not reachable from the current
276 branch, this command will fail with a warning.
d19fbc3c
BF
277git branch -D <branch>::
278 even if the branch points to a commit not reachable
279 from the current branch, you may know that that commit
280 is still reachable from some other branch or tag. In that
281 case it is safe to use this command to force git to delete
282 the branch.
283git checkout <branch>::
284 make the current branch <branch>, updating the working
285 directory to reflect the version referenced by <branch>
286git checkout -b <new> <start-point>::
287 create a new branch <new> referencing <start-point>, and
288 check it out.
289
72a76c95
BF
290The special symbol "HEAD" can always be used to refer to the current
291branch. In fact, git uses a file named "HEAD" in the .git directory to
292remember which branch is current:
293
294------------------------------------------------
295$ cat .git/HEAD
296ref: refs/heads/master
297------------------------------------------------
298
25d9f3fa 299[[detached-head]]
72a76c95
BF
300Examining an old version without creating a new branch
301------------------------------------------------------
302
303The git-checkout command normally expects a branch head, but will also
304accept an arbitrary commit; for example, you can check out the commit
305referenced by a tag:
306
307------------------------------------------------
308$ git checkout v2.6.17
309Note: moving to "v2.6.17" which isn't a local branch
310If you want to create a new branch from this checkout, you may do so
311(now or later) by using -b with the checkout command again. Example:
312 git checkout -b <new_branch_name>
313HEAD is now at 427abfa... Linux v2.6.17
314------------------------------------------------
315
316The HEAD then refers to the SHA1 of the commit instead of to a branch,
317and git branch shows that you are no longer on a branch:
318
319------------------------------------------------
320$ cat .git/HEAD
321427abfa28afedffadfca9dd8b067eb6d36bac53f
953f3d6f 322$ git branch
72a76c95
BF
323* (no branch)
324 master
325------------------------------------------------
326
327In this case we say that the HEAD is "detached".
328
953f3d6f
BF
329This is an easy way to check out a particular version without having to
330make up a name for the new branch. You can still create a new branch
331(or tag) for this version later if you decide to.
d19fbc3c 332
e34caace 333[[examining-remote-branches]]
d19fbc3c
BF
334Examining branches from a remote repository
335-------------------------------------------
336
337The "master" branch that was created at the time you cloned is a copy
338of the HEAD in the repository that you cloned from. That repository
339may also have had other branches, though, and your local repository
340keeps branches which track each of those remote branches, which you
341can view using the "-r" option to gitlink:git-branch[1]:
342
343------------------------------------------------
344$ git branch -r
345 origin/HEAD
346 origin/html
347 origin/maint
348 origin/man
349 origin/master
350 origin/next
351 origin/pu
352 origin/todo
353------------------------------------------------
354
355You cannot check out these remote-tracking branches, but you can
356examine them on a branch of your own, just as you would a tag:
357
358------------------------------------------------
359$ git checkout -b my-todo-copy origin/todo
360------------------------------------------------
361
362Note that the name "origin" is just the name that git uses by default
363to refer to the repository that you cloned from.
364
365[[how-git-stores-references]]
f60b9642
BF
366Naming branches, tags, and other references
367-------------------------------------------
d19fbc3c
BF
368
369Branches, remote-tracking branches, and tags are all references to
f60b9642
BF
370commits. All references are named with a slash-separated path name
371starting with "refs"; the names we've been using so far are actually
372shorthand:
d19fbc3c 373
f60b9642
BF
374 - The branch "test" is short for "refs/heads/test".
375 - The tag "v2.6.18" is short for "refs/tags/v2.6.18".
376 - "origin/master" is short for "refs/remotes/origin/master".
d19fbc3c 377
f60b9642
BF
378The full name is occasionally useful if, for example, there ever
379exists a tag and a branch with the same name.
d19fbc3c 380
c64415e2
BF
381As another useful shortcut, the "HEAD" of a repository can be referred
382to just using the name of that repository. So, for example, "origin"
383is usually a shortcut for the HEAD branch in the repository "origin".
d19fbc3c
BF
384
385For the complete list of paths which git checks for references, and
f60b9642
BF
386the order it uses to decide which to choose when there are multiple
387references with the same shorthand name, see the "SPECIFYING
388REVISIONS" section of gitlink:git-rev-parse[1].
d19fbc3c
BF
389
390[[Updating-a-repository-with-git-fetch]]
391Updating a repository with git fetch
392------------------------------------
393
394Eventually the developer cloned from will do additional work in her
395repository, creating new commits and advancing the branches to point
396at the new commits.
397
398The command "git fetch", with no arguments, will update all of the
399remote-tracking branches to the latest version found in her
400repository. It will not touch any of your own branches--not even the
401"master" branch that was created for you on clone.
402
e34caace 403[[fetching-branches]]
d5cd5de4
BF
404Fetching branches from other repositories
405-----------------------------------------
406
407You can also track branches from repositories other than the one you
408cloned from, using gitlink:git-remote[1]:
409
410-------------------------------------------------
411$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git
04483524 412$ git fetch linux-nfs
d5cd5de4
BF
413* refs/remotes/linux-nfs/master: storing branch 'master' ...
414 commit: bf81b46
415-------------------------------------------------
416
417New remote-tracking branches will be stored under the shorthand name
418that you gave "git remote add", in this case linux-nfs:
419
420-------------------------------------------------
421$ git branch -r
422linux-nfs/master
423origin/master
424-------------------------------------------------
425
426If you run "git fetch <remote>" later, the tracking branches for the
427named <remote> will be updated.
428
429If you examine the file .git/config, you will see that git has added
430a new stanza:
431
432-------------------------------------------------
433$ cat .git/config
434...
435[remote "linux-nfs"]
923642fe
BF
436 url = git://linux-nfs.org/pub/nfs-2.6.git
437 fetch = +refs/heads/*:refs/remotes/linux-nfs/*
d5cd5de4
BF
438...
439-------------------------------------------------
440
fc90c536
BF
441This is what causes git to track the remote's branches; you may modify
442or delete these configuration options by editing .git/config with a
443text editor. (See the "CONFIGURATION FILE" section of
444gitlink:git-config[1] for details.)
d5cd5de4 445
e34caace 446[[exploring-git-history]]
d19fbc3c
BF
447Exploring git history
448=====================
449
450Git is best thought of as a tool for storing the history of a
451collection of files. It does this by storing compressed snapshots of
1130845b 452the contents of a file hierarchy, together with "commits" which show
d19fbc3c
BF
453the relationships between these snapshots.
454
455Git provides extremely flexible and fast tools for exploring the
456history of a project.
457
aacd404e 458We start with one specialized tool that is useful for finding the
d19fbc3c
BF
459commit that introduced a bug into a project.
460
e34caace 461[[using-bisect]]
d19fbc3c
BF
462How to use bisect to find a regression
463--------------------------------------
464
465Suppose version 2.6.18 of your project worked, but the version at
466"master" crashes. Sometimes the best way to find the cause of such a
467regression is to perform a brute-force search through the project's
468history to find the particular commit that caused the problem. The
469gitlink:git-bisect[1] command can help you do this:
470
471-------------------------------------------------
472$ git bisect start
473$ git bisect good v2.6.18
474$ git bisect bad master
475Bisecting: 3537 revisions left to test after this
476[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
477-------------------------------------------------
478
479If you run "git branch" at this point, you'll see that git has
480temporarily moved you to a new branch named "bisect". This branch
481points to a commit (with commit id 65934...) that is reachable from
482v2.6.19 but not from v2.6.18. Compile and test it, and see whether
483it crashes. Assume it does crash. Then:
484
485-------------------------------------------------
486$ git bisect bad
487Bisecting: 1769 revisions left to test after this
488[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
489-------------------------------------------------
490
491checks out an older version. Continue like this, telling git at each
492stage whether the version it gives you is good or bad, and notice
493that the number of revisions left to test is cut approximately in
494half each time.
495
496After about 13 tests (in this case), it will output the commit id of
497the guilty commit. You can then examine the commit with
498gitlink:git-show[1], find out who wrote it, and mail them your bug
499report with the commit id. Finally, run
500
501-------------------------------------------------
502$ git bisect reset
503-------------------------------------------------
504
505to return you to the branch you were on before and delete the
506temporary "bisect" branch.
507
508Note that the version which git-bisect checks out for you at each
509point is just a suggestion, and you're free to try a different
510version if you think it would be a good idea. For example,
511occasionally you may land on a commit that broke something unrelated;
512run
513
514-------------------------------------------------
04483524 515$ git bisect visualize
d19fbc3c
BF
516-------------------------------------------------
517
518which will run gitk and label the commit it chose with a marker that
519says "bisect". Chose a safe-looking commit nearby, note its commit
520id, and check it out with:
521
522-------------------------------------------------
523$ git reset --hard fb47ddb2db...
524-------------------------------------------------
525
526then test, run "bisect good" or "bisect bad" as appropriate, and
527continue.
528
e34caace 529[[naming-commits]]
d19fbc3c
BF
530Naming commits
531--------------
532
533We have seen several ways of naming commits already:
534
d55ae921 535 - 40-hexdigit object name
d19fbc3c
BF
536 - branch name: refers to the commit at the head of the given
537 branch
538 - tag name: refers to the commit pointed to by the given tag
539 (we've seen branches and tags are special cases of
540 <<how-git-stores-references,references>>).
541 - HEAD: refers to the head of the current branch
542
eb6ae7f4 543There are many more; see the "SPECIFYING REVISIONS" section of the
aec053bb 544gitlink:git-rev-parse[1] man page for the complete list of ways to
d19fbc3c
BF
545name revisions. Some examples:
546
547-------------------------------------------------
d55ae921 548$ git show fb47ddb2 # the first few characters of the object name
d19fbc3c
BF
549 # are usually enough to specify it uniquely
550$ git show HEAD^ # the parent of the HEAD commit
551$ git show HEAD^^ # the grandparent
552$ git show HEAD~4 # the great-great-grandparent
553-------------------------------------------------
554
555Recall that merge commits may have more than one parent; by default,
556^ and ~ follow the first parent listed in the commit, but you can
557also choose:
558
559-------------------------------------------------
560$ git show HEAD^1 # show the first parent of HEAD
561$ git show HEAD^2 # show the second parent of HEAD
562-------------------------------------------------
563
564In addition to HEAD, there are several other special names for
565commits:
566
567Merges (to be discussed later), as well as operations such as
568git-reset, which change the currently checked-out commit, generally
569set ORIG_HEAD to the value HEAD had before the current operation.
570
571The git-fetch operation always stores the head of the last fetched
572branch in FETCH_HEAD. For example, if you run git fetch without
573specifying a local branch as the target of the operation
574
575-------------------------------------------------
576$ git fetch git://example.com/proj.git theirbranch
577-------------------------------------------------
578
579the fetched commits will still be available from FETCH_HEAD.
580
581When we discuss merges we'll also see the special name MERGE_HEAD,
582which refers to the other branch that we're merging in to the current
583branch.
584
aec053bb 585The gitlink:git-rev-parse[1] command is a low-level command that is
d55ae921
BF
586occasionally useful for translating some name for a commit to the object
587name for that commit:
aec053bb
BF
588
589-------------------------------------------------
590$ git rev-parse origin
591e05db0fd4f31dde7005f075a84f96b360d05984b
592-------------------------------------------------
593
e34caace 594[[creating-tags]]
d19fbc3c
BF
595Creating tags
596-------------
597
598We can also create a tag to refer to a particular commit; after
599running
600
601-------------------------------------------------
04483524 602$ git tag stable-1 1b2e1d63ff
d19fbc3c
BF
603-------------------------------------------------
604
605You can use stable-1 to refer to the commit 1b2e1d63ff.
606
c64415e2
BF
607This creates a "lightweight" tag. If you would also like to include a
608comment with the tag, and possibly sign it cryptographically, then you
609should create a tag object instead; see the gitlink:git-tag[1] man page
610for details.
d19fbc3c 611
e34caace 612[[browsing-revisions]]
d19fbc3c
BF
613Browsing revisions
614------------------
615
616The gitlink:git-log[1] command can show lists of commits. On its
617own, it shows all commits reachable from the parent commit; but you
618can also make more specific requests:
619
620-------------------------------------------------
621$ git log v2.5.. # commits since (not reachable from) v2.5
622$ git log test..master # commits reachable from master but not test
623$ git log master..test # ...reachable from test but not master
624$ git log master...test # ...reachable from either test or master,
625 # but not both
626$ git log --since="2 weeks ago" # commits from the last 2 weeks
627$ git log Makefile # commits which modify Makefile
628$ git log fs/ # ... which modify any file under fs/
629$ git log -S'foo()' # commits which add or remove any file data
630 # matching the string 'foo()'
631-------------------------------------------------
632
633And of course you can combine all of these; the following finds
634commits since v2.5 which touch the Makefile or any file under fs:
635
636-------------------------------------------------
637$ git log v2.5.. Makefile fs/
638-------------------------------------------------
639
640You can also ask git log to show patches:
641
642-------------------------------------------------
643$ git log -p
644-------------------------------------------------
645
646See the "--pretty" option in the gitlink:git-log[1] man page for more
647display options.
648
649Note that git log starts with the most recent commit and works
650backwards through the parents; however, since git history can contain
3dff5379 651multiple independent lines of development, the particular order that
d19fbc3c
BF
652commits are listed in may be somewhat arbitrary.
653
e34caace 654[[generating-diffs]]
d19fbc3c
BF
655Generating diffs
656----------------
657
658You can generate diffs between any two versions using
659gitlink:git-diff[1]:
660
661-------------------------------------------------
662$ git diff master..test
663-------------------------------------------------
664
665Sometimes what you want instead is a set of patches:
666
667-------------------------------------------------
668$ git format-patch master..test
669-------------------------------------------------
670
671will generate a file with a patch for each commit reachable from test
672but not from master. Note that if master also has commits which are
673not reachable from test, then the combined result of these patches
674will not be the same as the diff produced by the git-diff example.
675
e34caace 676[[viewing-old-file-versions]]
d19fbc3c
BF
677Viewing old file versions
678-------------------------
679
680You can always view an old version of a file by just checking out the
681correct revision first. But sometimes it is more convenient to be
682able to view an old version of a single file without checking
683anything out; this command does that:
684
685-------------------------------------------------
686$ git show v2.5:fs/locks.c
687-------------------------------------------------
688
689Before the colon may be anything that names a commit, and after it
690may be any path to a file tracked by git.
691
e34caace 692[[history-examples]]
aec053bb
BF
693Examples
694--------
695
46acd3fa
BF
696[[counting-commits-on-a-branch]]
697Counting the number of commits on a branch
698~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
699
700Suppose you want to know how many commits you've made on "mybranch"
701since it diverged from "origin":
702
703-------------------------------------------------
704$ git log --pretty=oneline origin..mybranch | wc -l
705-------------------------------------------------
706
707Alternatively, you may often see this sort of thing done with the
708lower-level command gitlink:git-rev-list[1], which just lists the SHA1's
709of all the given commits:
710
711-------------------------------------------------
712$ git rev-list origin..mybranch | wc -l
713-------------------------------------------------
714
e34caace 715[[checking-for-equal-branches]]
aec053bb 716Check whether two branches point at the same history
2f99710c 717~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
aec053bb
BF
718
719Suppose you want to check whether two branches point at the same point
720in history.
721
722-------------------------------------------------
723$ git diff origin..master
724-------------------------------------------------
725
69f7ad73
BF
726will tell you whether the contents of the project are the same at the
727two branches; in theory, however, it's possible that the same project
728contents could have been arrived at by two different historical
d55ae921 729routes. You could compare the object names:
aec053bb
BF
730
731-------------------------------------------------
732$ git rev-list origin
733e05db0fd4f31dde7005f075a84f96b360d05984b
734$ git rev-list master
735e05db0fd4f31dde7005f075a84f96b360d05984b
736-------------------------------------------------
737
69f7ad73
BF
738Or you could recall that the ... operator selects all commits
739contained reachable from either one reference or the other but not
740both: so
aec053bb
BF
741
742-------------------------------------------------
743$ git log origin...master
744-------------------------------------------------
745
746will return no commits when the two branches are equal.
747
e34caace 748[[finding-tagged-descendants]]
b181d57f
BF
749Find first tagged version including a given fix
750~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
aec053bb 751
69f7ad73
BF
752Suppose you know that the commit e05db0fd fixed a certain problem.
753You'd like to find the earliest tagged release that contains that
754fix.
755
756Of course, there may be more than one answer--if the history branched
757after commit e05db0fd, then there could be multiple "earliest" tagged
758releases.
759
760You could just visually inspect the commits since e05db0fd:
761
762-------------------------------------------------
763$ gitk e05db0fd..
764-------------------------------------------------
765
b181d57f
BF
766Or you can use gitlink:git-name-rev[1], which will give the commit a
767name based on any tag it finds pointing to one of the commit's
768descendants:
769
770-------------------------------------------------
04483524 771$ git name-rev --tags e05db0fd
b181d57f
BF
772e05db0fd tags/v1.5.0-rc1^0~23
773-------------------------------------------------
774
775The gitlink:git-describe[1] command does the opposite, naming the
776revision using a tag on which the given commit is based:
777
778-------------------------------------------------
779$ git describe e05db0fd
04483524 780v1.5.0-rc0-260-ge05db0f
b181d57f
BF
781-------------------------------------------------
782
783but that may sometimes help you guess which tags might come after the
784given commit.
785
786If you just want to verify whether a given tagged version contains a
787given commit, you could use gitlink:git-merge-base[1]:
788
789-------------------------------------------------
790$ git merge-base e05db0fd v1.5.0-rc1
791e05db0fd4f31dde7005f075a84f96b360d05984b
792-------------------------------------------------
793
794The merge-base command finds a common ancestor of the given commits,
795and always returns one or the other in the case where one is a
796descendant of the other; so the above output shows that e05db0fd
797actually is an ancestor of v1.5.0-rc1.
798
799Alternatively, note that
800
801-------------------------------------------------
4a7979ca 802$ git log v1.5.0-rc1..e05db0fd
b181d57f
BF
803-------------------------------------------------
804
4a7979ca 805will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
b181d57f 806because it outputs only commits that are not reachable from v1.5.0-rc1.
aec053bb 807
4a7979ca
BF
808As yet another alternative, the gitlink:git-show-branch[1] command lists
809the commits reachable from its arguments with a display on the left-hand
810side that indicates which arguments that commit is reachable from. So,
811you can run something like
812
813-------------------------------------------------
814$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
815! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
816available
817 ! [v1.5.0-rc0] GIT v1.5.0 preview
818 ! [v1.5.0-rc1] GIT v1.5.0-rc1
819 ! [v1.5.0-rc2] GIT v1.5.0-rc2
820...
821-------------------------------------------------
822
823then search for a line that looks like
824
825-------------------------------------------------
826+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
827available
828-------------------------------------------------
829
830Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and
831from v1.5.0-rc2, but not from v1.5.0-rc0.
832
629d9f78
BF
833[[showing-commits-unique-to-a-branch]]
834Showing commits unique to a given branch
835~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4a7979ca 836
629d9f78
BF
837Suppose you would like to see all the commits reachable from the branch
838head named "master" but not from any other head in your repository.
d19fbc3c 839
629d9f78
BF
840We can list all the heads in this repository with
841gitlink:git-show-ref[1]:
d19fbc3c 842
629d9f78
BF
843-------------------------------------------------
844$ git show-ref --heads
845bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
846db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
847a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
84824dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
8491e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
850-------------------------------------------------
d19fbc3c 851
629d9f78
BF
852We can get just the branch-head names, and remove "master", with
853the help of the standard utilities cut and grep:
854
855-------------------------------------------------
856$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
857refs/heads/core-tutorial
858refs/heads/maint
859refs/heads/tutorial-2
860refs/heads/tutorial-fixes
861-------------------------------------------------
862
863And then we can ask to see all the commits reachable from master
864but not from these other heads:
865
866-------------------------------------------------
867$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
868 grep -v '^refs/heads/master' )
869-------------------------------------------------
870
871Obviously, endless variations are possible; for example, to see all
872commits reachable from some head but not from any tag in the repository:
873
874-------------------------------------------------
c78974f7 875$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
629d9f78
BF
876-------------------------------------------------
877
878(See gitlink:git-rev-parse[1] for explanations of commit-selecting
879syntax such as `--not`.)
880
82c8bf28
BF
881[[making-a-release]]
882Creating a changelog and tarball for a software release
883~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
884
885The gitlink:git-archive[1] command can create a tar or zip archive from
886any version of a project; for example:
887
888-------------------------------------------------
889$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
890-------------------------------------------------
891
892will use HEAD to produce a tar archive in which each filename is
ccd71866 893preceded by "project/".
82c8bf28
BF
894
895If you're releasing a new version of a software project, you may want
896to simultaneously make a changelog to include in the release
897announcement.
898
899Linus Torvalds, for example, makes new kernel releases by tagging them,
900then running:
901
902-------------------------------------------------
903$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
904-------------------------------------------------
905
906where release-script is a shell script that looks like:
907
908-------------------------------------------------
909#!/bin/sh
910stable="$1"
911last="$2"
912new="$3"
913echo "# git tag v$new"
914echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
915echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
916echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
917echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
918echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
919-------------------------------------------------
920
921and then he just cut-and-pastes the output commands after verifying that
922they look OK.
4a7979ca 923
8ceca74a 924[[Finding-comments-with-given-content]]
187b0d80
BF
925Finding commits referencing a file with given content
926-----------------------------------------------------
927
928Somebody hands you a copy of a file, and asks which commits modified a
929file such that it contained the given content either before or after the
930commit. You can find out with this:
931
932-------------------------------------------------
933$ git log --raw -r --abbrev=40 --pretty=oneline -- filename |
934 grep -B 1 `git hash-object filename`
935-------------------------------------------------
936
937Figuring out why this works is left as an exercise to the (advanced)
938student. The gitlink:git-log[1], gitlink:git-diff-tree[1], and
939gitlink:git-hash-object[1] man pages may prove helpful.
940
e34caace 941[[Developing-with-git]]
d19fbc3c
BF
942Developing with git
943===================
944
e34caace 945[[telling-git-your-name]]
d19fbc3c
BF
946Telling git your name
947---------------------
948
949Before creating any commits, you should introduce yourself to git. The
58c19d1f
BF
950easiest way to do so is to make sure the following lines appear in a
951file named .gitconfig in your home directory:
d19fbc3c
BF
952
953------------------------------------------------
d19fbc3c
BF
954[user]
955 name = Your Name Comes Here
956 email = you@yourdomain.example.com
d19fbc3c
BF
957------------------------------------------------
958
fc90c536
BF
959(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for
960details on the configuration file.)
961
d19fbc3c 962
e34caace 963[[creating-a-new-repository]]
d19fbc3c
BF
964Creating a new repository
965-------------------------
966
967Creating a new repository from scratch is very easy:
968
969-------------------------------------------------
970$ mkdir project
971$ cd project
f1d2b477 972$ git init
d19fbc3c
BF
973-------------------------------------------------
974
975If you have some initial content (say, a tarball):
976
977-------------------------------------------------
978$ tar -xzvf project.tar.gz
979$ cd project
f1d2b477 980$ git init
d19fbc3c
BF
981$ git add . # include everything below ./ in the first commit:
982$ git commit
983-------------------------------------------------
984
985[[how-to-make-a-commit]]
ae25c67a 986How to make a commit
d19fbc3c
BF
987--------------------
988
989Creating a new commit takes three steps:
990
991 1. Making some changes to the working directory using your
992 favorite editor.
993 2. Telling git about your changes.
994 3. Creating the commit using the content you told git about
995 in step 2.
996
997In practice, you can interleave and repeat steps 1 and 2 as many
998times as you want: in order to keep track of what you want committed
999at step 3, git maintains a snapshot of the tree's contents in a
1000special staging area called "the index."
1001
01997b4a
BF
1002At the beginning, the content of the index will be identical to
1003that of the HEAD. The command "git diff --cached", which shows
1004the difference between the HEAD and the index, should therefore
1005produce no output at that point.
eb6ae7f4 1006
d19fbc3c
BF
1007Modifying the index is easy:
1008
1009To update the index with the new contents of a modified file, use
1010
1011-------------------------------------------------
1012$ git add path/to/file
1013-------------------------------------------------
1014
1015To add the contents of a new file to the index, use
1016
1017-------------------------------------------------
1018$ git add path/to/file
1019-------------------------------------------------
1020
eb6ae7f4 1021To remove a file from the index and from the working tree,
d19fbc3c
BF
1022
1023-------------------------------------------------
1024$ git rm path/to/file
1025-------------------------------------------------
1026
1027After each step you can verify that
1028
1029-------------------------------------------------
1030$ git diff --cached
1031-------------------------------------------------
1032
1033always shows the difference between the HEAD and the index file--this
1034is what you'd commit if you created the commit now--and that
1035
1036-------------------------------------------------
1037$ git diff
1038-------------------------------------------------
1039
1040shows the difference between the working tree and the index file.
1041
1042Note that "git add" always adds just the current contents of a file
1043to the index; further changes to the same file will be ignored unless
1044you run git-add on the file again.
1045
1046When you're ready, just run
1047
1048-------------------------------------------------
1049$ git commit
1050-------------------------------------------------
1051
1052and git will prompt you for a commit message and then create the new
3dff5379 1053commit. Check to make sure it looks like what you expected with
d19fbc3c
BF
1054
1055-------------------------------------------------
1056$ git show
1057-------------------------------------------------
1058
1059As a special shortcut,
a6080a0a 1060
d19fbc3c
BF
1061-------------------------------------------------
1062$ git commit -a
1063-------------------------------------------------
1064
1065will update the index with any files that you've modified or removed
1066and create a commit, all in one step.
1067
1068A number of commands are useful for keeping track of what you're
1069about to commit:
1070
1071-------------------------------------------------
1072$ git diff --cached # difference between HEAD and the index; what
1130845b 1073 # would be committed if you ran "commit" now.
d19fbc3c
BF
1074$ git diff # difference between the index file and your
1075 # working directory; changes that would not
1076 # be included if you ran "commit" now.
c64415e2
BF
1077$ git diff HEAD # difference between HEAD and working tree; what
1078 # would be committed if you ran "commit -a" now.
d19fbc3c
BF
1079$ git status # a brief per-file summary of the above.
1080-------------------------------------------------
1081
e34caace 1082[[creating-good-commit-messages]]
ae25c67a 1083Creating good commit messages
d19fbc3c
BF
1084-----------------------------
1085
1086Though not required, it's a good idea to begin the commit message
1087with a single short (less than 50 character) line summarizing the
1088change, followed by a blank line and then a more thorough
1089description. Tools that turn commits into email, for example, use
1090the first line on the Subject line and the rest of the commit in the
1091body.
1092
2dc53617
JH
1093[[ignoring-files]]
1094Ignoring files
1095--------------
1096
1097A project will often generate files that you do 'not' want to track with git.
1098This typically includes files generated by a build process or temporary
1099backup files made by your editor. Of course, 'not' tracking files with git
1100is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
1101annoying to have these untracked files lying around; e.g. they make
1102"`git add .`" and "`git commit -a`" practically useless, and they keep
1103showing up in the output of "`git status`", etc.
1104
1105Git therefore provides "exclude patterns" for telling git which files to
1106actively ignore. Exclude patterns are thoroughly explained in the
cedb8d5d
JT
1107gitlink:gitignore[5] manual page, but the heart of the concept is simply
1108a list of files which git should ignore. Entries in the list may contain
1109globs to specify multiple files, or may be prefixed by "`!`" to
1110explicitly include (un-ignore) a previously excluded (ignored) file
1111(i.e. later exclude patterns override earlier ones). The following
1112example should illustrate such patterns:
2dc53617
JH
1113
1114-------------------------------------------------
1115# Lines starting with '#' are considered comments.
1116# Ignore foo.txt.
1117foo.txt
1118# Ignore (generated) html files,
1119*.html
1120# except foo.html which is maintained by hand.
1121!foo.html
1122# Ignore objects and archives.
1123*.[oa]
1124-------------------------------------------------
1125
1126The next question is where to put these exclude patterns so that git can
1127find them. Git looks for exclude patterns in the following files:
1128
1129`.gitignore` files in your working tree:::
1130 You may store multiple `.gitignore` files at various locations in your
1131 working tree. Each `.gitignore` file is applied to the directory where
1132 it's located, including its subdirectories. Furthermore, the
1133 `.gitignore` files can be tracked like any other files in your working
1134 tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
1135 therefore the right place to put exclude patterns that are meant to
1136 be shared between all project participants, such as build output files
1137 (e.g. `\*.o`), etc.
1138`.git/info/exclude` in your repo:::
1139 Exclude patterns in this file are applied to the working tree as a
1140 whole. Since the file is not located in your working tree, it does
1141 not follow push/pull/clone like `.gitignore` can do. This is therefore
1142 the place to put exclude patterns that are local to your copy of the
1143 repo (i.e. 'not' shared between project participants), such as
1144 temporary backup files made by your editor (e.g. `\*~`), etc.
1145The file specified by the `core.excludesfile` config directive:::
1146 By setting the `core.excludesfile` config directive you can tell git
1147 where to find more exclude patterns (see gitlink:git-config[1] for
1148 more information on configuration options). This config directive
1149 can be set in the per-repo `.git/config` file, in which case the
1150 exclude patterns will apply to that repo only. Alternatively, you
1151 can set the directive in the global `~/.gitconfig` file to apply
1152 the exclude pattern to all your git repos. As with the above
1153 `.git/info/exclude` (and, indeed, with git config directives in
1154 general), this directive does not follow push/pull/clone, but remain
1155 local to your repo(s).
1156
1157[NOTE]
1158In addition to the above alternatives, there are git commands that can take
1159exclude patterns directly on the command line. See gitlink:git-ls-files[1]
1160for an example of this.
1161
e34caace 1162[[how-to-merge]]
ae25c67a 1163How to merge
d19fbc3c
BF
1164------------
1165
1166You can rejoin two diverging branches of development using
1167gitlink:git-merge[1]:
1168
1169-------------------------------------------------
1170$ git merge branchname
1171-------------------------------------------------
1172
1173merges the development in the branch "branchname" into the current
1174branch. If there are conflicts--for example, if the same file is
1175modified in two different ways in the remote branch and the local
1176branch--then you are warned; the output may look something like this:
1177
1178-------------------------------------------------
fabbd8f6
BF
1179$ git merge next
1180 100% (4/4) done
1181Auto-merged file.txt
d19fbc3c
BF
1182CONFLICT (content): Merge conflict in file.txt
1183Automatic merge failed; fix conflicts and then commit the result.
1184-------------------------------------------------
1185
1186Conflict markers are left in the problematic files, and after
1187you resolve the conflicts manually, you can update the index
1188with the contents and run git commit, as you normally would when
1189creating a new file.
1190
1191If you examine the resulting commit using gitk, you will see that it
1192has two parents, one pointing to the top of the current branch, and
1193one to the top of the other branch.
1194
d19fbc3c
BF
1195[[resolving-a-merge]]
1196Resolving a merge
1197-----------------
1198
1199When a merge isn't resolved automatically, git leaves the index and
1200the working tree in a special state that gives you all the
1201information you need to help resolve the merge.
1202
1203Files with conflicts are marked specially in the index, so until you
ef561ac7
BF
1204resolve the problem and update the index, gitlink:git-commit[1] will
1205fail:
d19fbc3c
BF
1206
1207-------------------------------------------------
1208$ git commit
1209file.txt: needs merge
1210-------------------------------------------------
1211
ef561ac7
BF
1212Also, gitlink:git-status[1] will list those files as "unmerged", and the
1213files with conflicts will have conflict markers added, like this:
1214
1215-------------------------------------------------
1216<<<<<<< HEAD:file.txt
1217Hello world
1218=======
1219Goodbye
1220>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1221-------------------------------------------------
1222
1223All you need to do is edit the files to resolve the conflicts, and then
1224
1225-------------------------------------------------
1226$ git add file.txt
1227$ git commit
1228-------------------------------------------------
1229
1230Note that the commit message will already be filled in for you with
1231some information about the merge. Normally you can just use this
1232default message unchanged, but you may add additional commentary of
1233your own if desired.
1234
1235The above is all you need to know to resolve a simple merge. But git
1236also provides more information to help resolve conflicts:
1237
e34caace 1238[[conflict-resolution]]
ef561ac7
BF
1239Getting conflict-resolution help during a merge
1240~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c
BF
1241
1242All of the changes that git was able to merge automatically are
1243already added to the index file, so gitlink:git-diff[1] shows only
ef561ac7 1244the conflicts. It uses an unusual syntax:
d19fbc3c
BF
1245
1246-------------------------------------------------
1247$ git diff
1248diff --cc file.txt
1249index 802992c,2b60207..0000000
1250--- a/file.txt
1251+++ b/file.txt
1252@@@ -1,1 -1,1 +1,5 @@@
1253++<<<<<<< HEAD:file.txt
1254 +Hello world
1255++=======
1256+ Goodbye
1257++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1258-------------------------------------------------
1259
1130845b 1260Recall that the commit which will be committed after we resolve this
d19fbc3c
BF
1261conflict will have two parents instead of the usual one: one parent
1262will be HEAD, the tip of the current branch; the other will be the
1263tip of the other branch, which is stored temporarily in MERGE_HEAD.
1264
ef561ac7
BF
1265During the merge, the index holds three versions of each file. Each of
1266these three "file stages" represents a different version of the file:
1267
1268-------------------------------------------------
1269$ git show :1:file.txt # the file in a common ancestor of both branches
1270$ git show :2:file.txt # the version from HEAD, but including any
1271 # nonconflicting changes from MERGE_HEAD
1272$ git show :3:file.txt # the version from MERGE_HEAD, but including any
1273 # nonconflicting changes from HEAD.
1274-------------------------------------------------
1275
1276Since the stage 2 and stage 3 versions have already been updated with
1277nonconflicting changes, the only remaining differences between them are
1278the important ones; thus gitlink:git-diff[1] can use the information in
1279the index to show only those conflicts.
1280
1281The diff above shows the differences between the working-tree version of
1282file.txt and the stage 2 and stage 3 versions. So instead of preceding
1283each line by a single "+" or "-", it now uses two columns: the first
1284column is used for differences between the first parent and the working
1285directory copy, and the second for differences between the second parent
1286and the working directory copy. (See the "COMBINED DIFF FORMAT" section
1287of gitlink:git-diff-files[1] for a details of the format.)
1288
1289After resolving the conflict in the obvious way (but before updating the
1290index), the diff will look like:
d19fbc3c
BF
1291
1292-------------------------------------------------
1293$ git diff
1294diff --cc file.txt
1295index 802992c,2b60207..0000000
1296--- a/file.txt
1297+++ b/file.txt
1298@@@ -1,1 -1,1 +1,1 @@@
1299- Hello world
1300 -Goodbye
1301++Goodbye world
1302-------------------------------------------------
1303
1304This shows that our resolved version deleted "Hello world" from the
1305first parent, deleted "Goodbye" from the second parent, and added
1306"Goodbye world", which was previously absent from both.
1307
ef561ac7
BF
1308Some special diff options allow diffing the working directory against
1309any of these stages:
1310
1311-------------------------------------------------
1312$ git diff -1 file.txt # diff against stage 1
1313$ git diff --base file.txt # same as the above
1314$ git diff -2 file.txt # diff against stage 2
1315$ git diff --ours file.txt # same as the above
1316$ git diff -3 file.txt # diff against stage 3
1317$ git diff --theirs file.txt # same as the above.
1318-------------------------------------------------
1319
1320The gitlink:git-log[1] and gitk[1] commands also provide special help
1321for merges:
d19fbc3c
BF
1322
1323-------------------------------------------------
1324$ git log --merge
ef561ac7 1325$ gitk --merge
d19fbc3c
BF
1326-------------------------------------------------
1327
ef561ac7
BF
1328These will display all commits which exist only on HEAD or on
1329MERGE_HEAD, and which touch an unmerged file.
d19fbc3c 1330
61d72564 1331You may also use gitlink:git-mergetool[1], which lets you merge the
c64415e2
BF
1332unmerged files using external tools such as emacs or kdiff3.
1333
ef561ac7 1334Each time you resolve the conflicts in a file and update the index:
d19fbc3c
BF
1335
1336-------------------------------------------------
1337$ git add file.txt
d19fbc3c
BF
1338-------------------------------------------------
1339
ef561ac7
BF
1340the different stages of that file will be "collapsed", after which
1341git-diff will (by default) no longer show diffs for that file.
d19fbc3c
BF
1342
1343[[undoing-a-merge]]
ae25c67a 1344Undoing a merge
d19fbc3c
BF
1345---------------
1346
1347If you get stuck and decide to just give up and throw the whole mess
1348away, you can always return to the pre-merge state with
1349
1350-------------------------------------------------
1351$ git reset --hard HEAD
1352-------------------------------------------------
1353
1130845b 1354Or, if you've already committed the merge that you want to throw away,
d19fbc3c
BF
1355
1356-------------------------------------------------
1c73bb0e 1357$ git reset --hard ORIG_HEAD
d19fbc3c
BF
1358-------------------------------------------------
1359
1360However, this last command can be dangerous in some cases--never
1361throw away a commit you have already committed if that commit may
1362itself have been merged into another branch, as doing so may confuse
1363further merges.
1364
e34caace 1365[[fast-forwards]]
d19fbc3c
BF
1366Fast-forward merges
1367-------------------
1368
1369There is one special case not mentioned above, which is treated
1370differently. Normally, a merge results in a merge commit, with two
1371parents, one pointing at each of the two lines of development that
1372were merged.
1373
59723040
BF
1374However, if the current branch is a descendant of the other--so every
1375commit present in the one is already contained in the other--then git
1376just performs a "fast forward"; the head of the current branch is moved
1377forward to point at the head of the merged-in branch, without any new
1378commits being created.
d19fbc3c 1379
e34caace 1380[[fixing-mistakes]]
b684f830
BF
1381Fixing mistakes
1382---------------
1383
1384If you've messed up the working tree, but haven't yet committed your
1385mistake, you can return the entire working tree to the last committed
1386state with
1387
1388-------------------------------------------------
1389$ git reset --hard HEAD
1390-------------------------------------------------
1391
1392If you make a commit that you later wish you hadn't, there are two
1393fundamentally different ways to fix the problem:
1394
1395 1. You can create a new commit that undoes whatever was done
1396 by the previous commit. This is the correct thing if your
1397 mistake has already been made public.
1398
1399 2. You can go back and modify the old commit. You should
1400 never do this if you have already made the history public;
1401 git does not normally expect the "history" of a project to
1402 change, and cannot correctly perform repeated merges from
1403 a branch that has had its history changed.
1404
e34caace 1405[[reverting-a-commit]]
b684f830
BF
1406Fixing a mistake with a new commit
1407~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1408
1409Creating a new commit that reverts an earlier change is very easy;
1410just pass the gitlink:git-revert[1] command a reference to the bad
1411commit; for example, to revert the most recent commit:
1412
1413-------------------------------------------------
1414$ git revert HEAD
1415-------------------------------------------------
1416
1417This will create a new commit which undoes the change in HEAD. You
1418will be given a chance to edit the commit message for the new commit.
1419
1420You can also revert an earlier change, for example, the next-to-last:
1421
1422-------------------------------------------------
1423$ git revert HEAD^
1424-------------------------------------------------
1425
1426In this case git will attempt to undo the old change while leaving
1427intact any changes made since then. If more recent changes overlap
1428with the changes to be reverted, then you will be asked to fix
1429conflicts manually, just as in the case of <<resolving-a-merge,
1430resolving a merge>>.
1431
365aa199 1432[[fixing-a-mistake-by-editing-history]]
b684f830
BF
1433Fixing a mistake by editing history
1434~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1435
1436If the problematic commit is the most recent commit, and you have not
1437yet made that commit public, then you may just
1438<<undoing-a-merge,destroy it using git-reset>>.
1439
1440Alternatively, you
1441can edit the working directory and update the index to fix your
1442mistake, just as if you were going to <<how-to-make-a-commit,create a
1443new commit>>, then run
1444
1445-------------------------------------------------
1446$ git commit --amend
1447-------------------------------------------------
1448
1449which will replace the old commit by a new commit incorporating your
1450changes, giving you a chance to edit the old commit message first.
1451
1452Again, you should never do this to a commit that may already have
1453been merged into another branch; use gitlink:git-revert[1] instead in
1454that case.
1455
1456It is also possible to edit commits further back in the history, but
1457this is an advanced topic to be left for
1458<<cleaning-up-history,another chapter>>.
1459
e34caace 1460[[checkout-of-path]]
b684f830
BF
1461Checking out an old version of a file
1462~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1463
1464In the process of undoing a previous bad change, you may find it
1465useful to check out an older version of a particular file using
1466gitlink:git-checkout[1]. We've used git checkout before to switch
1467branches, but it has quite different behavior if it is given a path
1468name: the command
1469
1470-------------------------------------------------
1471$ git checkout HEAD^ path/to/file
1472-------------------------------------------------
1473
1474replaces path/to/file by the contents it had in the commit HEAD^, and
1475also updates the index to match. It does not change branches.
1476
1477If you just want to look at an old version of the file, without
1478modifying the working directory, you can do that with
1479gitlink:git-show[1]:
1480
1481-------------------------------------------------
ed4eb0d8 1482$ git show HEAD^:path/to/file
b684f830
BF
1483-------------------------------------------------
1484
1485which will display the given version of the file.
1486
e34caace 1487[[ensuring-good-performance]]
d19fbc3c
BF
1488Ensuring good performance
1489-------------------------
1490
1491On large repositories, git depends on compression to keep the history
1492information from taking up to much space on disk or in memory.
1493
1494This compression is not performed automatically. Therefore you
17217090 1495should occasionally run gitlink:git-gc[1]:
d19fbc3c
BF
1496
1497-------------------------------------------------
1498$ git gc
1499-------------------------------------------------
1500
17217090
BF
1501to recompress the archive. This can be very time-consuming, so
1502you may prefer to run git-gc when you are not doing other work.
d19fbc3c 1503
e34caace
BF
1504
1505[[ensuring-reliability]]
11e016a3
BF
1506Ensuring reliability
1507--------------------
1508
e34caace 1509[[checking-for-corruption]]
11e016a3
BF
1510Checking the repository for corruption
1511~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1512
1191ee18
BF
1513The gitlink:git-fsck[1] command runs a number of self-consistency checks
1514on the repository, and reports on any problems. This may take some
21dcb3b7
BF
1515time. The most common warning by far is about "dangling" objects:
1516
1517-------------------------------------------------
04e50e94 1518$ git fsck
21dcb3b7
BF
1519dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1520dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1521dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1522dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
1523dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
1524dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
1525dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
1526dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1527...
1528-------------------------------------------------
1529
59723040 1530Dangling objects are not a problem. At worst they may take up a little
54782859
AP
1531extra disk space. They can sometimes provide a last-resort method for
1532recovering lost work--see <<dangling-objects>> for details. However, if
1533you wish, you can remove them with gitlink:git-prune[1] or the --prune
1191ee18 1534option to gitlink:git-gc[1]:
21dcb3b7
BF
1535
1536-------------------------------------------------
1537$ git gc --prune
1538-------------------------------------------------
1539
1191ee18
BF
1540This may be time-consuming. Unlike most other git operations (including
1541git-gc when run without any options), it is not safe to prune while
1542other git operations are in progress in the same repository.
21dcb3b7 1543
e34caace 1544[[recovering-lost-changes]]
11e016a3
BF
1545Recovering lost changes
1546~~~~~~~~~~~~~~~~~~~~~~~
1547
e34caace 1548[[reflogs]]
559e4d7a
BF
1549Reflogs
1550^^^^^^^
1551
1552Say you modify a branch with gitlink:git-reset[1] --hard, and then
1553realize that the branch was the only reference you had to that point in
1554history.
1555
1556Fortunately, git also keeps a log, called a "reflog", of all the
1557previous values of each branch. So in this case you can still find the
a6080a0a 1558old history using, for example,
559e4d7a
BF
1559
1560-------------------------------------------------
1561$ git log master@{1}
1562-------------------------------------------------
1563
1564This lists the commits reachable from the previous version of the head.
1565This syntax can be used to with any git command that accepts a commit,
1566not just with git log. Some other examples:
1567
1568-------------------------------------------------
1569$ git show master@{2} # See where the branch pointed 2,
1570$ git show master@{3} # 3, ... changes ago.
1571$ gitk master@{yesterday} # See where it pointed yesterday,
1572$ gitk master@{"1 week ago"} # ... or last week
953f3d6f
BF
1573$ git log --walk-reflogs master # show reflog entries for master
1574-------------------------------------------------
1575
1576A separate reflog is kept for the HEAD, so
1577
1578-------------------------------------------------
1579$ git show HEAD@{"1 week ago"}
559e4d7a
BF
1580-------------------------------------------------
1581
953f3d6f
BF
1582will show what HEAD pointed to one week ago, not what the current branch
1583pointed to one week ago. This allows you to see the history of what
1584you've checked out.
1585
559e4d7a 1586The reflogs are kept by default for 30 days, after which they may be
036be17e 1587pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn
559e4d7a
BF
1588how to control this pruning, and see the "SPECIFYING REVISIONS"
1589section of gitlink:git-rev-parse[1] for details.
1590
1591Note that the reflog history is very different from normal git history.
1592While normal history is shared by every repository that works on the
1593same project, the reflog history is not shared: it tells you only about
1594how the branches in your local repository have changed over time.
1595
59723040 1596[[dangling-object-recovery]]
559e4d7a
BF
1597Examining dangling objects
1598^^^^^^^^^^^^^^^^^^^^^^^^^^
1599
59723040
BF
1600In some situations the reflog may not be able to save you. For example,
1601suppose you delete a branch, then realize you need the history it
1602contained. The reflog is also deleted; however, if you have not yet
1603pruned the repository, then you may still be able to find the lost
1604commits in the dangling objects that git-fsck reports. See
1605<<dangling-objects>> for the details.
559e4d7a
BF
1606
1607-------------------------------------------------
1608$ git fsck
1609dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1610dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1611dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1612...
1613-------------------------------------------------
1614
aacd404e 1615You can examine
559e4d7a
BF
1616one of those dangling commits with, for example,
1617
1618------------------------------------------------
1619$ gitk 7281251ddd --not --all
1620------------------------------------------------
1621
1622which does what it sounds like: it says that you want to see the commit
1623history that is described by the dangling commit(s), but not the
1624history that is described by all your existing branches and tags. Thus
1625you get exactly the history reachable from that commit that is lost.
1626(And notice that it might not be just one commit: we only report the
1627"tip of the line" as being dangling, but there might be a whole deep
79c96c57 1628and complex commit history that was dropped.)
559e4d7a
BF
1629
1630If you decide you want the history back, you can always create a new
1631reference pointing to it, for example, a new branch:
1632
1633------------------------------------------------
a6080a0a 1634$ git branch recovered-branch 7281251ddd
559e4d7a
BF
1635------------------------------------------------
1636
59723040
BF
1637Other types of dangling objects (blobs and trees) are also possible, and
1638dangling objects can arise in other situations.
1639
11e016a3 1640
e34caace 1641[[sharing-development]]
d19fbc3c 1642Sharing development with others
b684f830 1643===============================
d19fbc3c
BF
1644
1645[[getting-updates-with-git-pull]]
1646Getting updates with git pull
b684f830 1647-----------------------------
d19fbc3c
BF
1648
1649After you clone a repository and make a few changes of your own, you
1650may wish to check the original repository for updates and merge them
1651into your own work.
1652
1653We have already seen <<Updating-a-repository-with-git-fetch,how to
1654keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1655and how to merge two branches. So you can merge in changes from the
1656original repository's master branch with:
1657
1658-------------------------------------------------
1659$ git fetch
1660$ git merge origin/master
1661-------------------------------------------------
1662
1663However, the gitlink:git-pull[1] command provides a way to do this in
1664one step:
1665
1666-------------------------------------------------
1667$ git pull origin master
1668-------------------------------------------------
1669
1670In fact, "origin" is normally the default repository to pull from,
1671and the default branch is normally the HEAD of the remote repository,
1672so often you can accomplish the above with just
1673
1674-------------------------------------------------
1675$ git pull
1676-------------------------------------------------
1677
c64415e2
BF
1678See the descriptions of the branch.<name>.remote and branch.<name>.merge
1679options in gitlink:git-config[1] to learn how to control these defaults
1680depending on the current branch. Also note that the --track option to
1681gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to
1682automatically set the default remote branch to pull from at the time
1683that a branch is created:
1684
1685-------------------------------------------------
1da158ea 1686$ git checkout --track -b maint origin/maint
c64415e2 1687-------------------------------------------------
d19fbc3c
BF
1688
1689In addition to saving you keystrokes, "git pull" also helps you by
1690producing a default commit message documenting the branch and
1691repository that you pulled from.
1692
1693(But note that no such commit will be created in the case of a
1694<<fast-forwards,fast forward>>; instead, your branch will just be
79c96c57 1695updated to point to the latest commit from the upstream branch.)
d19fbc3c 1696
1191ee18
BF
1697The git-pull command can also be given "." as the "remote" repository,
1698in which case it just merges in a branch from the current repository; so
4c63ff45
BF
1699the commands
1700
1701-------------------------------------------------
1702$ git pull . branch
1703$ git merge branch
1704-------------------------------------------------
1705
1706are roughly equivalent. The former is actually very commonly used.
1707
e34caace 1708[[submitting-patches]]
d19fbc3c 1709Submitting patches to a project
b684f830 1710-------------------------------
d19fbc3c
BF
1711
1712If you just have a few changes, the simplest way to submit them may
1713just be to send them as patches in email:
1714
036be17e 1715First, use gitlink:git-format-patch[1]; for example:
d19fbc3c
BF
1716
1717-------------------------------------------------
eb6ae7f4 1718$ git format-patch origin
d19fbc3c
BF
1719-------------------------------------------------
1720
1721will produce a numbered series of files in the current directory, one
1722for each patch in the current branch but not in origin/HEAD.
1723
1724You can then import these into your mail client and send them by
1725hand. However, if you have a lot to send at once, you may prefer to
1726use the gitlink:git-send-email[1] script to automate the process.
1727Consult the mailing list for your project first to determine how they
1728prefer such patches be handled.
1729
e34caace 1730[[importing-patches]]
d19fbc3c 1731Importing patches to a project
b684f830 1732------------------------------
d19fbc3c
BF
1733
1734Git also provides a tool called gitlink:git-am[1] (am stands for
1735"apply mailbox"), for importing such an emailed series of patches.
1736Just save all of the patch-containing messages, in order, into a
1737single mailbox file, say "patches.mbox", then run
1738
1739-------------------------------------------------
eb6ae7f4 1740$ git am -3 patches.mbox
d19fbc3c
BF
1741-------------------------------------------------
1742
1743Git will apply each patch in order; if any conflicts are found, it
1744will stop, and you can fix the conflicts as described in
01997b4a
BF
1745"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells
1746git to perform a merge; if you would prefer it just to abort and
1747leave your tree and index untouched, you may omit that option.)
1748
1749Once the index is updated with the results of the conflict
1750resolution, instead of creating a new commit, just run
d19fbc3c
BF
1751
1752-------------------------------------------------
1753$ git am --resolved
1754-------------------------------------------------
1755
1756and git will create the commit for you and continue applying the
1757remaining patches from the mailbox.
1758
1759The final result will be a series of commits, one for each patch in
1760the original mailbox, with authorship and commit log message each
1761taken from the message containing each patch.
1762
eda69449
BF
1763[[public-repositories]]
1764Public git repositories
1765-----------------------
d19fbc3c 1766
eda69449
BF
1767Another way to submit changes to a project is to tell the maintainer of
1768that project to pull the changes from your repository using git-pull[1].
1769In the section "<<getting-updates-with-git-pull, Getting updates with
1770git pull>>" we described this as a way to get updates from the "main"
1771repository, but it works just as well in the other direction.
d19fbc3c 1772
eda69449
BF
1773If you and the maintainer both have accounts on the same machine, then
1774you can just pull changes from each other's repositories directly;
11d51533 1775commands that accept repository URLs as arguments will also accept a
eda69449 1776local directory name:
d19fbc3c
BF
1777
1778-------------------------------------------------
1779$ git clone /path/to/repository
1780$ git pull /path/to/other/repository
1781-------------------------------------------------
1782
11d51533
BF
1783or an ssh url:
1784
1785-------------------------------------------------
1786$ git clone ssh://yourhost/~you/repository
1787-------------------------------------------------
1788
1789For projects with few developers, or for synchronizing a few private
1790repositories, this may be all you need.
1791
eda69449
BF
1792However, the more common way to do this is to maintain a separate public
1793repository (usually on a different host) for others to pull changes
1794from. This is usually more convenient, and allows you to cleanly
1795separate private work in progress from publicly visible work.
d19fbc3c
BF
1796
1797You will continue to do your day-to-day work in your personal
1798repository, but periodically "push" changes from your personal
1799repository into your public repository, allowing other developers to
1800pull from that repository. So the flow of changes, in a situation
1801where there is one other developer with a public repository, looks
1802like this:
1803
1804 you push
1805 your personal repo ------------------> your public repo
a6080a0a 1806 ^ |
d19fbc3c
BF
1807 | |
1808 | you pull | they pull
1809 | |
1810 | |
1811 | they push V
1812 their public repo <------------------- their repo
1813
11d51533
BF
1814We explain how to do this in the following sections.
1815
eda69449
BF
1816[[setting-up-a-public-repository]]
1817Setting up a public repository
1818~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1819
1820Assume your personal repository is in the directory ~/proj. We
1821first create a new clone of the repository and tell git-daemon that it
1822is meant to be public:
d19fbc3c
BF
1823
1824-------------------------------------------------
52c80037 1825$ git clone --bare ~/proj proj.git
eda69449 1826$ touch proj.git/git-daemon-export-ok
d19fbc3c
BF
1827-------------------------------------------------
1828
52c80037 1829The resulting directory proj.git contains a "bare" git repository--it is
eda69449
BF
1830just the contents of the ".git" directory, without any files checked out
1831around it.
d19fbc3c 1832
c64415e2 1833Next, copy proj.git to the server where you plan to host the
d19fbc3c
BF
1834public repository. You can use scp, rsync, or whatever is most
1835convenient.
1836
eda69449
BF
1837[[exporting-via-git]]
1838Exporting a git repository via the git protocol
1839~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1840
1841This is the preferred method.
1842
1843If someone else administers the server, they should tell you what
1844directory to put the repository in, and what git:// url it will appear
1845at. You can then skip to the section
d19fbc3c
BF
1846"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1847repository>>", below.
1848
eda69449
BF
1849Otherwise, all you need to do is start gitlink:git-daemon[1]; it will
1850listen on port 9418. By default, it will allow access to any directory
1851that looks like a git directory and contains the magic file
1852git-daemon-export-ok. Passing some directory paths as git-daemon
1853arguments will further restrict the exports to those paths.
1854
1855You can also run git-daemon as an inetd service; see the
1856gitlink:git-daemon[1] man page for details. (See especially the
1857examples section.)
d19fbc3c
BF
1858
1859[[exporting-via-http]]
1860Exporting a git repository via http
eda69449 1861~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c
BF
1862
1863The git protocol gives better performance and reliability, but on a
1864host with a web server set up, http exports may be simpler to set up.
1865
1866All you need to do is place the newly created bare git repository in
1867a directory that is exported by the web server, and make some
1868adjustments to give web clients some extra information they need:
1869
1870-------------------------------------------------
1871$ mv proj.git /home/you/public_html/proj.git
1872$ cd proj.git
c64415e2 1873$ git --bare update-server-info
d19fbc3c
BF
1874$ chmod a+x hooks/post-update
1875-------------------------------------------------
1876
1877(For an explanation of the last two lines, see
1878gitlink:git-update-server-info[1], and the documentation
a2983cb7 1879link:hooks.html[Hooks used by git].)
d19fbc3c
BF
1880
1881Advertise the url of proj.git. Anybody else should then be able to
1882clone or pull from that url, for example with a commandline like:
1883
1884-------------------------------------------------
1885$ git clone http://yourserver.com/~you/proj.git
1886-------------------------------------------------
1887
1888(See also
1889link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1890for a slightly more sophisticated setup using WebDAV which also
1891allows pushing over http.)
1892
d19fbc3c
BF
1893[[pushing-changes-to-a-public-repository]]
1894Pushing changes to a public repository
eda69449 1895~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c 1896
eda69449 1897Note that the two techniques outlined above (exporting via
d19fbc3c
BF
1898<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1899maintainers to fetch your latest changes, but they do not allow write
1900access, which you will need to update the public repository with the
1901latest changes created in your private repository.
1902
1903The simplest way to do this is using gitlink:git-push[1] and ssh; to
1904update the remote branch named "master" with the latest state of your
1905branch named "master", run
1906
1907-------------------------------------------------
1908$ git push ssh://yourserver.com/~you/proj.git master:master
1909-------------------------------------------------
1910
1911or just
1912
1913-------------------------------------------------
1914$ git push ssh://yourserver.com/~you/proj.git master
1915-------------------------------------------------
1916
1917As with git-fetch, git-push will complain if this does not result in
1918a <<fast-forwards,fast forward>>. Normally this is a sign of
1919something wrong. However, if you are sure you know what you're
1920doing, you may force git-push to perform the update anyway by
1921proceeding the branch name by a plus sign:
1922
1923-------------------------------------------------
1924$ git push ssh://yourserver.com/~you/proj.git +master
1925-------------------------------------------------
1926
11d51533
BF
1927Note that the target of a "push" is normally a
1928<<def_bare_repository,bare>> repository. You can also push to a
1929repository that has a checked-out working tree, but the working tree
1930will not be updated by the push. This may lead to unexpected results if
1931the branch you push to is the currently checked-out branch!
1932
d19fbc3c
BF
1933As with git-fetch, you may also set up configuration options to
1934save typing; so, for example, after
1935
1936-------------------------------------------------
c64415e2 1937$ cat >>.git/config <<EOF
d19fbc3c
BF
1938[remote "public-repo"]
1939 url = ssh://yourserver.com/~you/proj.git
1940EOF
1941-------------------------------------------------
1942
1943you should be able to perform the above push with just
1944
1945-------------------------------------------------
1946$ git push public-repo master
1947-------------------------------------------------
1948
1949See the explanations of the remote.<name>.url, branch.<name>.remote,
9d13bda3 1950and remote.<name>.push options in gitlink:git-config[1] for
d19fbc3c
BF
1951details.
1952
e34caace 1953[[setting-up-a-shared-repository]]
d19fbc3c 1954Setting up a shared repository
eda69449 1955~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c
BF
1956
1957Another way to collaborate is by using a model similar to that
1958commonly used in CVS, where several developers with special rights
1959all push to and pull from a single shared repository. See
a2983cb7 1960link:cvs-migration.html[git for CVS users] for instructions on how to
d19fbc3c
BF
1961set this up.
1962
8fae2225
BF
1963However, while there is nothing wrong with git's support for shared
1964repositories, this mode of operation is not generally recommended,
1965simply because the mode of collaboration that git supports--by
1966exchanging patches and pulling from public repositories--has so many
1967advantages over the central shared repository:
1968
1969 - Git's ability to quickly import and merge patches allows a
1970 single maintainer to process incoming changes even at very
1971 high rates. And when that becomes too much, git-pull provides
1972 an easy way for that maintainer to delegate this job to other
1973 maintainers while still allowing optional review of incoming
1974 changes.
1975 - Since every developer's repository has the same complete copy
1976 of the project history, no repository is special, and it is
1977 trivial for another developer to take over maintenance of a
1978 project, either by mutual agreement, or because a maintainer
1979 becomes unresponsive or difficult to work with.
1980 - The lack of a central group of "committers" means there is
1981 less need for formal decisions about who is "in" and who is
1982 "out".
1983
e34caace 1984[[setting-up-gitweb]]
eda69449
BF
1985Allowing web browsing of a repository
1986~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c 1987
a8cd1402
BF
1988The gitweb cgi script provides users an easy way to browse your
1989project's files and history without having to install git; see the file
04483524 1990gitweb/INSTALL in the git source tree for instructions on setting it up.
d19fbc3c 1991
e34caace 1992[[sharing-development-examples]]
b684f830
BF
1993Examples
1994--------
d19fbc3c 1995
9e2163ea
BF
1996[[maintaining-topic-branches]]
1997Maintaining topic branches for a Linux subsystem maintainer
1998~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1999
2000This describes how Tony Luck uses git in his role as maintainer of the
2001IA64 architecture for the Linux kernel.
2002
2003He uses two public branches:
2004
2005 - A "test" tree into which patches are initially placed so that they
2006 can get some exposure when integrated with other ongoing development.
2007 This tree is available to Andrew for pulling into -mm whenever he
2008 wants.
2009
2010 - A "release" tree into which tested patches are moved for final sanity
2011 checking, and as a vehicle to send them upstream to Linus (by sending
2012 him a "please pull" request.)
2013
2014He also uses a set of temporary branches ("topic branches"), each
2015containing a logical grouping of patches.
2016
2017To set this up, first create your work tree by cloning Linus's public
2018tree:
2019
2020-------------------------------------------------
2021$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
2022$ cd work
2023-------------------------------------------------
2024
2025Linus's tree will be stored in the remote branch named origin/master,
2026and can be updated using gitlink:git-fetch[1]; you can track other
2027public trees using gitlink:git-remote[1] to set up a "remote" and
2028git-fetch[1] to keep them up-to-date; see <<repositories-and-branches>>.
2029
2030Now create the branches in which you are going to work; these start out
2031at the current tip of origin/master branch, and should be set up (using
2032the --track option to gitlink:git-branch[1]) to merge changes in from
2033Linus by default.
2034
2035-------------------------------------------------
2036$ git branch --track test origin/master
2037$ git branch --track release origin/master
2038-------------------------------------------------
2039
2040These can be easily kept up to date using gitlink:git-pull[1]
2041
2042-------------------------------------------------
2043$ git checkout test && git pull
2044$ git checkout release && git pull
2045-------------------------------------------------
2046
2047Important note! If you have any local changes in these branches, then
2048this merge will create a commit object in the history (with no local
2049changes git will simply do a "Fast forward" merge). Many people dislike
2050the "noise" that this creates in the Linux history, so you should avoid
2051doing this capriciously in the "release" branch, as these noisy commits
2052will become part of the permanent history when you ask Linus to pull
2053from the release branch.
2054
2055A few configuration variables (see gitlink:git-config[1]) can
2056make it easy to push both branches to your public tree. (See
2057<<setting-up-a-public-repository>>.)
2058
2059-------------------------------------------------
2060$ cat >> .git/config <<EOF
2061[remote "mytree"]
2062 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
2063 push = release
2064 push = test
2065EOF
2066-------------------------------------------------
2067
2068Then you can push both the test and release trees using
2069gitlink:git-push[1]:
2070
2071-------------------------------------------------
2072$ git push mytree
2073-------------------------------------------------
2074
2075or push just one of the test and release branches using:
2076
2077-------------------------------------------------
2078$ git push mytree test
2079-------------------------------------------------
2080
2081or
2082
2083-------------------------------------------------
2084$ git push mytree release
2085-------------------------------------------------
2086
2087Now to apply some patches from the community. Think of a short
2088snappy name for a branch to hold this patch (or related group of
2089patches), and create a new branch from the current tip of Linus's
2090branch:
2091
2092-------------------------------------------------
2093$ git checkout -b speed-up-spinlocks origin
2094-------------------------------------------------
2095
2096Now you apply the patch(es), run some tests, and commit the change(s). If
2097the patch is a multi-part series, then you should apply each as a separate
2098commit to this branch.
2099
2100-------------------------------------------------
2101$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
2102-------------------------------------------------
2103
2104When you are happy with the state of this change, you can pull it into the
2105"test" branch in preparation to make it public:
2106
2107-------------------------------------------------
2108$ git checkout test && git pull . speed-up-spinlocks
2109-------------------------------------------------
2110
2111It is unlikely that you would have any conflicts here ... but you might if you
2112spent a while on this step and had also pulled new versions from upstream.
2113
2114Some time later when enough time has passed and testing done, you can pull the
2115same branch into the "release" tree ready to go upstream. This is where you
2116see the value of keeping each patch (or patch series) in its own branch. It
2117means that the patches can be moved into the "release" tree in any order.
2118
2119-------------------------------------------------
2120$ git checkout release && git pull . speed-up-spinlocks
2121-------------------------------------------------
2122
2123After a while, you will have a number of branches, and despite the
2124well chosen names you picked for each of them, you may forget what
2125they are for, or what status they are in. To get a reminder of what
2126changes are in a specific branch, use:
2127
2128-------------------------------------------------
2129$ git log linux..branchname | git-shortlog
2130-------------------------------------------------
2131
2132To see whether it has already been merged into the test or release branches
2133use:
2134
2135-------------------------------------------------
2136$ git log test..branchname
2137-------------------------------------------------
2138
2139or
2140
2141-------------------------------------------------
2142$ git log release..branchname
2143-------------------------------------------------
2144
2145(If this branch has not yet been merged you will see some log entries.
2146If it has been merged, then there will be no output.)
2147
2148Once a patch completes the great cycle (moving from test to release,
2149then pulled by Linus, and finally coming back into your local
2150"origin/master" branch) the branch for this change is no longer needed.
2151You detect this when the output from:
2152
2153-------------------------------------------------
2154$ git log origin..branchname
2155-------------------------------------------------
2156
2157is empty. At this point the branch can be deleted:
2158
2159-------------------------------------------------
2160$ git branch -d branchname
2161-------------------------------------------------
2162
2163Some changes are so trivial that it is not necessary to create a separate
2164branch and then merge into each of the test and release branches. For
2165these changes, just apply directly to the "release" branch, and then
2166merge that into the "test" branch.
2167
2168To create diffstat and shortlog summaries of changes to include in a "please
2169pull" request to Linus you can use:
2170
2171-------------------------------------------------
2172$ git diff --stat origin..release
2173-------------------------------------------------
2174
2175and
2176
2177-------------------------------------------------
2178$ git log -p origin..release | git shortlog
2179-------------------------------------------------
2180
2181Here are some of the scripts that simplify all this even further.
2182
2183-------------------------------------------------
2184==== update script ====
2185# Update a branch in my GIT tree. If the branch to be updated
2186# is origin, then pull from kernel.org. Otherwise merge
2187# origin/master branch into test|release branch
2188
2189case "$1" in
2190test|release)
2191 git checkout $1 && git pull . origin
2192 ;;
2193origin)
2194 before=$(cat .git/refs/remotes/origin/master)
2195 git fetch origin
2196 after=$(cat .git/refs/remotes/origin/master)
2197 if [ $before != $after ]
2198 then
2199 git log $before..$after | git shortlog
2200 fi
2201 ;;
2202*)
2203 echo "Usage: $0 origin|test|release" 1>&2
2204 exit 1
2205 ;;
2206esac
2207-------------------------------------------------
2208
2209-------------------------------------------------
2210==== merge script ====
2211# Merge a branch into either the test or release branch
2212
2213pname=$0
2214
2215usage()
2216{
2217 echo "Usage: $pname branch test|release" 1>&2
2218 exit 1
2219}
2220
2221if [ ! -f .git/refs/heads/"$1" ]
2222then
2223 echo "Can't see branch <$1>" 1>&2
2224 usage
2225fi
2226
2227case "$2" in
2228test|release)
2229 if [ $(git log $2..$1 | wc -c) -eq 0 ]
2230 then
2231 echo $1 already merged into $2 1>&2
2232 exit 1
2233 fi
2234 git checkout $2 && git pull . $1
2235 ;;
2236*)
2237 usage
2238 ;;
2239esac
2240-------------------------------------------------
2241
2242-------------------------------------------------
2243==== status script ====
2244# report on status of my ia64 GIT tree
2245
2246gb=$(tput setab 2)
2247rb=$(tput setab 1)
2248restore=$(tput setab 9)
2249
2250if [ `git rev-list test..release | wc -c` -gt 0 ]
2251then
2252 echo $rb Warning: commits in release that are not in test $restore
2253 git log test..release
2254fi
2255
2256for branch in `ls .git/refs/heads`
2257do
2258 if [ $branch = test -o $branch = release ]
2259 then
2260 continue
2261 fi
2262
2263 echo -n $gb ======= $branch ====== $restore " "
2264 status=
2265 for ref in test release origin/master
2266 do
2267 if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
2268 then
2269 status=$status${ref:0:1}
2270 fi
2271 done
2272 case $status in
2273 trl)
2274 echo $rb Need to pull into test $restore
2275 ;;
2276 rl)
2277 echo "In test"
2278 ;;
2279 l)
2280 echo "Waiting for linus"
2281 ;;
2282 "")
2283 echo $rb All done $restore
2284 ;;
2285 *)
2286 echo $rb "<$status>" $restore
2287 ;;
2288 esac
2289 git log origin/master..$branch | git shortlog
2290done
2291-------------------------------------------------
d19fbc3c 2292
d19fbc3c 2293
d19fbc3c 2294[[cleaning-up-history]]
4c63ff45
BF
2295Rewriting history and maintaining patch series
2296==============================================
2297
2298Normally commits are only added to a project, never taken away or
2299replaced. Git is designed with this assumption, and violating it will
2300cause git's merge machinery (for example) to do the wrong thing.
2301
2302However, there is a situation in which it can be useful to violate this
2303assumption.
2304
e34caace 2305[[patch-series]]
4c63ff45
BF
2306Creating the perfect patch series
2307---------------------------------
2308
2309Suppose you are a contributor to a large project, and you want to add a
2310complicated feature, and to present it to the other developers in a way
2311that makes it easy for them to read your changes, verify that they are
2312correct, and understand why you made each change.
2313
b181d57f 2314If you present all of your changes as a single patch (or commit), they
79c96c57 2315may find that it is too much to digest all at once.
4c63ff45
BF
2316
2317If you present them with the entire history of your work, complete with
2318mistakes, corrections, and dead ends, they may be overwhelmed.
2319
2320So the ideal is usually to produce a series of patches such that:
2321
2322 1. Each patch can be applied in order.
2323
2324 2. Each patch includes a single logical change, together with a
2325 message explaining the change.
2326
2327 3. No patch introduces a regression: after applying any initial
2328 part of the series, the resulting project still compiles and
2329 works, and has no bugs that it didn't have before.
2330
2331 4. The complete series produces the same end result as your own
2332 (probably much messier!) development process did.
2333
b181d57f
BF
2334We will introduce some tools that can help you do this, explain how to
2335use them, and then explain some of the problems that can arise because
2336you are rewriting history.
4c63ff45 2337
e34caace 2338[[using-git-rebase]]
4c63ff45
BF
2339Keeping a patch series up to date using git-rebase
2340--------------------------------------------------
2341
79c96c57
MC
2342Suppose that you create a branch "mywork" on a remote-tracking branch
2343"origin", and create some commits on top of it:
4c63ff45
BF
2344
2345-------------------------------------------------
2346$ git checkout -b mywork origin
2347$ vi file.txt
2348$ git commit
2349$ vi otherfile.txt
2350$ git commit
2351...
2352-------------------------------------------------
2353
2354You have performed no merges into mywork, so it is just a simple linear
2355sequence of patches on top of "origin":
2356
1dc71a91 2357................................................
4c63ff45
BF
2358 o--o--o <-- origin
2359 \
2360 o--o--o <-- mywork
1dc71a91 2361................................................
4c63ff45
BF
2362
2363Some more interesting work has been done in the upstream project, and
2364"origin" has advanced:
2365
1dc71a91 2366................................................
4c63ff45
BF
2367 o--o--O--o--o--o <-- origin
2368 \
2369 a--b--c <-- mywork
1dc71a91 2370................................................
4c63ff45
BF
2371
2372At this point, you could use "pull" to merge your changes back in;
2373the result would create a new merge commit, like this:
2374
1dc71a91 2375................................................
4c63ff45
BF
2376 o--o--O--o--o--o <-- origin
2377 \ \
2378 a--b--c--m <-- mywork
1dc71a91 2379................................................
a6080a0a 2380
4c63ff45
BF
2381However, if you prefer to keep the history in mywork a simple series of
2382commits without any merges, you may instead choose to use
2383gitlink:git-rebase[1]:
2384
2385-------------------------------------------------
2386$ git checkout mywork
2387$ git rebase origin
2388-------------------------------------------------
2389
b181d57f
BF
2390This will remove each of your commits from mywork, temporarily saving
2391them as patches (in a directory named ".dotest"), update mywork to
2392point at the latest version of origin, then apply each of the saved
2393patches to the new mywork. The result will look like:
4c63ff45
BF
2394
2395
1dc71a91 2396................................................
4c63ff45
BF
2397 o--o--O--o--o--o <-- origin
2398 \
2399 a'--b'--c' <-- mywork
1dc71a91 2400................................................
4c63ff45 2401
b181d57f
BF
2402In the process, it may discover conflicts. In that case it will stop
2403and allow you to fix the conflicts; after fixing conflicts, use "git
2404add" to update the index with those contents, and then, instead of
2405running git-commit, just run
4c63ff45
BF
2406
2407-------------------------------------------------
2408$ git rebase --continue
2409-------------------------------------------------
2410
2411and git will continue applying the rest of the patches.
2412
2413At any point you may use the --abort option to abort this process and
2414return mywork to the state it had before you started the rebase:
2415
2416-------------------------------------------------
2417$ git rebase --abort
2418-------------------------------------------------
2419
e34caace 2420[[modifying-one-commit]]
365aa199
BF
2421Modifying a single commit
2422-------------------------
2423
2424We saw in <<fixing-a-mistake-by-editing-history>> that you can replace the
2425most recent commit using
2426
2427-------------------------------------------------
2428$ git commit --amend
2429-------------------------------------------------
2430
2431which will replace the old commit by a new commit incorporating your
2432changes, giving you a chance to edit the old commit message first.
2433
2434You can also use a combination of this and gitlink:git-rebase[1] to edit
2435commits further back in your history. First, tag the problematic commit with
2436
2437-------------------------------------------------
2438$ git tag bad mywork~5
2439-------------------------------------------------
2440
2441(Either gitk or git-log may be useful for finding the commit.)
2442
25d9f3fa
BF
2443Then check out that commit, edit it, and rebase the rest of the series
2444on top of it (note that we could check out the commit on a temporary
2445branch, but instead we're using a <<detached-head,detached head>>):
365aa199
BF
2446
2447-------------------------------------------------
25d9f3fa 2448$ git checkout bad
365aa199
BF
2449$ # make changes here and update the index
2450$ git commit --amend
25d9f3fa 2451$ git rebase --onto HEAD bad mywork
365aa199
BF
2452-------------------------------------------------
2453
25d9f3fa
BF
2454When you're done, you'll be left with mywork checked out, with the top
2455patches on mywork reapplied on top of your modified commit. You can
365aa199
BF
2456then clean up with
2457
2458-------------------------------------------------
365aa199
BF
2459$ git tag -d bad
2460-------------------------------------------------
2461
2462Note that the immutable nature of git history means that you haven't really
2463"modified" existing commits; instead, you have replaced the old commits with
2464new commits having new object names.
2465
e34caace 2466[[reordering-patch-series]]
4c63ff45
BF
2467Reordering or selecting from a patch series
2468-------------------------------------------
2469
b181d57f
BF
2470Given one existing commit, the gitlink:git-cherry-pick[1] command
2471allows you to apply the change introduced by that commit and create a
2472new commit that records it. So, for example, if "mywork" points to a
2473series of patches on top of "origin", you might do something like:
2474
2475-------------------------------------------------
2476$ git checkout -b mywork-new origin
2477$ gitk origin..mywork &
2478-------------------------------------------------
2479
2480And browse through the list of patches in the mywork branch using gitk,
2481applying them (possibly in a different order) to mywork-new using
2482cherry-pick, and possibly modifying them as you go using commit
2483--amend.
2484
2485Another technique is to use git-format-patch to create a series of
2486patches, then reset the state to before the patches:
4c63ff45 2487
b181d57f
BF
2488-------------------------------------------------
2489$ git format-patch origin
2490$ git reset --hard origin
2491-------------------------------------------------
4c63ff45 2492
b181d57f
BF
2493Then modify, reorder, or eliminate patches as preferred before applying
2494them again with gitlink:git-am[1].
4c63ff45 2495
e34caace 2496[[patch-series-tools]]
4c63ff45
BF
2497Other tools
2498-----------
2499
b181d57f 2500There are numerous other tools, such as stgit, which exist for the
79c96c57 2501purpose of maintaining a patch series. These are outside of the scope of
b181d57f 2502this manual.
4c63ff45 2503
e34caace 2504[[problems-with-rewriting-history]]
4c63ff45
BF
2505Problems with rewriting history
2506-------------------------------
2507
b181d57f
BF
2508The primary problem with rewriting the history of a branch has to do
2509with merging. Suppose somebody fetches your branch and merges it into
2510their branch, with a result something like this:
2511
1dc71a91 2512................................................
b181d57f
BF
2513 o--o--O--o--o--o <-- origin
2514 \ \
2515 t--t--t--m <-- their branch:
1dc71a91 2516................................................
b181d57f
BF
2517
2518Then suppose you modify the last three commits:
2519
1dc71a91 2520................................................
b181d57f
BF
2521 o--o--o <-- new head of origin
2522 /
2523 o--o--O--o--o--o <-- old head of origin
1dc71a91 2524................................................
b181d57f
BF
2525
2526If we examined all this history together in one repository, it will
2527look like:
2528
1dc71a91 2529................................................
b181d57f
BF
2530 o--o--o <-- new head of origin
2531 /
2532 o--o--O--o--o--o <-- old head of origin
2533 \ \
2534 t--t--t--m <-- their branch:
1dc71a91 2535................................................
b181d57f
BF
2536
2537Git has no way of knowing that the new head is an updated version of
2538the old head; it treats this situation exactly the same as it would if
2539two developers had independently done the work on the old and new heads
2540in parallel. At this point, if someone attempts to merge the new head
2541in to their branch, git will attempt to merge together the two (old and
2542new) lines of development, instead of trying to replace the old by the
2543new. The results are likely to be unexpected.
2544
2545You may still choose to publish branches whose history is rewritten,
2546and it may be useful for others to be able to fetch those branches in
2547order to examine or test them, but they should not attempt to pull such
2548branches into their own work.
2549
2550For true distributed development that supports proper merging,
2551published branches should never be rewritten.
2552
e34caace 2553[[advanced-branch-management]]
b181d57f
BF
2554Advanced branch management
2555==========================
4c63ff45 2556
e34caace 2557[[fetching-individual-branches]]
b181d57f
BF
2558Fetching individual branches
2559----------------------------
2560
2561Instead of using gitlink:git-remote[1], you can also choose just
2562to update one branch at a time, and to store it locally under an
2563arbitrary name:
2564
2565-------------------------------------------------
2566$ git fetch origin todo:my-todo-work
2567-------------------------------------------------
2568
2569The first argument, "origin", just tells git to fetch from the
2570repository you originally cloned from. The second argument tells git
2571to fetch the branch named "todo" from the remote repository, and to
2572store it locally under the name refs/heads/my-todo-work.
2573
2574You can also fetch branches from other repositories; so
2575
2576-------------------------------------------------
2577$ git fetch git://example.com/proj.git master:example-master
2578-------------------------------------------------
2579
2580will create a new branch named "example-master" and store in it the
2581branch named "master" from the repository at the given URL. If you
2582already have a branch named example-master, it will attempt to
59723040
BF
2583<<fast-forwards,fast-forward>> to the commit given by example.com's
2584master branch. In more detail:
b181d57f 2585
59723040
BF
2586[[fetch-fast-forwards]]
2587git fetch and fast-forwards
2588---------------------------
b181d57f
BF
2589
2590In the previous example, when updating an existing branch, "git
2591fetch" checks to make sure that the most recent commit on the remote
2592branch is a descendant of the most recent commit on your copy of the
2593branch before updating your copy of the branch to point at the new
59723040 2594commit. Git calls this process a <<fast-forwards,fast forward>>.
b181d57f
BF
2595
2596A fast forward looks something like this:
2597
1dc71a91 2598................................................
b181d57f
BF
2599 o--o--o--o <-- old head of the branch
2600 \
2601 o--o--o <-- new head of the branch
1dc71a91 2602................................................
b181d57f
BF
2603
2604
2605In some cases it is possible that the new head will *not* actually be
2606a descendant of the old head. For example, the developer may have
2607realized she made a serious mistake, and decided to backtrack,
2608resulting in a situation like:
2609
1dc71a91 2610................................................
b181d57f
BF
2611 o--o--o--o--a--b <-- old head of the branch
2612 \
2613 o--o--o <-- new head of the branch
1dc71a91 2614................................................
b181d57f
BF
2615
2616In this case, "git fetch" will fail, and print out a warning.
2617
2618In that case, you can still force git to update to the new head, as
2619described in the following section. However, note that in the
2620situation above this may mean losing the commits labeled "a" and "b",
2621unless you've already created a reference of your own pointing to
2622them.
2623
e34caace 2624[[forcing-fetch]]
b181d57f
BF
2625Forcing git fetch to do non-fast-forward updates
2626------------------------------------------------
2627
2628If git fetch fails because the new head of a branch is not a
2629descendant of the old head, you may force the update with:
2630
2631-------------------------------------------------
2632$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
2633-------------------------------------------------
2634
c64415e2
BF
2635Note the addition of the "+" sign. Alternatively, you can use the "-f"
2636flag to force updates of all the fetched branches, as in:
2637
2638-------------------------------------------------
2639$ git fetch -f origin
2640-------------------------------------------------
2641
2642Be aware that commits that the old version of example/master pointed at
2643may be lost, as we saw in the previous section.
b181d57f 2644
e34caace 2645[[remote-branch-configuration]]
b181d57f
BF
2646Configuring remote branches
2647---------------------------
2648
2649We saw above that "origin" is just a shortcut to refer to the
79c96c57 2650repository that you originally cloned from. This information is
b181d57f 2651stored in git configuration variables, which you can see using
9d13bda3 2652gitlink:git-config[1]:
b181d57f
BF
2653
2654-------------------------------------------------
9d13bda3 2655$ git config -l
b181d57f
BF
2656core.repositoryformatversion=0
2657core.filemode=true
2658core.logallrefupdates=true
2659remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
2660remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
2661branch.master.remote=origin
2662branch.master.merge=refs/heads/master
2663-------------------------------------------------
2664
2665If there are other repositories that you also use frequently, you can
2666create similar configuration options to save typing; for example,
2667after
2668
2669-------------------------------------------------
9d13bda3 2670$ git config remote.example.url git://example.com/proj.git
b181d57f
BF
2671-------------------------------------------------
2672
2673then the following two commands will do the same thing:
2674
2675-------------------------------------------------
2676$ git fetch git://example.com/proj.git master:refs/remotes/example/master
2677$ git fetch example master:refs/remotes/example/master
2678-------------------------------------------------
2679
2680Even better, if you add one more option:
2681
2682-------------------------------------------------
9d13bda3 2683$ git config remote.example.fetch master:refs/remotes/example/master
b181d57f
BF
2684-------------------------------------------------
2685
2686then the following commands will all do the same thing:
2687
2688-------------------------------------------------
52c80037
BF
2689$ git fetch git://example.com/proj.git master:refs/remotes/example/master
2690$ git fetch example master:refs/remotes/example/master
b181d57f
BF
2691$ git fetch example
2692-------------------------------------------------
2693
2694You can also add a "+" to force the update each time:
2695
2696-------------------------------------------------
9d13bda3 2697$ git config remote.example.fetch +master:ref/remotes/example/master
b181d57f
BF
2698-------------------------------------------------
2699
2700Don't do this unless you're sure you won't mind "git fetch" possibly
2701throwing away commits on mybranch.
2702
2703Also note that all of the above configuration can be performed by
2704directly editing the file .git/config instead of using
9d13bda3 2705gitlink:git-config[1].
b181d57f 2706
9d13bda3 2707See gitlink:git-config[1] for more details on the configuration
b181d57f 2708options mentioned above.
d19fbc3c 2709
d19fbc3c 2710
35121930 2711[[git-internals]]
d19fbc3c
BF
2712Git internals
2713=============
2714
a536b08b
BF
2715Git depends on two fundamental abstractions: the "object database", and
2716the "current directory cache" aka "index".
b181d57f 2717
e34caace 2718[[the-object-database]]
b181d57f
BF
2719The Object Database
2720-------------------
2721
2722The object database is literally just a content-addressable collection
2723of objects. All objects are named by their content, which is
2724approximated by the SHA1 hash of the object itself. Objects may refer
2725to other objects (by referencing their SHA1 hash), and so you can
2726build up a hierarchy of objects.
2727
c64415e2 2728All objects have a statically determined "type" which is
b181d57f
BF
2729determined at object creation time, and which identifies the format of
2730the object (i.e. how it is used, and how it can refer to other
2731objects). There are currently four different object types: "blob",
a536b08b 2732"tree", "commit", and "tag".
b181d57f 2733
a536b08b
BF
2734A <<def_blob_object,"blob" object>> cannot refer to any other object,
2735and is, as the name implies, a pure storage object containing some
2736user data. It is used to actually store the file data, i.e. a blob
2737object is associated with some particular version of some file.
b181d57f 2738
a536b08b
BF
2739A <<def_tree_object,"tree" object>> is an object that ties one or more
2740"blob" objects into a directory structure. In addition, a tree object
2741can refer to other tree objects, thus creating a directory hierarchy.
b181d57f 2742
a536b08b
BF
2743A <<def_commit_object,"commit" object>> ties such directory hierarchies
2744together into a <<def_DAG,directed acyclic graph>> of revisions - each
2745"commit" is associated with exactly one tree (the directory hierarchy at
2746the time of the commit). In addition, a "commit" refers to one or more
2747"parent" commit objects that describe the history of how we arrived at
2748that directory hierarchy.
b181d57f
BF
2749
2750As a special case, a commit object with no parents is called the "root"
c64415e2 2751commit, and is the point of an initial project commit. Each project
b181d57f
BF
2752must have at least one root, and while you can tie several different
2753root objects together into one project by creating a commit object which
2754has two or more separate roots as its ultimate parents, that's probably
2755just going to confuse people. So aim for the notion of "one root object
a6080a0a 2756per project", even if git itself does not enforce that.
b181d57f 2757
a536b08b
BF
2758A <<def_tag_object,"tag" object>> symbolically identifies and can be
2759used to sign other objects. It contains the identifier and type of
2760another object, a symbolic name (of course!) and, optionally, a
2761signature.
b181d57f
BF
2762
2763Regardless of object type, all objects share the following
2764characteristics: they are all deflated with zlib, and have a header
2765that not only specifies their type, but also provides size information
2766about the data in the object. It's worth noting that the SHA1 hash
2767that is used to name the object is the hash of the original data
2768plus this header, so `sha1sum` 'file' does not match the object name
2769for 'file'.
2770(Historical note: in the dawn of the age of git the hash
2771was the sha1 of the 'compressed' object.)
2772
2773As a result, the general consistency of an object can always be tested
2774independently of the contents or the type of the object: all objects can
2775be validated by verifying that (a) their hashes match the content of the
2776file and (b) the object successfully inflates to a stream of bytes that
4c7100a9
JH
2777forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal
2778size> {plus} <byte\0> {plus} <binary object data>.
b181d57f
BF
2779
2780The structured objects can further have their structure and
2781connectivity to other objects verified. This is generally done with
04e50e94 2782the `git-fsck` program, which generates a full dependency graph
b181d57f
BF
2783of all objects, and verifies their internal consistency (in addition
2784to just verifying their superficial consistency through the hash).
2785
2786The object types in some more detail:
2787
e34caace 2788[[blob-object]]
b181d57f
BF
2789Blob Object
2790-----------
2791
2792A "blob" object is nothing but a binary blob of data, and doesn't
2793refer to anything else. There is no signature or any other
2794verification of the data, so while the object is consistent (it 'is'
2795indexed by its sha1 hash, so the data itself is certainly correct), it
2796has absolutely no other attributes. No name associations, no
2797permissions. It is purely a blob of data (i.e. normally "file
2798contents").
2799
2800In particular, since the blob is entirely defined by its data, if two
2801files in a directory tree (or in multiple different versions of the
2802repository) have the same contents, they will share the same blob
2803object. The object is totally independent of its location in the
2804directory tree, and renaming a file does not change the object that
2805file is associated with in any way.
2806
2807A blob is typically created when gitlink:git-update-index[1]
2808is run, and its data can be accessed by gitlink:git-cat-file[1].
2809
e34caace 2810[[tree-object]]
b181d57f
BF
2811Tree Object
2812-----------
2813
2814The next hierarchical object type is the "tree" object. A tree object
2815is a list of mode/name/blob data, sorted by name. Alternatively, the
2816mode data may specify a directory mode, in which case instead of
2817naming a blob, that name is associated with another TREE object.
2818
2819Like the "blob" object, a tree object is uniquely determined by the
2820set contents, and so two separate but identical trees will always
2821share the exact same object. This is true at all levels, i.e. it's
2822true for a "leaf" tree (which does not refer to any other trees, only
2823blobs) as well as for a whole subdirectory.
2824
2825For that reason a "tree" object is just a pure data abstraction: it
2826has no history, no signatures, no verification of validity, except
2827that since the contents are again protected by the hash itself, we can
2828trust that the tree is immutable and its contents never change.
2829
2830So you can trust the contents of a tree to be valid, the same way you
2831can trust the contents of a blob, but you don't know where those
2832contents 'came' from.
2833
2834Side note on trees: since a "tree" object is a sorted list of
2835"filename+content", you can create a diff between two trees without
2836actually having to unpack two trees. Just ignore all common parts,
2837and your diff will look right. In other words, you can effectively
2838(and efficiently) tell the difference between any two random trees by
2839O(n) where "n" is the size of the difference, rather than the size of
2840the tree.
2841
2842Side note 2 on trees: since the name of a "blob" depends entirely and
2843exclusively on its contents (i.e. there are no names or permissions
2844involved), you can see trivial renames or permission changes by
2845noticing that the blob stayed the same. However, renames with data
2846changes need a smarter "diff" implementation.
2847
2848A tree is created with gitlink:git-write-tree[1] and
2849its data can be accessed by gitlink:git-ls-tree[1].
2850Two trees can be compared with gitlink:git-diff-tree[1].
2851
e34caace 2852[[commit-object]]
b181d57f
BF
2853Commit Object
2854-------------
2855
2856The "commit" object is an object that introduces the notion of
2857history into the picture. In contrast to the other objects, it
2858doesn't just describe the physical state of a tree, it describes how
2859we got there, and why.
2860
2861A "commit" is defined by the tree-object that it results in, the
2862parent commits (zero, one or more) that led up to that point, and a
2863comment on what happened. Again, a commit is not trusted per se:
2864the contents are well-defined and "safe" due to the cryptographically
2865strong signatures at all levels, but there is no reason to believe
2866that the tree is "good" or that the merge information makes sense.
2867The parents do not have to actually have any relationship with the
2868result, for example.
2869
c64415e2 2870Note on commits: unlike some SCM's, commits do not contain
b181d57f
BF
2871rename information or file mode change information. All of that is
2872implicit in the trees involved (the result tree, and the result trees
2873of the parents), and describing that makes no sense in this idiotic
2874file manager.
2875
2876A commit is created with gitlink:git-commit-tree[1] and
2877its data can be accessed by gitlink:git-cat-file[1].
2878
e34caace 2879[[trust]]
b181d57f
BF
2880Trust
2881-----
2882
2883An aside on the notion of "trust". Trust is really outside the scope
2884of "git", but it's worth noting a few things. First off, since
2885everything is hashed with SHA1, you 'can' trust that an object is
2886intact and has not been messed with by external sources. So the name
2887of an object uniquely identifies a known state - just not a state that
2888you may want to trust.
2889
2890Furthermore, since the SHA1 signature of a commit refers to the
2891SHA1 signatures of the tree it is associated with and the signatures
2892of the parent, a single named commit specifies uniquely a whole set
2893of history, with full contents. You can't later fake any step of the
2894way once you have the name of a commit.
2895
2896So to introduce some real trust in the system, the only thing you need
2897to do is to digitally sign just 'one' special note, which includes the
2898name of a top-level commit. Your digital signature shows others
2899that you trust that commit, and the immutability of the history of
2900commits tells others that they can trust the whole history.
2901
2902In other words, you can easily validate a whole archive by just
2903sending out a single email that tells the people the name (SHA1 hash)
2904of the top commit, and digitally sign that email using something
2905like GPG/PGP.
2906
2907To assist in this, git also provides the tag object...
2908
e34caace 2909[[tag-object]]
b181d57f
BF
2910Tag Object
2911----------
2912
2913Git provides the "tag" object to simplify creating, managing and
2914exchanging symbolic and signed tokens. The "tag" object at its
2915simplest simply symbolically identifies another object by containing
2916the sha1, type and symbolic name.
2917
2918However it can optionally contain additional signature information
2919(which git doesn't care about as long as there's less than 8k of
2920it). This can then be verified externally to git.
2921
2922Note that despite the tag features, "git" itself only handles content
2923integrity; the trust framework (and signature provision and
2924verification) has to come from outside.
2925
2926A tag is created with gitlink:git-mktag[1],
2927its data can be accessed by gitlink:git-cat-file[1],
2928and the signature can be verified by
2929gitlink:git-verify-tag[1].
2930
2931
e34caace 2932[[the-index]]
b181d57f
BF
2933The "index" aka "Current Directory Cache"
2934-----------------------------------------
2935
2936The index is a simple binary file, which contains an efficient
c64415e2 2937representation of the contents of a virtual directory. It
b181d57f
BF
2938does so by a simple array that associates a set of names, dates,
2939permissions and content (aka "blob") objects together. The cache is
2940always kept ordered by name, and names are unique (with a few very
2941specific rules) at any point in time, but the cache has no long-term
2942meaning, and can be partially updated at any time.
2943
2944In particular, the index certainly does not need to be consistent with
2945the current directory contents (in fact, most operations will depend on
2946different ways to make the index 'not' be consistent with the directory
2947hierarchy), but it has three very important attributes:
2948
2949'(a) it can re-generate the full state it caches (not just the
2950directory structure: it contains pointers to the "blob" objects so
2951that it can regenerate the data too)'
2952
2953As a special case, there is a clear and unambiguous one-way mapping
2954from a current directory cache to a "tree object", which can be
2955efficiently created from just the current directory cache without
2956actually looking at any other data. So a directory cache at any one
2957time uniquely specifies one and only one "tree" object (but has
2958additional data to make it easy to match up that tree object with what
2959has happened in the directory)
2960
2961'(b) it has efficient methods for finding inconsistencies between that
2962cached state ("tree object waiting to be instantiated") and the
2963current state.'
2964
2965'(c) it can additionally efficiently represent information about merge
2966conflicts between different tree objects, allowing each pathname to be
2967associated with sufficient information about the trees involved that
2968you can create a three-way merge between them.'
2969
79c96c57 2970Those are the ONLY three things that the directory cache does. It's a
b181d57f
BF
2971cache, and the normal operation is to re-generate it completely from a
2972known tree object, or update/compare it with a live tree that is being
2973developed. If you blow the directory cache away entirely, you generally
2974haven't lost any information as long as you have the name of the tree
a6080a0a 2975that it described.
b181d57f 2976
48389181
MF
2977At the same time, the index is also the staging area for creating
2978new trees, and creating a new tree always involves a controlled
2979modification of the index file. In particular, the index file can
2980have the representation of an intermediate tree that has not yet been
2981instantiated. So the index can be thought of as a write-back cache,
2982which can contain dirty information that has not yet been written back
2983to the backing store.
b181d57f
BF
2984
2985
2986
e34caace 2987[[the-workflow]]
b181d57f
BF
2988The Workflow
2989------------
2990
2991Generally, all "git" operations work on the index file. Some operations
2992work *purely* on the index file (showing the current state of the
2993index), but most operations move data to and from the index file. Either
2994from the database or from the working directory. Thus there are four
a6080a0a 2995main combinations:
b181d57f 2996
e34caace 2997[[working-directory-to-index]]
b181d57f
BF
2998working directory -> index
2999~~~~~~~~~~~~~~~~~~~~~~~~~~
3000
3001You update the index with information from the working directory with
3002the gitlink:git-update-index[1] command. You
3003generally update the index information by just specifying the filename
3004you want to update, like so:
3005
3006-------------------------------------------------
3007$ git-update-index filename
3008-------------------------------------------------
3009
3010but to avoid common mistakes with filename globbing etc, the command
3011will not normally add totally new entries or remove old entries,
3012i.e. it will normally just update existing cache entries.
3013
3014To tell git that yes, you really do realize that certain files no
3015longer exist, or that new files should be added, you
3016should use the `--remove` and `--add` flags respectively.
3017
3018NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
3019necessarily be removed: if the files still exist in your directory
3020structure, the index will be updated with their new status, not
3021removed. The only thing `--remove` means is that update-cache will be
3022considering a removed file to be a valid thing, and if the file really
3023does not exist any more, it will update the index accordingly.
3024
3025As a special case, you can also do `git-update-index --refresh`, which
3026will refresh the "stat" information of each index to match the current
3027stat information. It will 'not' update the object status itself, and
3028it will only update the fields that are used to quickly test whether
3029an object still matches its old backing store object.
3030
e34caace 3031[[index-to-object-database]]
b181d57f
BF
3032index -> object database
3033~~~~~~~~~~~~~~~~~~~~~~~~
3034
3035You write your current index file to a "tree" object with the program
3036
3037-------------------------------------------------
3038$ git-write-tree
3039-------------------------------------------------
3040
3041that doesn't come with any options - it will just write out the
3042current index into the set of tree objects that describe that state,
3043and it will return the name of the resulting top-level tree. You can
3044use that tree to re-generate the index at any time by going in the
3045other direction:
3046
e34caace 3047[[object-database-to-index]]
b181d57f
BF
3048object database -> index
3049~~~~~~~~~~~~~~~~~~~~~~~~
3050
3051You read a "tree" file from the object database, and use that to
3052populate (and overwrite - don't do this if your index contains any
3053unsaved state that you might want to restore later!) your current
3054index. Normal operation is just
3055
3056-------------------------------------------------
3057$ git-read-tree <sha1 of tree>
3058-------------------------------------------------
3059
3060and your index file will now be equivalent to the tree that you saved
3061earlier. However, that is only your 'index' file: your working
3062directory contents have not been modified.
3063
e34caace 3064[[index-to-working-directory]]
b181d57f
BF
3065index -> working directory
3066~~~~~~~~~~~~~~~~~~~~~~~~~~
3067
3068You update your working directory from the index by "checking out"
3069files. This is not a very common operation, since normally you'd just
3070keep your files updated, and rather than write to your working
3071directory, you'd tell the index files about the changes in your
3072working directory (i.e. `git-update-index`).
3073
3074However, if you decide to jump to a new version, or check out somebody
3075else's version, or just restore a previous tree, you'd populate your
3076index file with read-tree, and then you need to check out the result
3077with
3078
3079-------------------------------------------------
3080$ git-checkout-index filename
3081-------------------------------------------------
3082
3083or, if you want to check out all of the index, use `-a`.
3084
3085NOTE! git-checkout-index normally refuses to overwrite old files, so
3086if you have an old version of the tree already checked out, you will
3087need to use the "-f" flag ('before' the "-a" flag or the filename) to
3088'force' the checkout.
3089
3090
3091Finally, there are a few odds and ends which are not purely moving
3092from one representation to the other:
3093
e34caace 3094[[tying-it-all-together]]
b181d57f
BF
3095Tying it all together
3096~~~~~~~~~~~~~~~~~~~~~
3097
3098To commit a tree you have instantiated with "git-write-tree", you'd
3099create a "commit" object that refers to that tree and the history
3100behind it - most notably the "parent" commits that preceded it in
3101history.
3102
3103Normally a "commit" has one parent: the previous state of the tree
3104before a certain change was made. However, sometimes it can have two
3105or more parent commits, in which case we call it a "merge", due to the
3106fact that such a commit brings together ("merges") two or more
3107previous states represented by other commits.
3108
3109In other words, while a "tree" represents a particular directory state
3110of a working directory, a "commit" represents that state in "time",
3111and explains how we got there.
3112
3113You create a commit object by giving it the tree that describes the
3114state at the time of the commit, and a list of parents:
3115
3116-------------------------------------------------
3117$ git-commit-tree <tree> -p <parent> [-p <parent2> ..]
3118-------------------------------------------------
3119
3120and then giving the reason for the commit on stdin (either through
3121redirection from a pipe or file, or by just typing it at the tty).
3122
3123git-commit-tree will return the name of the object that represents
3124that commit, and you should save it away for later use. Normally,
3125you'd commit a new `HEAD` state, and while git doesn't care where you
3126save the note about that state, in practice we tend to just write the
3127result to the file pointed at by `.git/HEAD`, so that we can always see
3128what the last committed state was.
3129
3130Here is an ASCII art by Jon Loeliger that illustrates how
3131various pieces fit together.
3132
3133------------
3134
3135 commit-tree
3136 commit obj
3137 +----+
3138 | |
3139 | |
3140 V V
3141 +-----------+
3142 | Object DB |
3143 | Backing |
3144 | Store |
3145 +-----------+
3146 ^
3147 write-tree | |
3148 tree obj | |
3149 | | read-tree
3150 | | tree obj
3151 V
3152 +-----------+
3153 | Index |
3154 | "cache" |
3155 +-----------+
3156 update-index ^
3157 blob obj | |
3158 | |
3159 checkout-index -u | | checkout-index
3160 stat | | blob obj
3161 V
3162 +-----------+
3163 | Working |
3164 | Directory |
3165 +-----------+
3166
3167------------
3168
3169
e34caace 3170[[examining-the-data]]
b181d57f
BF
3171Examining the data
3172------------------
3173
3174You can examine the data represented in the object database and the
3175index with various helper tools. For every object, you can use
3176gitlink:git-cat-file[1] to examine details about the
3177object:
3178
3179-------------------------------------------------
3180$ git-cat-file -t <objectname>
3181-------------------------------------------------
3182
3183shows the type of the object, and once you have the type (which is
3184usually implicit in where you find the object), you can use
3185
3186-------------------------------------------------
3187$ git-cat-file blob|tree|commit|tag <objectname>
3188-------------------------------------------------
3189
3190to show its contents. NOTE! Trees have binary content, and as a result
3191there is a special helper for showing that content, called
3192`git-ls-tree`, which turns the binary content into a more easily
3193readable form.
3194
3195It's especially instructive to look at "commit" objects, since those
3196tend to be small and fairly self-explanatory. In particular, if you
3197follow the convention of having the top commit name in `.git/HEAD`,
3198you can do
3199
3200-------------------------------------------------
3201$ git-cat-file commit HEAD
3202-------------------------------------------------
3203
3204to see what the top commit was.
3205
e34caace 3206[[merging-multiple-trees]]
b181d57f 3207Merging multiple trees
d19fbc3c
BF
3208----------------------
3209
b181d57f
BF
3210Git helps you do a three-way merge, which you can expand to n-way by
3211repeating the merge procedure arbitrary times until you finally
3212"commit" the state. The normal situation is that you'd only do one
3213three-way merge (two parents), and commit it, but if you like to, you
3214can do multiple parents in one go.
3215
3216To do a three-way merge, you need the two sets of "commit" objects
3217that you want to merge, use those to find the closest common parent (a
3218third "commit" object), and then use those commit objects to find the
3219state of the directory ("tree" object) at these points.
3220
3221To get the "base" for the merge, you first look up the common parent
3222of two commits with
3223
3224-------------------------------------------------
3225$ git-merge-base <commit1> <commit2>
3226-------------------------------------------------
3227
3228which will return you the commit they are both based on. You should
3229now look up the "tree" objects of those commits, which you can easily
3230do with (for example)
3231
3232-------------------------------------------------
3233$ git-cat-file commit <commitname> | head -1
3234-------------------------------------------------
3235
3236since the tree object information is always the first line in a commit
3237object.
3238
1191ee18 3239Once you know the three trees you are going to merge (the one "original"
c64415e2 3240tree, aka the common tree, and the two "result" trees, aka the branches
1191ee18
BF
3241you want to merge), you do a "merge" read into the index. This will
3242complain if it has to throw away your old index contents, so you should
b181d57f 3243make sure that you've committed those - in fact you would normally
1191ee18
BF
3244always do a merge against your last commit (which should thus match what
3245you have in your current index anyway).
b181d57f
BF
3246
3247To do the merge, do
3248
3249-------------------------------------------------
3250$ git-read-tree -m -u <origtree> <yourtree> <targettree>
3251-------------------------------------------------
3252
3253which will do all trivial merge operations for you directly in the
3254index file, and you can just write the result out with
3255`git-write-tree`.
3256
3257
e34caace 3258[[merging-multiple-trees-2]]
b181d57f
BF
3259Merging multiple trees, continued
3260---------------------------------
3261
3262Sadly, many merges aren't trivial. If there are files that have
3263been added.moved or removed, or if both branches have modified the
3264same file, you will be left with an index tree that contains "merge
3265entries" in it. Such an index tree can 'NOT' be written out to a tree
3266object, and you will have to resolve any such merge clashes using
3267other tools before you can write out the result.
3268
3269You can examine such index state with `git-ls-files --unmerged`
3270command. An example:
3271
3272------------------------------------------------
3273$ git-read-tree -m $orig HEAD $target
3274$ git-ls-files --unmerged
3275100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
3276100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
3277100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
3278------------------------------------------------
3279
3280Each line of the `git-ls-files --unmerged` output begins with
3281the blob mode bits, blob SHA1, 'stage number', and the
3282filename. The 'stage number' is git's way to say which tree it
3283came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`
3284tree, and stage3 `$target` tree.
3285
3286Earlier we said that trivial merges are done inside
3287`git-read-tree -m`. For example, if the file did not change
3288from `$orig` to `HEAD` nor `$target`, or if the file changed
3289from `$orig` to `HEAD` and `$orig` to `$target` the same way,
3290obviously the final outcome is what is in `HEAD`. What the
3291above example shows is that file `hello.c` was changed from
3292`$orig` to `HEAD` and `$orig` to `$target` in a different way.
3293You could resolve this by running your favorite 3-way merge
c64415e2
BF
3294program, e.g. `diff3`, `merge`, or git's own merge-file, on
3295the blob objects from these three stages yourself, like this:
b181d57f
BF
3296
3297------------------------------------------------
3298$ git-cat-file blob 263414f... >hello.c~1
3299$ git-cat-file blob 06fa6a2... >hello.c~2
3300$ git-cat-file blob cc44c73... >hello.c~3
c64415e2 3301$ git merge-file hello.c~2 hello.c~1 hello.c~3
b181d57f
BF
3302------------------------------------------------
3303
3304This would leave the merge result in `hello.c~2` file, along
3305with conflict markers if there are conflicts. After verifying
3306the merge result makes sense, you can tell git what the final
3307merge result for this file is by:
3308
3309-------------------------------------------------
3310$ mv -f hello.c~2 hello.c
3311$ git-update-index hello.c
3312-------------------------------------------------
3313
3314When a path is in unmerged state, running `git-update-index` for
3315that path tells git to mark the path resolved.
3316
3317The above is the description of a git merge at the lowest level,
3318to help you understand what conceptually happens under the hood.
3319In practice, nobody, not even git itself, uses three `git-cat-file`
3320for this. There is `git-merge-index` program that extracts the
3321stages to temporary files and calls a "merge" script on it:
3322
3323-------------------------------------------------
3324$ git-merge-index git-merge-one-file hello.c
3325-------------------------------------------------
3326
207dfa07 3327and that is what higher level `git merge -s resolve` is implemented with.
b181d57f 3328
e34caace 3329[[pack-files]]
b181d57f
BF
3330How git stores objects efficiently: pack files
3331----------------------------------------------
3332
3333We've seen how git stores each object in a file named after the
3334object's SHA1 hash.
3335
3336Unfortunately this system becomes inefficient once a project has a
3337lot of objects. Try this on an old project:
3338
3339------------------------------------------------
3340$ git count-objects
33416930 objects, 47620 kilobytes
3342------------------------------------------------
3343
3344The first number is the number of objects which are kept in
3345individual files. The second is the amount of space taken up by
3346those "loose" objects.
3347
3348You can save space and make git faster by moving these loose objects in
3349to a "pack file", which stores a group of objects in an efficient
3350compressed format; the details of how pack files are formatted can be
3351found in link:technical/pack-format.txt[technical/pack-format.txt].
3352
3353To put the loose objects into a pack, just run git repack:
3354
3355------------------------------------------------
3356$ git repack
3357Generating pack...
3358Done counting 6020 objects.
3359Deltifying 6020 objects.
3360 100% (6020/6020) done
3361Writing 6020 objects.
3362 100% (6020/6020) done
3363Total 6020, written 6020 (delta 4070), reused 0 (delta 0)
3364Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created.
3365------------------------------------------------
3366
3367You can then run
3368
3369------------------------------------------------
3370$ git prune
3371------------------------------------------------
3372
3373to remove any of the "loose" objects that are now contained in the
3374pack. This will also remove any unreferenced objects (which may be
3375created when, for example, you use "git reset" to remove a commit).
3376You can verify that the loose objects are gone by looking at the
3377.git/objects directory or by running
3378
3379------------------------------------------------
3380$ git count-objects
33810 objects, 0 kilobytes
3382------------------------------------------------
3383
3384Although the object files are gone, any commands that refer to those
3385objects will work exactly as they did before.
3386
3387The gitlink:git-gc[1] command performs packing, pruning, and more for
3388you, so is normally the only high-level command you need.
d19fbc3c 3389
59723040 3390[[dangling-objects]]
21dcb3b7 3391Dangling objects
61b41790 3392----------------
21dcb3b7 3393
04e50e94 3394The gitlink:git-fsck[1] command will sometimes complain about dangling
21dcb3b7
BF
3395objects. They are not a problem.
3396
1191ee18
BF
3397The most common cause of dangling objects is that you've rebased a
3398branch, or you have pulled from somebody else who rebased a branch--see
3399<<cleaning-up-history>>. In that case, the old head of the original
59723040
BF
3400branch still exists, as does everything it pointed to. The branch
3401pointer itself just doesn't, since you replaced it with another one.
1191ee18 3402
59723040 3403There are also other situations that cause dangling objects. For
1191ee18
BF
3404example, a "dangling blob" may arise because you did a "git add" of a
3405file, but then, before you actually committed it and made it part of the
3406bigger picture, you changed something else in that file and committed
3407that *updated* thing - the old state that you added originally ends up
3408not being pointed to by any commit or tree, so it's now a dangling blob
3409object.
3410
3411Similarly, when the "recursive" merge strategy runs, and finds that
3412there are criss-cross merges and thus more than one merge base (which is
3413fairly unusual, but it does happen), it will generate one temporary
3414midway tree (or possibly even more, if you had lots of criss-crossing
3415merges and more than two merge bases) as a temporary internal merge
3416base, and again, those are real objects, but the end result will not end
3417up pointing to them, so they end up "dangling" in your repository.
3418
3419Generally, dangling objects aren't anything to worry about. They can
3420even be very useful: if you screw something up, the dangling objects can
3421be how you recover your old tree (say, you did a rebase, and realized
3422that you really didn't want to - you can look at what dangling objects
3423you have, and decide to reset your head to some old dangling state).
21dcb3b7 3424
59723040 3425For commits, you can just use:
21dcb3b7
BF
3426
3427------------------------------------------------
3428$ gitk <dangling-commit-sha-goes-here> --not --all
3429------------------------------------------------
3430
59723040
BF
3431This asks for all the history reachable from the given commit but not
3432from any branch, tag, or other reference. If you decide it's something
3433you want, you can always create a new reference to it, e.g.,
3434
3435------------------------------------------------
3436$ git branch recovered-branch <dangling-commit-sha-goes-here>
3437------------------------------------------------
3438
3439For blobs and trees, you can't do the same, but you can still examine
3440them. You can just do
21dcb3b7
BF
3441
3442------------------------------------------------
3443$ git show <dangling-blob/tree-sha-goes-here>
3444------------------------------------------------
3445
1191ee18
BF
3446to show what the contents of the blob were (or, for a tree, basically
3447what the "ls" for that directory was), and that may give you some idea
3448of what the operation was that left that dangling object.
21dcb3b7 3449
1191ee18
BF
3450Usually, dangling blobs and trees aren't very interesting. They're
3451almost always the result of either being a half-way mergebase (the blob
3452will often even have the conflict markers from a merge in it, if you
3453have had conflicting merges that you fixed up by hand), or simply
3454because you interrupted a "git fetch" with ^C or something like that,
3455leaving _some_ of the new objects in the object database, but just
3456dangling and useless.
21dcb3b7 3457
a6080a0a 3458Anyway, once you are sure that you're not interested in any dangling
21dcb3b7
BF
3459state, you can just prune all unreachable objects:
3460
3461------------------------------------------------
3462$ git prune
3463------------------------------------------------
3464
1191ee18
BF
3465and they'll be gone. But you should only run "git prune" on a quiescent
3466repository - it's kind of like doing a filesystem fsck recovery: you
3467don't want to do that while the filesystem is mounted.
21dcb3b7 3468
a6080a0a
JH
3469(The same is true of "git-fsck" itself, btw - but since
3470git-fsck never actually *changes* the repository, it just reports
3471on what it found, git-fsck itself is never "dangerous" to run.
3472Running it while somebody is actually changing the repository can cause
3473confusing and scary messages, but it won't actually do anything bad. In
3474contrast, running "git prune" while somebody is actively changing the
21dcb3b7
BF
3475repository is a *BAD* idea).
3476
126640af 3477[[birdview-on-the-source-code]]
a5fc33b4
BF
3478A birds-eye view of Git's source code
3479-------------------------------------
126640af 3480
a5fc33b4
BF
3481It is not always easy for new developers to find their way through Git's
3482source code. This section gives you a little guidance to show where to
3483start.
126640af 3484
a5fc33b4 3485A good place to start is with the contents of the initial commit, with:
126640af
JS
3486
3487----------------------------------------------------
a5fc33b4 3488$ git checkout e83c5163
126640af
JS
3489----------------------------------------------------
3490
a5fc33b4
BF
3491The initial revision lays the foundation for almost everything git has
3492today, but is small enough to read in one sitting.
126640af 3493
a5fc33b4
BF
3494Note that terminology has changed since that revision. For example, the
3495README in that revision uses the word "changeset" to describe what we
3496now call a <<def_commit_object,commit>>.
126640af 3497
a5fc33b4 3498Also, we do not call it "cache" any more, but "index", however, the
126640af
JS
3499file is still called `cache.h`. Remark: Not much reason to change it now,
3500especially since there is no good single name for it anyway, because it is
3501basically _the_ header file which is included by _all_ of Git's C sources.
3502
a5fc33b4
BF
3503If you grasp the ideas in that initial commit, you should check out a
3504more recent version and skim `cache.h`, `object.h` and `commit.h`.
126640af
JS
3505
3506In the early days, Git (in the tradition of UNIX) was a bunch of programs
3507which were extremely simple, and which you used in scripts, piping the
3508output of one into another. This turned out to be good for initial
3509development, since it was easier to test new things. However, recently
3510many of these parts have become builtins, and some of the core has been
3511"libified", i.e. put into libgit.a for performance, portability reasons,
3512and to avoid code duplication.
3513
3514By now, you know what the index is (and find the corresponding data
3515structures in `cache.h`), and that there are just a couple of object types
3516(blobs, trees, commits and tags) which inherit their common structure from
3517`struct object`, which is their first member (and thus, you can cast e.g.
3518`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e.
3519get at the object name and flags).
3520
3521Now is a good point to take a break to let this information sink in.
3522
3523Next step: get familiar with the object naming. Read <<naming-commits>>.
3524There are quite a few ways to name an object (and not only revisions!).
3525All of these are handled in `sha1_name.c`. Just have a quick look at
3526the function `get_sha1()`. A lot of the special handling is done by
3527functions like `get_sha1_basic()` or the likes.
3528
3529This is just to get you into the groove for the most libified part of Git: