user-manual: introduce git
[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.
ef89f701 29
2624d9a5
BF
30Also, see <<todo>> for ways that you can help make this manual more
31complete.
ef89f701 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.
157
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).
161
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:
170
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
452the contents of a file heirarchy, together with "commits" which show
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
82c8bf28
BF
833[[making-a-release]]
834Creating a changelog and tarball for a software release
835~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
836
837The gitlink:git-archive[1] command can create a tar or zip archive from
838any version of a project; for example:
839
840-------------------------------------------------
841$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
842-------------------------------------------------
843
844will use HEAD to produce a tar archive in which each filename is
845preceded by "prefix/".
846
847If you're releasing a new version of a software project, you may want
848to simultaneously make a changelog to include in the release
849announcement.
850
851Linus Torvalds, for example, makes new kernel releases by tagging them,
852then running:
853
854-------------------------------------------------
855$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
856-------------------------------------------------
857
858where release-script is a shell script that looks like:
859
860-------------------------------------------------
861#!/bin/sh
862stable="$1"
863last="$2"
864new="$3"
865echo "# git tag v$new"
866echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
867echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
868echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
869echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
870echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
871-------------------------------------------------
872
873and then he just cut-and-pastes the output commands after verifying that
874they look OK.
4a7979ca 875
e34caace 876[[Developing-with-git]]
d19fbc3c
BF
877Developing with git
878===================
879
e34caace 880[[telling-git-your-name]]
d19fbc3c
BF
881Telling git your name
882---------------------
883
884Before creating any commits, you should introduce yourself to git. The
58c19d1f
BF
885easiest way to do so is to make sure the following lines appear in a
886file named .gitconfig in your home directory:
d19fbc3c
BF
887
888------------------------------------------------
d19fbc3c
BF
889[user]
890 name = Your Name Comes Here
891 email = you@yourdomain.example.com
d19fbc3c
BF
892------------------------------------------------
893
fc90c536
BF
894(See the "CONFIGURATION FILE" section of gitlink:git-config[1] for
895details on the configuration file.)
896
d19fbc3c 897
e34caace 898[[creating-a-new-repository]]
d19fbc3c
BF
899Creating a new repository
900-------------------------
901
902Creating a new repository from scratch is very easy:
903
904-------------------------------------------------
905$ mkdir project
906$ cd project
f1d2b477 907$ git init
d19fbc3c
BF
908-------------------------------------------------
909
910If you have some initial content (say, a tarball):
911
912-------------------------------------------------
913$ tar -xzvf project.tar.gz
914$ cd project
f1d2b477 915$ git init
d19fbc3c
BF
916$ git add . # include everything below ./ in the first commit:
917$ git commit
918-------------------------------------------------
919
920[[how-to-make-a-commit]]
ae25c67a 921How to make a commit
d19fbc3c
BF
922--------------------
923
924Creating a new commit takes three steps:
925
926 1. Making some changes to the working directory using your
927 favorite editor.
928 2. Telling git about your changes.
929 3. Creating the commit using the content you told git about
930 in step 2.
931
932In practice, you can interleave and repeat steps 1 and 2 as many
933times as you want: in order to keep track of what you want committed
934at step 3, git maintains a snapshot of the tree's contents in a
935special staging area called "the index."
936
01997b4a
BF
937At the beginning, the content of the index will be identical to
938that of the HEAD. The command "git diff --cached", which shows
939the difference between the HEAD and the index, should therefore
940produce no output at that point.
eb6ae7f4 941
d19fbc3c
BF
942Modifying the index is easy:
943
944To update the index with the new contents of a modified file, use
945
946-------------------------------------------------
947$ git add path/to/file
948-------------------------------------------------
949
950To add the contents of a new file to the index, use
951
952-------------------------------------------------
953$ git add path/to/file
954-------------------------------------------------
955
eb6ae7f4 956To remove a file from the index and from the working tree,
d19fbc3c
BF
957
958-------------------------------------------------
959$ git rm path/to/file
960-------------------------------------------------
961
962After each step you can verify that
963
964-------------------------------------------------
965$ git diff --cached
966-------------------------------------------------
967
968always shows the difference between the HEAD and the index file--this
969is what you'd commit if you created the commit now--and that
970
971-------------------------------------------------
972$ git diff
973-------------------------------------------------
974
975shows the difference between the working tree and the index file.
976
977Note that "git add" always adds just the current contents of a file
978to the index; further changes to the same file will be ignored unless
979you run git-add on the file again.
980
981When you're ready, just run
982
983-------------------------------------------------
984$ git commit
985-------------------------------------------------
986
987and git will prompt you for a commit message and then create the new
3dff5379 988commit. Check to make sure it looks like what you expected with
d19fbc3c
BF
989
990-------------------------------------------------
991$ git show
992-------------------------------------------------
993
994As a special shortcut,
995
996-------------------------------------------------
997$ git commit -a
998-------------------------------------------------
999
1000will update the index with any files that you've modified or removed
1001and create a commit, all in one step.
1002
1003A number of commands are useful for keeping track of what you're
1004about to commit:
1005
1006-------------------------------------------------
1007$ git diff --cached # difference between HEAD and the index; what
1008 # would be commited if you ran "commit" now.
1009$ git diff # difference between the index file and your
1010 # working directory; changes that would not
1011 # be included if you ran "commit" now.
c64415e2
BF
1012$ git diff HEAD # difference between HEAD and working tree; what
1013 # would be committed if you ran "commit -a" now.
d19fbc3c
BF
1014$ git status # a brief per-file summary of the above.
1015-------------------------------------------------
1016
e34caace 1017[[creating-good-commit-messages]]
ae25c67a 1018Creating good commit messages
d19fbc3c
BF
1019-----------------------------
1020
1021Though not required, it's a good idea to begin the commit message
1022with a single short (less than 50 character) line summarizing the
1023change, followed by a blank line and then a more thorough
1024description. Tools that turn commits into email, for example, use
1025the first line on the Subject line and the rest of the commit in the
1026body.
1027
e34caace 1028[[how-to-merge]]
ae25c67a 1029How to merge
d19fbc3c
BF
1030------------
1031
1032You can rejoin two diverging branches of development using
1033gitlink:git-merge[1]:
1034
1035-------------------------------------------------
1036$ git merge branchname
1037-------------------------------------------------
1038
1039merges the development in the branch "branchname" into the current
1040branch. If there are conflicts--for example, if the same file is
1041modified in two different ways in the remote branch and the local
1042branch--then you are warned; the output may look something like this:
1043
1044-------------------------------------------------
fabbd8f6
BF
1045$ git merge next
1046 100% (4/4) done
1047Auto-merged file.txt
d19fbc3c
BF
1048CONFLICT (content): Merge conflict in file.txt
1049Automatic merge failed; fix conflicts and then commit the result.
1050-------------------------------------------------
1051
1052Conflict markers are left in the problematic files, and after
1053you resolve the conflicts manually, you can update the index
1054with the contents and run git commit, as you normally would when
1055creating a new file.
1056
1057If you examine the resulting commit using gitk, you will see that it
1058has two parents, one pointing to the top of the current branch, and
1059one to the top of the other branch.
1060
d19fbc3c
BF
1061[[resolving-a-merge]]
1062Resolving a merge
1063-----------------
1064
1065When a merge isn't resolved automatically, git leaves the index and
1066the working tree in a special state that gives you all the
1067information you need to help resolve the merge.
1068
1069Files with conflicts are marked specially in the index, so until you
ef561ac7
BF
1070resolve the problem and update the index, gitlink:git-commit[1] will
1071fail:
d19fbc3c
BF
1072
1073-------------------------------------------------
1074$ git commit
1075file.txt: needs merge
1076-------------------------------------------------
1077
ef561ac7
BF
1078Also, gitlink:git-status[1] will list those files as "unmerged", and the
1079files with conflicts will have conflict markers added, like this:
1080
1081-------------------------------------------------
1082<<<<<<< HEAD:file.txt
1083Hello world
1084=======
1085Goodbye
1086>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1087-------------------------------------------------
1088
1089All you need to do is edit the files to resolve the conflicts, and then
1090
1091-------------------------------------------------
1092$ git add file.txt
1093$ git commit
1094-------------------------------------------------
1095
1096Note that the commit message will already be filled in for you with
1097some information about the merge. Normally you can just use this
1098default message unchanged, but you may add additional commentary of
1099your own if desired.
1100
1101The above is all you need to know to resolve a simple merge. But git
1102also provides more information to help resolve conflicts:
1103
e34caace 1104[[conflict-resolution]]
ef561ac7
BF
1105Getting conflict-resolution help during a merge
1106~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
d19fbc3c
BF
1107
1108All of the changes that git was able to merge automatically are
1109already added to the index file, so gitlink:git-diff[1] shows only
ef561ac7 1110the conflicts. It uses an unusual syntax:
d19fbc3c
BF
1111
1112-------------------------------------------------
1113$ git diff
1114diff --cc file.txt
1115index 802992c,2b60207..0000000
1116--- a/file.txt
1117+++ b/file.txt
1118@@@ -1,1 -1,1 +1,5 @@@
1119++<<<<<<< HEAD:file.txt
1120 +Hello world
1121++=======
1122+ Goodbye
1123++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1124-------------------------------------------------
1125
1126Recall that the commit which will be commited after we resolve this
1127conflict will have two parents instead of the usual one: one parent
1128will be HEAD, the tip of the current branch; the other will be the
1129tip of the other branch, which is stored temporarily in MERGE_HEAD.
1130
ef561ac7
BF
1131During the merge, the index holds three versions of each file. Each of
1132these three "file stages" represents a different version of the file:
1133
1134-------------------------------------------------
1135$ git show :1:file.txt # the file in a common ancestor of both branches
1136$ git show :2:file.txt # the version from HEAD, but including any
1137 # nonconflicting changes from MERGE_HEAD
1138$ git show :3:file.txt # the version from MERGE_HEAD, but including any
1139 # nonconflicting changes from HEAD.
1140-------------------------------------------------
1141
1142Since the stage 2 and stage 3 versions have already been updated with
1143nonconflicting changes, the only remaining differences between them are
1144the important ones; thus gitlink:git-diff[1] can use the information in
1145the index to show only those conflicts.
1146
1147The diff above shows the differences between the working-tree version of
1148file.txt and the stage 2 and stage 3 versions. So instead of preceding
1149each line by a single "+" or "-", it now uses two columns: the first
1150column is used for differences between the first parent and the working
1151directory copy, and the second for differences between the second parent
1152and the working directory copy. (See the "COMBINED DIFF FORMAT" section
1153of gitlink:git-diff-files[1] for a details of the format.)
1154
1155After resolving the conflict in the obvious way (but before updating the
1156index), the diff will look like:
d19fbc3c
BF
1157
1158-------------------------------------------------
1159$ git diff
1160diff --cc file.txt
1161index 802992c,2b60207..0000000
1162--- a/file.txt
1163+++ b/file.txt
1164@@@ -1,1 -1,1 +1,1 @@@
1165- Hello world
1166 -Goodbye
1167++Goodbye world
1168-------------------------------------------------
1169
1170This shows that our resolved version deleted "Hello world" from the
1171first parent, deleted "Goodbye" from the second parent, and added
1172"Goodbye world", which was previously absent from both.
1173
ef561ac7
BF
1174Some special diff options allow diffing the working directory against
1175any of these stages:
1176
1177-------------------------------------------------
1178$ git diff -1 file.txt # diff against stage 1
1179$ git diff --base file.txt # same as the above
1180$ git diff -2 file.txt # diff against stage 2
1181$ git diff --ours file.txt # same as the above
1182$ git diff -3 file.txt # diff against stage 3
1183$ git diff --theirs file.txt # same as the above.
1184-------------------------------------------------
1185
1186The gitlink:git-log[1] and gitk[1] commands also provide special help
1187for merges:
d19fbc3c
BF
1188
1189-------------------------------------------------
1190$ git log --merge
ef561ac7 1191$ gitk --merge
d19fbc3c
BF
1192-------------------------------------------------
1193
ef561ac7
BF
1194These will display all commits which exist only on HEAD or on
1195MERGE_HEAD, and which touch an unmerged file.
d19fbc3c 1196
61d72564 1197You may also use gitlink:git-mergetool[1], which lets you merge the
c64415e2
BF
1198unmerged files using external tools such as emacs or kdiff3.
1199
ef561ac7 1200Each time you resolve the conflicts in a file and update the index:
d19fbc3c
BF
1201
1202-------------------------------------------------
1203$ git add file.txt
d19fbc3c
BF
1204-------------------------------------------------
1205
ef561ac7
BF
1206the different stages of that file will be "collapsed", after which
1207git-diff will (by default) no longer show diffs for that file.
d19fbc3c
BF
1208
1209[[undoing-a-merge]]
ae25c67a 1210Undoing a merge
d19fbc3c
BF
1211---------------
1212
1213If you get stuck and decide to just give up and throw the whole mess
1214away, you can always return to the pre-merge state with
1215
1216-------------------------------------------------
1217$ git reset --hard HEAD
1218-------------------------------------------------
1219
1220Or, if you've already commited the merge that you want to throw away,
1221
1222-------------------------------------------------
1c73bb0e 1223$ git reset --hard ORIG_HEAD
d19fbc3c
BF
1224-------------------------------------------------
1225
1226However, this last command can be dangerous in some cases--never
1227throw away a commit you have already committed if that commit may
1228itself have been merged into another branch, as doing so may confuse
1229further merges.
1230
e34caace 1231[[fast-forwards]]
d19fbc3c
BF
1232Fast-forward merges
1233-------------------
1234
1235There is one special case not mentioned above, which is treated
1236differently. Normally, a merge results in a merge commit, with two
1237parents, one pointing at each of the two lines of development that
1238were merged.
1239
59723040
BF
1240However, if the current branch is a descendant of the other--so every
1241commit present in the one is already contained in the other--then git
1242just performs a "fast forward"; the head of the current branch is moved
1243forward to point at the head of the merged-in branch, without any new
1244commits being created.
d19fbc3c 1245
e34caace 1246[[fixing-mistakes]]
b684f830
BF
1247Fixing mistakes
1248---------------
1249
1250If you've messed up the working tree, but haven't yet committed your
1251mistake, you can return the entire working tree to the last committed
1252state with
1253
1254-------------------------------------------------
1255$ git reset --hard HEAD
1256-------------------------------------------------
1257
1258If you make a commit that you later wish you hadn't, there are two
1259fundamentally different ways to fix the problem:
1260
1261 1. You can create a new commit that undoes whatever was done
1262 by the previous commit. This is the correct thing if your
1263 mistake has already been made public.
1264
1265 2. You can go back and modify the old commit. You should
1266 never do this if you have already made the history public;
1267 git does not normally expect the "history" of a project to
1268 change, and cannot correctly perform repeated merges from
1269 a branch that has had its history changed.
1270
e34caace 1271[[reverting-a-commit]]
b684f830
BF
1272Fixing a mistake with a new commit
1273~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1274
1275Creating a new commit that reverts an earlier change is very easy;
1276just pass the gitlink:git-revert[1] command a reference to the bad
1277commit; for example, to revert the most recent commit:
1278
1279-------------------------------------------------
1280$ git revert HEAD
1281-------------------------------------------------
1282
1283This will create a new commit which undoes the change in HEAD. You
1284will be given a chance to edit the commit message for the new commit.
1285
1286You can also revert an earlier change, for example, the next-to-last:
1287
1288-------------------------------------------------
1289$ git revert HEAD^
1290-------------------------------------------------
1291
1292In this case git will attempt to undo the old change while leaving
1293intact any changes made since then. If more recent changes overlap
1294with the changes to be reverted, then you will be asked to fix
1295conflicts manually, just as in the case of <<resolving-a-merge,
1296resolving a merge>>.
1297
365aa199 1298[[fixing-a-mistake-by-editing-history]]
b684f830
BF
1299Fixing a mistake by editing history
1300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1301
1302If the problematic commit is the most recent commit, and you have not
1303yet made that commit public, then you may just
1304<<undoing-a-merge,destroy it using git-reset>>.
1305
1306Alternatively, you
1307can edit the working directory and update the index to fix your
1308mistake, just as if you were going to <<how-to-make-a-commit,create a
1309new commit>>, then run
1310
1311-------------------------------------------------
1312$ git commit --amend
1313-------------------------------------------------
1314
1315which will replace the old commit by a new commit incorporating your
1316changes, giving you a chance to edit the old commit message first.
1317
1318Again, you should never do this to a commit that may already have
1319been merged into another branch; use gitlink:git-revert[1] instead in
1320that case.
1321
1322It is also possible to edit commits further back in the history, but
1323this is an advanced topic to be left for
1324<<cleaning-up-history,another chapter>>.
1325
e34caace 1326[[checkout-of-path]]
b684f830
BF
1327Checking out an old version of a file
1328~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1329
1330In the process of undoing a previous bad change, you may find it
1331useful to check out an older version of a particular file using
1332gitlink:git-checkout[1]. We've used git checkout before to switch
1333branches, but it has quite different behavior if it is given a path
1334name: the command
1335
1336-------------------------------------------------
1337$ git checkout HEAD^ path/to/file
1338-------------------------------------------------
1339
1340replaces path/to/file by the contents it had in the commit HEAD^, and
1341also updates the index to match. It does not change branches.
1342
1343If you just want to look at an old version of the file, without
1344modifying the working directory, you can do that with
1345gitlink:git-show[1]:
1346
1347-------------------------------------------------
ed4eb0d8 1348$ git show HEAD^:path/to/file
b684f830
BF
1349-------------------------------------------------
1350
1351which will display the given version of the file.
1352
e34caace 1353[[ensuring-good-performance]]
d19fbc3c
BF
1354Ensuring good performance
1355-------------------------
1356
1357On large repositories, git depends on compression to keep the history
1358information from taking up to much space on disk or in memory.
1359
1360This compression is not performed automatically. Therefore you
17217090 1361should occasionally run gitlink:git-gc[1]:
d19fbc3c
BF
1362
1363-------------------------------------------------
1364$ git gc
1365-------------------------------------------------
1366
17217090
BF
1367to recompress the archive. This can be very time-consuming, so
1368you may prefer to run git-gc when you are not doing other work.
d19fbc3c 1369
e34caace
BF
1370
1371[[ensuring-reliability]]
11e016a3
BF
1372Ensuring reliability
1373--------------------
1374
e34caace 1375[[checking-for-corruption]]
11e016a3
BF
1376Checking the repository for corruption
1377~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1378
1191ee18
BF
1379The gitlink:git-fsck[1] command runs a number of self-consistency checks
1380on the repository, and reports on any problems. This may take some
21dcb3b7
BF
1381time. The most common warning by far is about "dangling" objects:
1382
1383-------------------------------------------------
04e50e94 1384$ git fsck
21dcb3b7
BF
1385dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1386dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1387dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1388dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
1389dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
1390dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
1391dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
1392dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1393...
1394-------------------------------------------------
1395
59723040
BF
1396Dangling objects are not a problem. At worst they may take up a little
1397extra disk space. They can sometimes provide a last-resort method of
1398recovery lost work--see <<dangling-objects>> for details. However, if
1399you want, you may remove them with gitlink:git-prune[1] or the --prune
1191ee18 1400option to gitlink:git-gc[1]:
21dcb3b7
BF
1401
1402-------------------------------------------------
1403$ git gc --prune
1404-------------------------------------------------
1405
1191ee18
BF
1406This may be time-consuming. Unlike most other git operations (including
1407git-gc when run without any options), it is not safe to prune while
1408other git operations are in progress in the same repository.
21dcb3b7 1409
e34caace 1410[[recovering-lost-changes]]
11e016a3
BF
1411Recovering lost changes
1412~~~~~~~~~~~~~~~~~~~~~~~
1413
e34caace 1414[[reflogs]]
559e4d7a
BF
1415Reflogs
1416^^^^^^^
1417
1418Say you modify a branch with gitlink:git-reset[1] --hard, and then
1419realize that the branch was the only reference you had to that point in
1420history.
1421
1422Fortunately, git also keeps a log, called a "reflog", of all the
1423previous values of each branch. So in this case you can still find the
1424old history using, for example,
1425
1426-------------------------------------------------
1427$ git log master@{1}
1428-------------------------------------------------
1429
1430This lists the commits reachable from the previous version of the head.
1431This syntax can be used to with any git command that accepts a commit,
1432not just with git log. Some other examples:
1433
1434-------------------------------------------------
1435$ git show master@{2} # See where the branch pointed 2,
1436$ git show master@{3} # 3, ... changes ago.
1437$ gitk master@{yesterday} # See where it pointed yesterday,
1438$ gitk master@{"1 week ago"} # ... or last week
953f3d6f
BF
1439$ git log --walk-reflogs master # show reflog entries for master
1440-------------------------------------------------
1441
1442A separate reflog is kept for the HEAD, so
1443
1444-------------------------------------------------
1445$ git show HEAD@{"1 week ago"}
559e4d7a
BF
1446-------------------------------------------------
1447
953f3d6f
BF
1448will show what HEAD pointed to one week ago, not what the current branch
1449pointed to one week ago. This allows you to see the history of what
1450you've checked out.
1451
559e4d7a 1452The reflogs are kept by default for 30 days, after which they may be
036be17e 1453pruned. See gitlink:git-reflog[1] and gitlink:git-gc[1] to learn
559e4d7a
BF
1454how to control this pruning, and see the "SPECIFYING REVISIONS"
1455section of gitlink:git-rev-parse[1] for details.
1456
1457Note that the reflog history is very different from normal git history.
1458While normal history is shared by every repository that works on the
1459same project, the reflog history is not shared: it tells you only about
1460how the branches in your local repository have changed over time.
1461
59723040 1462[[dangling-object-recovery]]
559e4d7a
BF
1463Examining dangling objects
1464^^^^^^^^^^^^^^^^^^^^^^^^^^
1465
59723040
BF
1466In some situations the reflog may not be able to save you. For example,
1467suppose you delete a branch, then realize you need the history it
1468contained. The reflog is also deleted; however, if you have not yet
1469pruned the repository, then you may still be able to find the lost
1470commits in the dangling objects that git-fsck reports. See
1471<<dangling-objects>> for the details.
559e4d7a
BF
1472
1473-------------------------------------------------
1474$ git fsck
1475dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1476dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1477dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1478...
1479-------------------------------------------------
1480
aacd404e 1481You can examine
559e4d7a
BF
1482one of those dangling commits with, for example,
1483
1484------------------------------------------------
1485$ gitk 7281251ddd --not --all
1486------------------------------------------------
1487
1488which does what it sounds like: it says that you want to see the commit
1489history that is described by the dangling commit(s), but not the
1490history that is described by all your existing branches and tags. Thus
1491you get exactly the history reachable from that commit that is lost.
1492(And notice that it might not be just one commit: we only report the
1493"tip of the line" as being dangling, but there might be a whole deep
79c96c57 1494and complex commit history that was dropped.)
559e4d7a
BF
1495
1496If you decide you want the history back, you can always create a new
1497reference pointing to it, for example, a new branch:
1498
1499------------------------------------------------
1500$ git branch recovered-branch 7281251ddd
1501------------------------------------------------
1502
59723040
BF
1503Other types of dangling objects (blobs and trees) are also possible, and
1504dangling objects can arise in other situations.
1505
11e016a3 1506
e34caace 1507[[sharing-development]]
d19fbc3c 1508Sharing development with others
b684f830 1509===============================
d19fbc3c
BF
1510
1511[[getting-updates-with-git-pull]]
1512Getting updates with git pull
b684f830 1513-----------------------------
d19fbc3c
BF
1514
1515After you clone a repository and make a few changes of your own, you
1516may wish to check the original repository for updates and merge them
1517into your own work.
1518
1519We have already seen <<Updating-a-repository-with-git-fetch,how to
1520keep remote tracking branches up to date>> with gitlink:git-fetch[1],
1521and how to merge two branches. So you can merge in changes from the
1522original repository's master branch with:
1523
1524-------------------------------------------------
1525$ git fetch
1526$ git merge origin/master
1527-------------------------------------------------
1528
1529However, the gitlink:git-pull[1] command provides a way to do this in
1530one step:
1531
1532-------------------------------------------------
1533$ git pull origin master
1534-------------------------------------------------
1535
1536In fact, "origin" is normally the default repository to pull from,
1537and the default branch is normally the HEAD of the remote repository,
1538so often you can accomplish the above with just
1539
1540-------------------------------------------------
1541$ git pull
1542-------------------------------------------------
1543
c64415e2
BF
1544See the descriptions of the branch.<name>.remote and branch.<name>.merge
1545options in gitlink:git-config[1] to learn how to control these defaults
1546depending on the current branch. Also note that the --track option to
1547gitlink:git-branch[1] and gitlink:git-checkout[1] can be used to
1548automatically set the default remote branch to pull from at the time
1549that a branch is created:
1550
1551-------------------------------------------------
1552$ git checkout --track -b origin/maint maint
1553-------------------------------------------------
d19fbc3c
BF
1554
1555In addition to saving you keystrokes, "git pull" also helps you by
1556producing a default commit message documenting the branch and
1557repository that you pulled from.
1558
1559(But note that no such commit will be created in the case of a
1560<<fast-forwards,fast forward>>; instead, your branch will just be
79c96c57 1561updated to point to the latest commit from the upstream branch.)
d19fbc3c 1562
1191ee18
BF
1563The git-pull command can also be given "." as the "remote" repository,
1564in which case it just merges in a branch from the current repository; so
4c63ff45
BF
1565the commands
1566
1567-------------------------------------------------
1568$ git pull . branch
1569$ git merge branch
1570-------------------------------------------------
1571
1572are roughly equivalent. The former is actually very commonly used.
1573
e34caace 1574[[submitting-patches]]
d19fbc3c 1575Submitting patches to a project
b684f830 1576-------------------------------
d19fbc3c
BF
1577
1578If you just have a few changes, the simplest way to submit them may
1579just be to send them as patches in email:
1580
036be17e 1581First, use gitlink:git-format-patch[1]; for example:
d19fbc3c
BF
1582
1583-------------------------------------------------
eb6ae7f4 1584$ git format-patch origin
d19fbc3c
BF
1585-------------------------------------------------
1586
1587will produce a numbered series of files in the current directory, one
1588for each patch in the current branch but not in origin/HEAD.
1589
1590You can then import these into your mail client and send them by
1591hand. However, if you have a lot to send at once, you may prefer to
1592use the gitlink:git-send-email[1] script to automate the process.
1593Consult the mailing list for your project first to determine how they
1594prefer such patches be handled.
1595
e34caace 1596[[importing-patches]]
d19fbc3c 1597Importing patches to a project
b684f830 1598------------------------------
d19fbc3c
BF
1599
1600Git also provides a tool called gitlink:git-am[1] (am stands for
1601"apply mailbox"), for importing such an emailed series of patches.
1602Just save all of the patch-containing messages, in order, into a
1603single mailbox file, say "patches.mbox", then run
1604
1605-------------------------------------------------
eb6ae7f4 1606$ git am -3 patches.mbox
d19fbc3c
BF
1607-------------------------------------------------
1608
1609Git will apply each patch in order; if any conflicts are found, it
1610will stop, and you can fix the conflicts as described in
01997b4a
BF
1611"<<resolving-a-merge,Resolving a merge>>". (The "-3" option tells
1612git to perform a merge; if you would prefer it just to abort and
1613leave your tree and index untouched, you may omit that option.)
1614
1615Once the index is updated with the results of the conflict
1616resolution, instead of creating a new commit, just run
d19fbc3c
BF
1617
1618-------------------------------------------------
1619$ git am --resolved
1620-------------------------------------------------
1621
1622and git will create the commit for you and continue applying the
1623remaining patches from the mailbox.
1624
1625The final result will be a series of commits, one for each patch in
1626the original mailbox, with authorship and commit log message each
1627taken from the message containing each patch.
1628
1629[[setting-up-a-public-repository]]
1630Setting up a public repository
b684f830 1631------------------------------
d19fbc3c
BF
1632
1633Another way to submit changes to a project is to simply tell the
1634maintainer of that project to pull from your repository, exactly as
1635you did in the section "<<getting-updates-with-git-pull, Getting
1636updates with git pull>>".
1637
1638If you and maintainer both have accounts on the same machine, then
1639then you can just pull changes from each other's repositories
79c96c57
MC
1640directly; note that all of the commands (gitlink:git-clone[1],
1641git-fetch[1], git-pull[1], etc.) that accept a URL as an argument
21f13ee2 1642will also accept a local directory name; so, for example, you can
d19fbc3c
BF
1643use
1644
1645-------------------------------------------------
1646$ git clone /path/to/repository
1647$ git pull /path/to/other/repository
1648-------------------------------------------------
1649
1650If this sort of setup is inconvenient or impossible, another (more
1651common) option is to set up a public repository on a public server.
1652This also allows you to cleanly separate private work in progress
1653from publicly visible work.
1654
1655You will continue to do your day-to-day work in your personal
1656repository, but periodically "push" changes from your personal
1657repository into your public repository, allowing other developers to
1658pull from that repository. So the flow of changes, in a situation
1659where there is one other developer with a public repository, looks
1660like this:
1661
1662 you push
1663 your personal repo ------------------> your public repo
1664 ^ |
1665 | |
1666 | you pull | they pull
1667 | |
1668 | |
1669 | they push V
1670 their public repo <------------------- their repo
1671
1672Now, assume your personal repository is in the directory ~/proj. We
1673first create a new clone of the repository:
1674
1675-------------------------------------------------
52c80037 1676$ git clone --bare ~/proj proj.git
d19fbc3c
BF
1677-------------------------------------------------
1678
52c80037
BF
1679The resulting directory proj.git contains a "bare" git repository--it is
1680just the contents of the ".git" directory, without a checked-out copy of
1681a working directory.
d19fbc3c 1682
c64415e2 1683Next, copy proj.git to the server where you plan to host the
d19fbc3c
BF
1684public repository. You can use scp, rsync, or whatever is most
1685convenient.
1686
1687If somebody else maintains the public server, they may already have
1688set up a git service for you, and you may skip to the section
1689"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1690repository>>", below.
1691
1692Otherwise, the following sections explain how to export your newly
1693created public repository:
1694
1695[[exporting-via-http]]
1696Exporting a git repository via http
b684f830 1697-----------------------------------
d19fbc3c
BF
1698
1699The git protocol gives better performance and reliability, but on a
1700host with a web server set up, http exports may be simpler to set up.
1701
1702All you need to do is place the newly created bare git repository in
1703a directory that is exported by the web server, and make some
1704adjustments to give web clients some extra information they need:
1705
1706-------------------------------------------------
1707$ mv proj.git /home/you/public_html/proj.git
1708$ cd proj.git
c64415e2 1709$ git --bare update-server-info
d19fbc3c
BF
1710$ chmod a+x hooks/post-update
1711-------------------------------------------------
1712
1713(For an explanation of the last two lines, see
1714gitlink:git-update-server-info[1], and the documentation
1715link:hooks.txt[Hooks used by git].)
1716
1717Advertise the url of proj.git. Anybody else should then be able to
1718clone or pull from that url, for example with a commandline like:
1719
1720-------------------------------------------------
1721$ git clone http://yourserver.com/~you/proj.git
1722-------------------------------------------------
1723
1724(See also
1725link:howto/setup-git-server-over-http.txt[setup-git-server-over-http]
1726for a slightly more sophisticated setup using WebDAV which also
1727allows pushing over http.)
1728
1729[[exporting-via-git]]
1730Exporting a git repository via the git protocol
b684f830 1731-----------------------------------------------
d19fbc3c
BF
1732
1733This is the preferred method.
1734
1735For now, we refer you to the gitlink:git-daemon[1] man page for
1736instructions. (See especially the examples section.)
1737
1738[[pushing-changes-to-a-public-repository]]
1739Pushing changes to a public repository
b684f830 1740--------------------------------------
d19fbc3c
BF
1741
1742Note that the two techniques outline above (exporting via
1743<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1744maintainers to fetch your latest changes, but they do not allow write
1745access, which you will need to update the public repository with the
1746latest changes created in your private repository.
1747
1748The simplest way to do this is using gitlink:git-push[1] and ssh; to
1749update the remote branch named "master" with the latest state of your
1750branch named "master", run
1751
1752-------------------------------------------------
1753$ git push ssh://yourserver.com/~you/proj.git master:master
1754-------------------------------------------------
1755
1756or just
1757
1758-------------------------------------------------
1759$ git push ssh://yourserver.com/~you/proj.git master
1760-------------------------------------------------
1761
1762As with git-fetch, git-push will complain if this does not result in
1763a <<fast-forwards,fast forward>>. Normally this is a sign of
1764something wrong. However, if you are sure you know what you're
1765doing, you may force git-push to perform the update anyway by
1766proceeding the branch name by a plus sign:
1767
1768-------------------------------------------------
1769$ git push ssh://yourserver.com/~you/proj.git +master
1770-------------------------------------------------
1771
1772As with git-fetch, you may also set up configuration options to
1773save typing; so, for example, after
1774
1775-------------------------------------------------
c64415e2 1776$ cat >>.git/config <<EOF
d19fbc3c
BF
1777[remote "public-repo"]
1778 url = ssh://yourserver.com/~you/proj.git
1779EOF
1780-------------------------------------------------
1781
1782you should be able to perform the above push with just
1783
1784-------------------------------------------------
1785$ git push public-repo master
1786-------------------------------------------------
1787
1788See the explanations of the remote.<name>.url, branch.<name>.remote,
9d13bda3 1789and remote.<name>.push options in gitlink:git-config[1] for
d19fbc3c
BF
1790details.
1791
e34caace 1792[[setting-up-a-shared-repository]]
d19fbc3c 1793Setting up a shared repository
b684f830 1794------------------------------
d19fbc3c
BF
1795
1796Another way to collaborate is by using a model similar to that
1797commonly used in CVS, where several developers with special rights
1798all push to and pull from a single shared repository. See
1799link:cvs-migration.txt[git for CVS users] for instructions on how to
1800set this up.
1801
e34caace 1802[[setting-up-gitweb]]
b684f830
BF
1803Allow web browsing of a repository
1804----------------------------------
d19fbc3c 1805
a8cd1402
BF
1806The gitweb cgi script provides users an easy way to browse your
1807project's files and history without having to install git; see the file
04483524 1808gitweb/INSTALL in the git source tree for instructions on setting it up.
d19fbc3c 1809
e34caace 1810[[sharing-development-examples]]
b684f830
BF
1811Examples
1812--------
d19fbc3c 1813
9e2163ea
BF
1814[[maintaining-topic-branches]]
1815Maintaining topic branches for a Linux subsystem maintainer
1816~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1817
1818This describes how Tony Luck uses git in his role as maintainer of the
1819IA64 architecture for the Linux kernel.
1820
1821He uses two public branches:
1822
1823 - A "test" tree into which patches are initially placed so that they
1824 can get some exposure when integrated with other ongoing development.
1825 This tree is available to Andrew for pulling into -mm whenever he
1826 wants.
1827
1828 - A "release" tree into which tested patches are moved for final sanity
1829 checking, and as a vehicle to send them upstream to Linus (by sending
1830 him a "please pull" request.)
1831
1832He also uses a set of temporary branches ("topic branches"), each
1833containing a logical grouping of patches.
1834
1835To set this up, first create your work tree by cloning Linus's public
1836tree:
1837
1838-------------------------------------------------
1839$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
1840$ cd work
1841-------------------------------------------------
1842
1843Linus's tree will be stored in the remote branch named origin/master,
1844and can be updated using gitlink:git-fetch[1]; you can track other
1845public trees using gitlink:git-remote[1] to set up a "remote" and
1846git-fetch[1] to keep them up-to-date; see <<repositories-and-branches>>.
1847
1848Now create the branches in which you are going to work; these start out
1849at the current tip of origin/master branch, and should be set up (using
1850the --track option to gitlink:git-branch[1]) to merge changes in from
1851Linus by default.
1852
1853-------------------------------------------------
1854$ git branch --track test origin/master
1855$ git branch --track release origin/master
1856-------------------------------------------------
1857
1858These can be easily kept up to date using gitlink:git-pull[1]
1859
1860-------------------------------------------------
1861$ git checkout test && git pull
1862$ git checkout release && git pull
1863-------------------------------------------------
1864
1865Important note! If you have any local changes in these branches, then
1866this merge will create a commit object in the history (with no local
1867changes git will simply do a "Fast forward" merge). Many people dislike
1868the "noise" that this creates in the Linux history, so you should avoid
1869doing this capriciously in the "release" branch, as these noisy commits
1870will become part of the permanent history when you ask Linus to pull
1871from the release branch.
1872
1873A few configuration variables (see gitlink:git-config[1]) can
1874make it easy to push both branches to your public tree. (See
1875<<setting-up-a-public-repository>>.)
1876
1877-------------------------------------------------
1878$ cat >> .git/config <<EOF
1879[remote "mytree"]
1880 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
1881 push = release
1882 push = test
1883EOF
1884-------------------------------------------------
1885
1886Then you can push both the test and release trees using
1887gitlink:git-push[1]:
1888
1889-------------------------------------------------
1890$ git push mytree
1891-------------------------------------------------
1892
1893or push just one of the test and release branches using:
1894
1895-------------------------------------------------
1896$ git push mytree test
1897-------------------------------------------------
1898
1899or
1900
1901-------------------------------------------------
1902$ git push mytree release
1903-------------------------------------------------
1904
1905Now to apply some patches from the community. Think of a short
1906snappy name for a branch to hold this patch (or related group of
1907patches), and create a new branch from the current tip of Linus's
1908branch:
1909
1910-------------------------------------------------
1911$ git checkout -b speed-up-spinlocks origin
1912-------------------------------------------------
1913
1914Now you apply the patch(es), run some tests, and commit the change(s). If
1915the patch is a multi-part series, then you should apply each as a separate
1916commit to this branch.
1917
1918-------------------------------------------------
1919$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
1920-------------------------------------------------
1921
1922When you are happy with the state of this change, you can pull it into the
1923"test" branch in preparation to make it public:
1924
1925-------------------------------------------------
1926$ git checkout test && git pull . speed-up-spinlocks
1927-------------------------------------------------
1928
1929It is unlikely that you would have any conflicts here ... but you might if you
1930spent a while on this step and had also pulled new versions from upstream.
1931
1932Some time later when enough time has passed and testing done, you can pull the
1933same branch into the "release" tree ready to go upstream. This is where you
1934see the value of keeping each patch (or patch series) in its own branch. It
1935means that the patches can be moved into the "release" tree in any order.
1936
1937-------------------------------------------------
1938$ git checkout release && git pull . speed-up-spinlocks
1939-------------------------------------------------
1940
1941After a while, you will have a number of branches, and despite the
1942well chosen names you picked for each of them, you may forget what
1943they are for, or what status they are in. To get a reminder of what
1944changes are in a specific branch, use:
1945
1946-------------------------------------------------
1947$ git log linux..branchname | git-shortlog
1948-------------------------------------------------
1949
1950To see whether it has already been merged into the test or release branches
1951use:
1952
1953-------------------------------------------------
1954$ git log test..branchname
1955-------------------------------------------------
1956
1957or
1958
1959-------------------------------------------------
1960$ git log release..branchname
1961-------------------------------------------------
1962
1963(If this branch has not yet been merged you will see some log entries.
1964If it has been merged, then there will be no output.)
1965
1966Once a patch completes the great cycle (moving from test to release,
1967then pulled by Linus, and finally coming back into your local
1968"origin/master" branch) the branch for this change is no longer needed.
1969You detect this when the output from:
1970
1971-------------------------------------------------
1972$ git log origin..branchname
1973-------------------------------------------------
1974
1975is empty. At this point the branch can be deleted:
1976
1977-------------------------------------------------
1978$ git branch -d branchname
1979-------------------------------------------------
1980
1981Some changes are so trivial that it is not necessary to create a separate
1982branch and then merge into each of the test and release branches. For
1983these changes, just apply directly to the "release" branch, and then
1984merge that into the "test" branch.
1985
1986To create diffstat and shortlog summaries of changes to include in a "please
1987pull" request to Linus you can use:
1988
1989-------------------------------------------------
1990$ git diff --stat origin..release
1991-------------------------------------------------
1992
1993and
1994
1995-------------------------------------------------
1996$ git log -p origin..release | git shortlog
1997-------------------------------------------------
1998
1999Here are some of the scripts that simplify all this even further.
2000
2001-------------------------------------------------
2002==== update script ====
2003# Update a branch in my GIT tree. If the branch to be updated
2004# is origin, then pull from kernel.org. Otherwise merge
2005# origin/master branch into test|release branch
2006
2007case "$1" in
2008test|release)
2009 git checkout $1 && git pull . origin
2010 ;;
2011origin)
2012 before=$(cat .git/refs/remotes/origin/master)
2013 git fetch origin
2014 after=$(cat .git/refs/remotes/origin/master)
2015 if [ $before != $after ]
2016 then
2017 git log $before..$after | git shortlog
2018 fi
2019 ;;
2020*)
2021 echo "Usage: $0 origin|test|release" 1>&2
2022 exit 1
2023 ;;
2024esac
2025-------------------------------------------------
2026
2027-------------------------------------------------
2028==== merge script ====
2029# Merge a branch into either the test or release branch
2030
2031pname=$0
2032
2033usage()
2034{
2035 echo "Usage: $pname branch test|release" 1>&2
2036 exit 1
2037}
2038
2039if [ ! -f .git/refs/heads/"$1" ]
2040then
2041 echo "Can't see branch <$1>" 1>&2
2042 usage
2043fi
2044
2045case "$2" in
2046test|release)
2047 if [ $(git log $2..$1 | wc -c) -eq 0 ]
2048 then
2049 echo $1 already merged into $2 1>&2
2050 exit 1
2051 fi
2052 git checkout $2 && git pull . $1
2053 ;;
2054*)
2055 usage
2056 ;;
2057esac
2058-------------------------------------------------
2059
2060-------------------------------------------------
2061==== status script ====
2062# report on status of my ia64 GIT tree
2063
2064gb=$(tput setab 2)
2065rb=$(tput setab 1)
2066restore=$(tput setab 9)
2067
2068if [ `git rev-list test..release | wc -c` -gt 0 ]
2069then
2070 echo $rb Warning: commits in release that are not in test $restore
2071 git log test..release
2072fi
2073
2074for branch in `ls .git/refs/heads`
2075do
2076 if [ $branch = test -o $branch = release ]
2077 then
2078 continue
2079 fi
2080
2081 echo -n $gb ======= $branch ====== $restore " "
2082 status=
2083 for ref in test release origin/master
2084 do
2085 if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
2086 then
2087 status=$status${ref:0:1}
2088 fi
2089 done
2090 case $status in
2091 trl)
2092 echo $rb Need to pull into test $restore
2093 ;;
2094 rl)
2095 echo "In test"
2096 ;;
2097 l)
2098 echo "Waiting for linus"
2099 ;;
2100 "")
2101 echo $rb All done $restore
2102 ;;
2103 *)
2104 echo $rb "<$status>" $restore
2105 ;;
2106 esac
2107 git log origin/master..$branch | git shortlog
2108done
2109-------------------------------------------------
d19fbc3c 2110
d19fbc3c 2111
d19fbc3c 2112[[cleaning-up-history]]
4c63ff45
BF
2113Rewriting history and maintaining patch series
2114==============================================
2115
2116Normally commits are only added to a project, never taken away or
2117replaced. Git is designed with this assumption, and violating it will
2118cause git's merge machinery (for example) to do the wrong thing.
2119
2120However, there is a situation in which it can be useful to violate this
2121assumption.
2122
e34caace 2123[[patch-series]]
4c63ff45
BF
2124Creating the perfect patch series
2125---------------------------------
2126
2127Suppose you are a contributor to a large project, and you want to add a
2128complicated feature, and to present it to the other developers in a way
2129that makes it easy for them to read your changes, verify that they are
2130correct, and understand why you made each change.
2131
b181d57f 2132If you present all of your changes as a single patch (or commit), they
79c96c57 2133may find that it is too much to digest all at once.
4c63ff45
BF
2134
2135If you present them with the entire history of your work, complete with
2136mistakes, corrections, and dead ends, they may be overwhelmed.
2137
2138So the ideal is usually to produce a series of patches such that:
2139
2140 1. Each patch can be applied in order.
2141
2142 2. Each patch includes a single logical change, together with a
2143 message explaining the change.
2144
2145 3. No patch introduces a regression: after applying any initial
2146 part of the series, the resulting project still compiles and
2147 works, and has no bugs that it didn't have before.
2148
2149 4. The complete series produces the same end result as your own
2150 (probably much messier!) development process did.
2151
b181d57f
BF
2152We will introduce some tools that can help you do this, explain how to
2153use them, and then explain some of the problems that can arise because
2154you are rewriting history.
4c63ff45 2155
e34caace 2156[[using-git-rebase]]
4c63ff45
BF
2157Keeping a patch series up to date using git-rebase
2158--------------------------------------------------
2159
79c96c57
MC
2160Suppose that you create a branch "mywork" on a remote-tracking branch
2161"origin", and create some commits on top of it:
4c63ff45
BF
2162
2163-------------------------------------------------
2164$ git checkout -b mywork origin
2165$ vi file.txt
2166$ git commit
2167$ vi otherfile.txt
2168$ git commit
2169...
2170-------------------------------------------------
2171
2172You have performed no merges into mywork, so it is just a simple linear
2173sequence of patches on top of "origin":
2174
1dc71a91 2175................................................
4c63ff45
BF
2176 o--o--o <-- origin
2177 \
2178 o--o--o <-- mywork
1dc71a91 2179................................................
4c63ff45
BF
2180
2181Some more interesting work has been done in the upstream project, and
2182"origin" has advanced:
2183
1dc71a91 2184................................................
4c63ff45
BF
2185 o--o--O--o--o--o <-- origin
2186 \
2187 a--b--c <-- mywork
1dc71a91 2188................................................
4c63ff45
BF
2189
2190At this point, you could use "pull" to merge your changes back in;
2191the result would create a new merge commit, like this:
2192
1dc71a91 2193................................................
4c63ff45
BF
2194 o--o--O--o--o--o <-- origin
2195 \ \
2196 a--b--c--m <-- mywork
1dc71a91 2197................................................
4c63ff45
BF
2198
2199However, if you prefer to keep the history in mywork a simple series of
2200commits without any merges, you may instead choose to use
2201gitlink:git-rebase[1]:
2202
2203-------------------------------------------------
2204$ git checkout mywork
2205$ git rebase origin
2206-------------------------------------------------
2207
b181d57f
BF
2208This will remove each of your commits from mywork, temporarily saving
2209them as patches (in a directory named ".dotest"), update mywork to
2210point at the latest version of origin, then apply each of the saved
2211patches to the new mywork. The result will look like:
4c63ff45
BF
2212
2213
1dc71a91 2214................................................
4c63ff45
BF
2215 o--o--O--o--o--o <-- origin
2216 \
2217 a'--b'--c' <-- mywork
1dc71a91 2218................................................
4c63ff45 2219
b181d57f
BF
2220In the process, it may discover conflicts. In that case it will stop
2221and allow you to fix the conflicts; after fixing conflicts, use "git
2222add" to update the index with those contents, and then, instead of
2223running git-commit, just run
4c63ff45
BF
2224
2225-------------------------------------------------
2226$ git rebase --continue
2227-------------------------------------------------
2228
2229and git will continue applying the rest of the patches.
2230
2231At any point you may use the --abort option to abort this process and
2232return mywork to the state it had before you started the rebase:
2233
2234-------------------------------------------------
2235$ git rebase --abort
2236-------------------------------------------------
2237
e34caace 2238[[modifying-one-commit]]
365aa199
BF
2239Modifying a single commit
2240-------------------------
2241
2242We saw in <<fixing-a-mistake-by-editing-history>> that you can replace the
2243most recent commit using
2244
2245-------------------------------------------------
2246$ git commit --amend
2247-------------------------------------------------
2248
2249which will replace the old commit by a new commit incorporating your
2250changes, giving you a chance to edit the old commit message first.
2251
2252You can also use a combination of this and gitlink:git-rebase[1] to edit
2253commits further back in your history. First, tag the problematic commit with
2254
2255-------------------------------------------------
2256$ git tag bad mywork~5
2257-------------------------------------------------
2258
2259(Either gitk or git-log may be useful for finding the commit.)
2260
25d9f3fa
BF
2261Then check out that commit, edit it, and rebase the rest of the series
2262on top of it (note that we could check out the commit on a temporary
2263branch, but instead we're using a <<detached-head,detached head>>):
365aa199
BF
2264
2265-------------------------------------------------
25d9f3fa 2266$ git checkout bad
365aa199
BF
2267$ # make changes here and update the index
2268$ git commit --amend
25d9f3fa 2269$ git rebase --onto HEAD bad mywork
365aa199
BF
2270-------------------------------------------------
2271
25d9f3fa
BF
2272When you're done, you'll be left with mywork checked out, with the top
2273patches on mywork reapplied on top of your modified commit. You can
365aa199
BF
2274then clean up with
2275
2276-------------------------------------------------
365aa199
BF
2277$ git tag -d bad
2278-------------------------------------------------
2279
2280Note that the immutable nature of git history means that you haven't really
2281"modified" existing commits; instead, you have replaced the old commits with
2282new commits having new object names.
2283
e34caace 2284[[reordering-patch-series]]
4c63ff45
BF
2285Reordering or selecting from a patch series
2286-------------------------------------------
2287
b181d57f
BF
2288Given one existing commit, the gitlink:git-cherry-pick[1] command
2289allows you to apply the change introduced by that commit and create a
2290new commit that records it. So, for example, if "mywork" points to a
2291series of patches on top of "origin", you might do something like:
2292
2293-------------------------------------------------
2294$ git checkout -b mywork-new origin
2295$ gitk origin..mywork &
2296-------------------------------------------------
2297
2298And browse through the list of patches in the mywork branch using gitk,
2299applying them (possibly in a different order) to mywork-new using
2300cherry-pick, and possibly modifying them as you go using commit
2301--amend.
2302
2303Another technique is to use git-format-patch to create a series of
2304patches, then reset the state to before the patches:
4c63ff45 2305
b181d57f
BF
2306-------------------------------------------------
2307$ git format-patch origin
2308$ git reset --hard origin
2309-------------------------------------------------
4c63ff45 2310
b181d57f
BF
2311Then modify, reorder, or eliminate patches as preferred before applying
2312them again with gitlink:git-am[1].
4c63ff45 2313
e34caace 2314[[patch-series-tools]]
4c63ff45
BF
2315Other tools
2316-----------
2317
b181d57f 2318There are numerous other tools, such as stgit, which exist for the
79c96c57 2319purpose of maintaining a patch series. These are outside of the scope of
b181d57f 2320this manual.
4c63ff45 2321
e34caace 2322[[problems-with-rewriting-history]]
4c63ff45
BF
2323Problems with rewriting history
2324-------------------------------
2325
b181d57f
BF
2326The primary problem with rewriting the history of a branch has to do
2327with merging. Suppose somebody fetches your branch and merges it into
2328their branch, with a result something like this:
2329
1dc71a91 2330................................................
b181d57f
BF
2331 o--o--O--o--o--o <-- origin
2332 \ \
2333 t--t--t--m <-- their branch:
1dc71a91 2334................................................
b181d57f
BF
2335
2336Then suppose you modify the last three commits:
2337
1dc71a91 2338................................................
b181d57f
BF
2339 o--o--o <-- new head of origin
2340 /
2341 o--o--O--o--o--o <-- old head of origin
1dc71a91 2342................................................
b181d57f
BF
2343
2344If we examined all this history together in one repository, it will
2345look like:
2346
1dc71a91 2347................................................
b181d57f
BF
2348 o--o--o <-- new head of origin
2349 /
2350 o--o--O--o--o--o <-- old head of origin
2351 \ \
2352 t--t--t--m <-- their branch:
1dc71a91 2353................................................
b181d57f
BF
2354
2355Git has no way of knowing that the new head is an updated version of
2356the old head; it treats this situation exactly the same as it would if
2357two developers had independently done the work on the old and new heads
2358in parallel. At this point, if someone attempts to merge the new head
2359in to their branch, git will attempt to merge together the two (old and
2360new) lines of development, instead of trying to replace the old by the
2361new. The results are likely to be unexpected.
2362
2363You may still choose to publish branches whose history is rewritten,
2364and it may be useful for others to be able to fetch those branches in
2365order to examine or test them, but they should not attempt to pull such
2366branches into their own work.
2367
2368For true distributed development that supports proper merging,
2369published branches should never be rewritten.
2370
e34caace 2371[[advanced-branch-management]]
b181d57f
BF
2372Advanced branch management
2373==========================
4c63ff45 2374
e34caace 2375[[fetching-individual-branches]]
b181d57f
BF
2376Fetching individual branches
2377----------------------------
2378
2379Instead of using gitlink:git-remote[1], you can also choose just
2380to update one branch at a time, and to store it locally under an
2381arbitrary name:
2382
2383-------------------------------------------------
2384$ git fetch origin todo:my-todo-work
2385-------------------------------------------------
2386
2387The first argument, "origin", just tells git to fetch from the
2388repository you originally cloned from. The second argument tells git
2389to fetch the branch named "todo" from the remote repository, and to
2390store it locally under the name refs/heads/my-todo-work.
2391
2392You can also fetch branches from other repositories; so
2393
2394-------------------------------------------------
2395$ git fetch git://example.com/proj.git master:example-master
2396-------------------------------------------------
2397
2398will create a new branch named "example-master" and store in it the
2399branch named "master" from the repository at the given URL. If you
2400already have a branch named example-master, it will attempt to
59723040
BF
2401<<fast-forwards,fast-forward>> to the commit given by example.com's
2402master branch. In more detail:
b181d57f 2403
59723040
BF
2404[[fetch-fast-forwards]]
2405git fetch and fast-forwards
2406---------------------------
b181d57f
BF
2407
2408In the previous example, when updating an existing branch, "git
2409fetch" checks to make sure that the most recent commit on the remote
2410branch is a descendant of the most recent commit on your copy of the
2411branch before updating your copy of the branch to point at the new
59723040 2412commit. Git calls this process a <<fast-forwards,fast forward>>.
b181d57f
BF
2413
2414A fast forward looks something like this:
2415
1dc71a91 2416................................................
b181d57f
BF
2417 o--o--o--o <-- old head of the branch
2418 \
2419 o--o--o <-- new head of the branch
1dc71a91 2420................................................
b181d57f
BF
2421
2422
2423In some cases it is possible that the new head will *not* actually be
2424a descendant of the old head. For example, the developer may have
2425realized she made a serious mistake, and decided to backtrack,
2426resulting in a situation like:
2427
1dc71a91 2428................................................
b181d57f
BF
2429 o--o--o--o--a--b <-- old head of the branch
2430 \
2431 o--o--o <-- new head of the branch
1dc71a91 2432................................................
b181d57f
BF
2433
2434In this case, "git fetch" will fail, and print out a warning.
2435
2436In that case, you can still force git to update to the new head, as
2437described in the following section. However, note that in the
2438situation above this may mean losing the commits labeled "a" and "b",
2439unless you've already created a reference of your own pointing to
2440them.
2441
e34caace 2442[[forcing-fetch]]
b181d57f
BF
2443Forcing git fetch to do non-fast-forward updates
2444------------------------------------------------
2445
2446If git fetch fails because the new head of a branch is not a
2447descendant of the old head, you may force the update with:
2448
2449-------------------------------------------------
2450$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
2451-------------------------------------------------
2452
c64415e2
BF
2453Note the addition of the "+" sign. Alternatively, you can use the "-f"
2454flag to force updates of all the fetched branches, as in:
2455
2456-------------------------------------------------
2457$ git fetch -f origin
2458-------------------------------------------------
2459
2460Be aware that commits that the old version of example/master pointed at
2461may be lost, as we saw in the previous section.
b181d57f 2462
e34caace 2463[[remote-branch-configuration]]
b181d57f
BF
2464Configuring remote branches
2465---------------------------
2466
2467We saw above that "origin" is just a shortcut to refer to the
79c96c57 2468repository that you originally cloned from. This information is
b181d57f 2469stored in git configuration variables, which you can see using
9d13bda3 2470gitlink:git-config[1]:
b181d57f
BF
2471
2472-------------------------------------------------
9d13bda3 2473$ git config -l
b181d57f
BF
2474core.repositoryformatversion=0
2475core.filemode=true
2476core.logallrefupdates=true
2477remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
2478remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
2479branch.master.remote=origin
2480branch.master.merge=refs/heads/master
2481-------------------------------------------------
2482
2483If there are other repositories that you also use frequently, you can
2484create similar configuration options to save typing; for example,
2485after
2486
2487-------------------------------------------------
9d13bda3 2488$ git config remote.example.url git://example.com/proj.git
b181d57f
BF
2489-------------------------------------------------
2490
2491then the following two commands will do the same thing:
2492
2493-------------------------------------------------
2494$ git fetch git://example.com/proj.git master:refs/remotes/example/master
2495$ git fetch example master:refs/remotes/example/master
2496-------------------------------------------------
2497
2498Even better, if you add one more option:
2499
2500-------------------------------------------------
9d13bda3 2501$ git config remote.example.fetch master:refs/remotes/example/master
b181d57f
BF
2502-------------------------------------------------
2503
2504then the following commands will all do the same thing:
2505
2506-------------------------------------------------
52c80037
BF
2507$ git fetch git://example.com/proj.git master:refs/remotes/example/master
2508$ git fetch example master:refs/remotes/example/master
b181d57f
BF
2509$ git fetch example
2510-------------------------------------------------
2511
2512You can also add a "+" to force the update each time:
2513
2514-------------------------------------------------
9d13bda3 2515$ git config remote.example.fetch +master:ref/remotes/example/master
b181d57f
BF
2516-------------------------------------------------
2517
2518Don't do this unless you're sure you won't mind "git fetch" possibly
2519throwing away commits on mybranch.
2520
2521Also note that all of the above configuration can be performed by
2522directly editing the file .git/config instead of using
9d13bda3 2523gitlink:git-config[1].
b181d57f 2524
9d13bda3 2525See gitlink:git-config[1] for more details on the configuration
b181d57f 2526options mentioned above.
d19fbc3c 2527
d19fbc3c 2528
35121930 2529[[git-internals]]
d19fbc3c
BF
2530Git internals
2531=============
2532
a536b08b
BF
2533Git depends on two fundamental abstractions: the "object database", and
2534the "current directory cache" aka "index".
b181d57f 2535
e34caace 2536[[the-object-database]]
b181d57f
BF
2537The Object Database
2538-------------------
2539
2540The object database is literally just a content-addressable collection
2541of objects. All objects are named by their content, which is
2542approximated by the SHA1 hash of the object itself. Objects may refer
2543to other objects (by referencing their SHA1 hash), and so you can
2544build up a hierarchy of objects.
2545
c64415e2 2546All objects have a statically determined "type" which is
b181d57f
BF
2547determined at object creation time, and which identifies the format of
2548the object (i.e. how it is used, and how it can refer to other
2549objects). There are currently four different object types: "blob",
a536b08b 2550"tree", "commit", and "tag".
b181d57f 2551
a536b08b
BF
2552A <<def_blob_object,"blob" object>> cannot refer to any other object,
2553and is, as the name implies, a pure storage object containing some
2554user data. It is used to actually store the file data, i.e. a blob
2555object is associated with some particular version of some file.
b181d57f 2556
a536b08b
BF
2557A <<def_tree_object,"tree" object>> is an object that ties one or more
2558"blob" objects into a directory structure. In addition, a tree object
2559can refer to other tree objects, thus creating a directory hierarchy.
b181d57f 2560
a536b08b
BF
2561A <<def_commit_object,"commit" object>> ties such directory hierarchies
2562together into a <<def_DAG,directed acyclic graph>> of revisions - each
2563"commit" is associated with exactly one tree (the directory hierarchy at
2564the time of the commit). In addition, a "commit" refers to one or more
2565"parent" commit objects that describe the history of how we arrived at
2566that directory hierarchy.
b181d57f
BF
2567
2568As a special case, a commit object with no parents is called the "root"
c64415e2 2569commit, and is the point of an initial project commit. Each project
b181d57f
BF
2570must have at least one root, and while you can tie several different
2571root objects together into one project by creating a commit object which
2572has two or more separate roots as its ultimate parents, that's probably
2573just going to confuse people. So aim for the notion of "one root object
2574per project", even if git itself does not enforce that.
2575
a536b08b
BF
2576A <<def_tag_object,"tag" object>> symbolically identifies and can be
2577used to sign other objects. It contains the identifier and type of
2578another object, a symbolic name (of course!) and, optionally, a
2579signature.
b181d57f
BF
2580
2581Regardless of object type, all objects share the following
2582characteristics: they are all deflated with zlib, and have a header
2583that not only specifies their type, but also provides size information
2584about the data in the object. It's worth noting that the SHA1 hash
2585that is used to name the object is the hash of the original data
2586plus this header, so `sha1sum` 'file' does not match the object name
2587for 'file'.
2588(Historical note: in the dawn of the age of git the hash
2589was the sha1 of the 'compressed' object.)
2590
2591As a result, the general consistency of an object can always be tested
2592independently of the contents or the type of the object: all objects can
2593be validated by verifying that (a) their hashes match the content of the
2594file and (b) the object successfully inflates to a stream of bytes that
2595forms a sequence of <ascii type without space> + <space> + <ascii decimal
2596size> + <byte\0> + <binary object data>.
2597
2598The structured objects can further have their structure and
2599connectivity to other objects verified. This is generally done with
04e50e94 2600the `git-fsck` program, which generates a full dependency graph
b181d57f
BF
2601of all objects, and verifies their internal consistency (in addition
2602to just verifying their superficial consistency through the hash).
2603
2604The object types in some more detail:
2605
e34caace 2606[[blob-object]]
b181d57f
BF
2607Blob Object
2608-----------
2609
2610A "blob" object is nothing but a binary blob of data, and doesn't
2611refer to anything else. There is no signature or any other
2612verification of the data, so while the object is consistent (it 'is'
2613indexed by its sha1 hash, so the data itself is certainly correct), it
2614has absolutely no other attributes. No name associations, no
2615permissions. It is purely a blob of data (i.e. normally "file
2616contents").
2617
2618In particular, since the blob is entirely defined by its data, if two
2619files in a directory tree (or in multiple different versions of the
2620repository) have the same contents, they will share the same blob
2621object. The object is totally independent of its location in the
2622directory tree, and renaming a file does not change the object that
2623file is associated with in any way.
2624
2625A blob is typically created when gitlink:git-update-index[1]
2626is run, and its data can be accessed by gitlink:git-cat-file[1].
2627
e34caace 2628[[tree-object]]
b181d57f
BF
2629Tree Object
2630-----------
2631
2632The next hierarchical object type is the "tree" object. A tree object
2633is a list of mode/name/blob data, sorted by name. Alternatively, the
2634mode data may specify a directory mode, in which case instead of
2635naming a blob, that name is associated with another TREE object.
2636
2637Like the "blob" object, a tree object is uniquely determined by the
2638set contents, and so two separate but identical trees will always
2639share the exact same object. This is true at all levels, i.e. it's
2640true for a "leaf" tree (which does not refer to any other trees, only
2641blobs) as well as for a whole subdirectory.
2642
2643For that reason a "tree" object is just a pure data abstraction: it
2644has no history, no signatures, no verification of validity, except
2645that since the contents are again protected by the hash itself, we can
2646trust that the tree is immutable and its contents never change.
2647
2648So you can trust the contents of a tree to be valid, the same way you
2649can trust the contents of a blob, but you don't know where those
2650contents 'came' from.
2651
2652Side note on trees: since a "tree" object is a sorted list of
2653"filename+content", you can create a diff between two trees without
2654actually having to unpack two trees. Just ignore all common parts,
2655and your diff will look right. In other words, you can effectively
2656(and efficiently) tell the difference between any two random trees by
2657O(n) where "n" is the size of the difference, rather than the size of
2658the tree.
2659
2660Side note 2 on trees: since the name of a "blob" depends entirely and
2661exclusively on its contents (i.e. there are no names or permissions
2662involved), you can see trivial renames or permission changes by
2663noticing that the blob stayed the same. However, renames with data
2664changes need a smarter "diff" implementation.
2665
2666A tree is created with gitlink:git-write-tree[1] and
2667its data can be accessed by gitlink:git-ls-tree[1].
2668Two trees can be compared with gitlink:git-diff-tree[1].
2669
e34caace 2670[[commit-object]]
b181d57f
BF
2671Commit Object
2672-------------
2673
2674The "commit" object is an object that introduces the notion of
2675history into the picture. In contrast to the other objects, it
2676doesn't just describe the physical state of a tree, it describes how
2677we got there, and why.
2678
2679A "commit" is defined by the tree-object that it results in, the
2680parent commits (zero, one or more) that led up to that point, and a
2681comment on what happened. Again, a commit is not trusted per se:
2682the contents are well-defined and "safe" due to the cryptographically
2683strong signatures at all levels, but there is no reason to believe
2684that the tree is "good" or that the merge information makes sense.
2685The parents do not have to actually have any relationship with the
2686result, for example.
2687
c64415e2 2688Note on commits: unlike some SCM's, commits do not contain
b181d57f
BF
2689rename information or file mode change information. All of that is
2690implicit in the trees involved (the result tree, and the result trees
2691of the parents), and describing that makes no sense in this idiotic
2692file manager.
2693
2694A commit is created with gitlink:git-commit-tree[1] and
2695its data can be accessed by gitlink:git-cat-file[1].
2696
e34caace 2697[[trust]]
b181d57f
BF
2698Trust
2699-----
2700
2701An aside on the notion of "trust". Trust is really outside the scope
2702of "git", but it's worth noting a few things. First off, since
2703everything is hashed with SHA1, you 'can' trust that an object is
2704intact and has not been messed with by external sources. So the name
2705of an object uniquely identifies a known state - just not a state that
2706you may want to trust.
2707
2708Furthermore, since the SHA1 signature of a commit refers to the
2709SHA1 signatures of the tree it is associated with and the signatures
2710of the parent, a single named commit specifies uniquely a whole set
2711of history, with full contents. You can't later fake any step of the
2712way once you have the name of a commit.
2713
2714So to introduce some real trust in the system, the only thing you need
2715to do is to digitally sign just 'one' special note, which includes the
2716name of a top-level commit. Your digital signature shows others
2717that you trust that commit, and the immutability of the history of
2718commits tells others that they can trust the whole history.
2719
2720In other words, you can easily validate a whole archive by just
2721sending out a single email that tells the people the name (SHA1 hash)
2722of the top commit, and digitally sign that email using something
2723like GPG/PGP.
2724
2725To assist in this, git also provides the tag object...
2726
e34caace 2727[[tag-object]]
b181d57f
BF
2728Tag Object
2729----------
2730
2731Git provides the "tag" object to simplify creating, managing and
2732exchanging symbolic and signed tokens. The "tag" object at its
2733simplest simply symbolically identifies another object by containing
2734the sha1, type and symbolic name.
2735
2736However it can optionally contain additional signature information
2737(which git doesn't care about as long as there's less than 8k of
2738it). This can then be verified externally to git.
2739
2740Note that despite the tag features, "git" itself only handles content
2741integrity; the trust framework (and signature provision and
2742verification) has to come from outside.
2743
2744A tag is created with gitlink:git-mktag[1],
2745its data can be accessed by gitlink:git-cat-file[1],
2746and the signature can be verified by
2747gitlink:git-verify-tag[1].
2748
2749
e34caace 2750[[the-index]]
b181d57f
BF
2751The "index" aka "Current Directory Cache"
2752-----------------------------------------
2753
2754The index is a simple binary file, which contains an efficient
c64415e2 2755representation of the contents of a virtual directory. It
b181d57f
BF
2756does so by a simple array that associates a set of names, dates,
2757permissions and content (aka "blob") objects together. The cache is
2758always kept ordered by name, and names are unique (with a few very
2759specific rules) at any point in time, but the cache has no long-term
2760meaning, and can be partially updated at any time.
2761
2762In particular, the index certainly does not need to be consistent with
2763the current directory contents (in fact, most operations will depend on
2764different ways to make the index 'not' be consistent with the directory
2765hierarchy), but it has three very important attributes:
2766
2767'(a) it can re-generate the full state it caches (not just the
2768directory structure: it contains pointers to the "blob" objects so
2769that it can regenerate the data too)'
2770
2771As a special case, there is a clear and unambiguous one-way mapping
2772from a current directory cache to a "tree object", which can be
2773efficiently created from just the current directory cache without
2774actually looking at any other data. So a directory cache at any one
2775time uniquely specifies one and only one "tree" object (but has
2776additional data to make it easy to match up that tree object with what
2777has happened in the directory)
2778
2779'(b) it has efficient methods for finding inconsistencies between that
2780cached state ("tree object waiting to be instantiated") and the
2781current state.'
2782
2783'(c) it can additionally efficiently represent information about merge
2784conflicts between different tree objects, allowing each pathname to be
2785associated with sufficient information about the trees involved that
2786you can create a three-way merge between them.'
2787
79c96c57 2788Those are the ONLY three things that the directory cache does. It's a
b181d57f
BF
2789cache, and the normal operation is to re-generate it completely from a
2790known tree object, or update/compare it with a live tree that is being
2791developed. If you blow the directory cache away entirely, you generally
2792haven't lost any information as long as you have the name of the tree
2793that it described.
2794
2795At the same time, the index is at the same time also the
2796staging area for creating new trees, and creating a new tree always
2797involves a controlled modification of the index file. In particular,
2798the index file can have the representation of an intermediate tree that
2799has not yet been instantiated. So the index can be thought of as a
2800write-back cache, which can contain dirty information that has not yet
2801been written back to the backing store.
2802
2803
2804
e34caace 2805[[the-workflow]]
b181d57f
BF
2806The Workflow
2807------------
2808
2809Generally, all "git" operations work on the index file. Some operations
2810work *purely* on the index file (showing the current state of the
2811index), but most operations move data to and from the index file. Either
2812from the database or from the working directory. Thus there are four
2813main combinations:
2814
e34caace 2815[[working-directory-to-index]]
b181d57f
BF
2816working directory -> index
2817~~~~~~~~~~~~~~~~~~~~~~~~~~
2818
2819You update the index with information from the working directory with
2820the gitlink:git-update-index[1] command. You
2821generally update the index information by just specifying the filename
2822you want to update, like so:
2823
2824-------------------------------------------------
2825$ git-update-index filename
2826-------------------------------------------------
2827
2828but to avoid common mistakes with filename globbing etc, the command
2829will not normally add totally new entries or remove old entries,
2830i.e. it will normally just update existing cache entries.
2831
2832To tell git that yes, you really do realize that certain files no
2833longer exist, or that new files should be added, you
2834should use the `--remove` and `--add` flags respectively.
2835
2836NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
2837necessarily be removed: if the files still exist in your directory
2838structure, the index will be updated with their new status, not
2839removed. The only thing `--remove` means is that update-cache will be
2840considering a removed file to be a valid thing, and if the file really
2841does not exist any more, it will update the index accordingly.
2842
2843As a special case, you can also do `git-update-index --refresh`, which
2844will refresh the "stat" information of each index to match the current
2845stat information. It will 'not' update the object status itself, and
2846it will only update the fields that are used to quickly test whether
2847an object still matches its old backing store object.
2848
e34caace 2849[[index-to-object-database]]
b181d57f
BF
2850index -> object database
2851~~~~~~~~~~~~~~~~~~~~~~~~
2852
2853You write your current index file to a "tree" object with the program
2854
2855-------------------------------------------------
2856$ git-write-tree
2857-------------------------------------------------
2858
2859that doesn't come with any options - it will just write out the
2860current index into the set of tree objects that describe that state,
2861and it will return the name of the resulting top-level tree. You can
2862use that tree to re-generate the index at any time by going in the
2863other direction:
2864
e34caace 2865[[object-database-to-index]]
b181d57f
BF
2866object database -> index
2867~~~~~~~~~~~~~~~~~~~~~~~~
2868
2869You read a "tree" file from the object database, and use that to
2870populate (and overwrite - don't do this if your index contains any
2871unsaved state that you might want to restore later!) your current
2872index. Normal operation is just
2873
2874-------------------------------------------------
2875$ git-read-tree <sha1 of tree>
2876-------------------------------------------------
2877
2878and your index file will now be equivalent to the tree that you saved
2879earlier. However, that is only your 'index' file: your working
2880directory contents have not been modified.
2881
e34caace 2882[[index-to-working-directory]]
b181d57f
BF
2883index -> working directory
2884~~~~~~~~~~~~~~~~~~~~~~~~~~
2885
2886You update your working directory from the index by "checking out"
2887files. This is not a very common operation, since normally you'd just
2888keep your files updated, and rather than write to your working
2889directory, you'd tell the index files about the changes in your
2890working directory (i.e. `git-update-index`).
2891
2892However, if you decide to jump to a new version, or check out somebody
2893else's version, or just restore a previous tree, you'd populate your
2894index file with read-tree, and then you need to check out the result
2895with
2896
2897-------------------------------------------------
2898$ git-checkout-index filename
2899-------------------------------------------------
2900
2901or, if you want to check out all of the index, use `-a`.
2902
2903NOTE! git-checkout-index normally refuses to overwrite old files, so
2904if you have an old version of the tree already checked out, you will
2905need to use the "-f" flag ('before' the "-a" flag or the filename) to
2906'force' the checkout.
2907
2908
2909Finally, there are a few odds and ends which are not purely moving
2910from one representation to the other:
2911
e34caace 2912[[tying-it-all-together]]
b181d57f
BF
2913Tying it all together
2914~~~~~~~~~~~~~~~~~~~~~
2915
2916To commit a tree you have instantiated with "git-write-tree", you'd
2917create a "commit" object that refers to that tree and the history
2918behind it - most notably the "parent" commits that preceded it in
2919history.
2920
2921Normally a "commit" has one parent: the previous state of the tree
2922before a certain change was made. However, sometimes it can have two
2923or more parent commits, in which case we call it a "merge", due to the
2924fact that such a commit brings together ("merges") two or more
2925previous states represented by other commits.
2926
2927In other words, while a "tree" represents a particular directory state
2928of a working directory, a "commit" represents that state in "time",
2929and explains how we got there.
2930
2931You create a commit object by giving it the tree that describes the
2932state at the time of the commit, and a list of parents:
2933
2934-------------------------------------------------
2935$ git-commit-tree <tree> -p <parent> [-p <parent2> ..]
2936-------------------------------------------------
2937
2938and then giving the reason for the commit on stdin (either through
2939redirection from a pipe or file, or by just typing it at the tty).
2940
2941git-commit-tree will return the name of the object that represents
2942that commit, and you should save it away for later use. Normally,
2943you'd commit a new `HEAD` state, and while git doesn't care where you
2944save the note about that state, in practice we tend to just write the
2945result to the file pointed at by `.git/HEAD`, so that we can always see
2946what the last committed state was.
2947
2948Here is an ASCII art by Jon Loeliger that illustrates how
2949various pieces fit together.
2950
2951------------
2952
2953 commit-tree
2954 commit obj
2955 +----+
2956 | |
2957 | |
2958 V V
2959 +-----------+
2960 | Object DB |
2961 | Backing |
2962 | Store |
2963 +-----------+
2964 ^
2965 write-tree | |
2966 tree obj | |
2967 | | read-tree
2968 | | tree obj
2969 V
2970 +-----------+
2971 | Index |
2972 | "cache" |
2973 +-----------+
2974 update-index ^
2975 blob obj | |
2976 | |
2977 checkout-index -u | | checkout-index
2978 stat | | blob obj
2979 V
2980 +-----------+
2981 | Working |
2982 | Directory |
2983 +-----------+
2984
2985------------
2986
2987
e34caace 2988[[examining-the-data]]
b181d57f
BF
2989Examining the data
2990------------------
2991
2992You can examine the data represented in the object database and the
2993index with various helper tools. For every object, you can use
2994gitlink:git-cat-file[1] to examine details about the
2995object:
2996
2997-------------------------------------------------
2998$ git-cat-file -t <objectname>
2999-------------------------------------------------
3000
3001shows the type of the object, and once you have the type (which is
3002usually implicit in where you find the object), you can use
3003
3004-------------------------------------------------
3005$ git-cat-file blob|tree|commit|tag <objectname>
3006-------------------------------------------------
3007
3008to show its contents. NOTE! Trees have binary content, and as a result
3009there is a special helper for showing that content, called
3010`git-ls-tree`, which turns the binary content into a more easily
3011readable form.
3012
3013It's especially instructive to look at "commit" objects, since those
3014tend to be small and fairly self-explanatory. In particular, if you
3015follow the convention of having the top commit name in `.git/HEAD`,
3016you can do
3017
3018-------------------------------------------------
3019$ git-cat-file commit HEAD
3020-------------------------------------------------
3021
3022to see what the top commit was.
3023
e34caace 3024[[merging-multiple-trees]]
b181d57f 3025Merging multiple trees
d19fbc3c
BF
3026----------------------
3027
b181d57f
BF
3028Git helps you do a three-way merge, which you can expand to n-way by
3029repeating the merge procedure arbitrary times until you finally
3030"commit" the state. The normal situation is that you'd only do one
3031three-way merge (two parents), and commit it, but if you like to, you
3032can do multiple parents in one go.
3033
3034To do a three-way merge, you need the two sets of "commit" objects
3035that you want to merge, use those to find the closest common parent (a
3036third "commit" object), and then use those commit objects to find the
3037state of the directory ("tree" object) at these points.
3038
3039To get the "base" for the merge, you first look up the common parent
3040of two commits with
3041
3042-------------------------------------------------
3043$ git-merge-base <commit1> <commit2>
3044-------------------------------------------------
3045
3046which will return you the commit they are both based on. You should
3047now look up the "tree" objects of those commits, which you can easily
3048do with (for example)
3049
3050-------------------------------------------------
3051$ git-cat-file commit <commitname> | head -1
3052-------------------------------------------------
3053
3054since the tree object information is always the first line in a commit
3055object.
3056
1191ee18 3057Once you know the three trees you are going to merge (the one "original"
c64415e2 3058tree, aka the common tree, and the two "result" trees, aka the branches
1191ee18
BF
3059you want to merge), you do a "merge" read into the index. This will
3060complain if it has to throw away your old index contents, so you should
b181d57f 3061make sure that you've committed those - in fact you would normally
1191ee18
BF
3062always do a merge against your last commit (which should thus match what
3063you have in your current index anyway).
b181d57f
BF
3064
3065To do the merge, do
3066
3067-------------------------------------------------
3068$ git-read-tree -m -u <origtree> <yourtree> <targettree>
3069-------------------------------------------------
3070
3071which will do all trivial merge operations for you directly in the
3072index file, and you can just write the result out with
3073`git-write-tree`.
3074
3075
e34caace 3076[[merging-multiple-trees-2]]
b181d57f
BF
3077Merging multiple trees, continued
3078---------------------------------
3079
3080Sadly, many merges aren't trivial. If there are files that have
3081been added.moved or removed, or if both branches have modified the
3082same file, you will be left with an index tree that contains "merge
3083entries" in it. Such an index tree can 'NOT' be written out to a tree
3084object, and you will have to resolve any such merge clashes using
3085other tools before you can write out the result.
3086
3087You can examine such index state with `git-ls-files --unmerged`
3088command. An example:
3089
3090------------------------------------------------
3091$ git-read-tree -m $orig HEAD $target
3092$ git-ls-files --unmerged
3093100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
3094100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
3095100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
3096------------------------------------------------
3097
3098Each line of the `git-ls-files --unmerged` output begins with
3099the blob mode bits, blob SHA1, 'stage number', and the
3100filename. The 'stage number' is git's way to say which tree it
3101came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`
3102tree, and stage3 `$target` tree.
3103
3104Earlier we said that trivial merges are done inside
3105`git-read-tree -m`. For example, if the file did not change
3106from `$orig` to `HEAD` nor `$target`, or if the file changed
3107from `$orig` to `HEAD` and `$orig` to `$target` the same way,
3108obviously the final outcome is what is in `HEAD`. What the
3109above example shows is that file `hello.c` was changed from
3110`$orig` to `HEAD` and `$orig` to `$target` in a different way.
3111You could resolve this by running your favorite 3-way merge
c64415e2
BF
3112program, e.g. `diff3`, `merge`, or git's own merge-file, on
3113the blob objects from these three stages yourself, like this:
b181d57f
BF
3114
3115------------------------------------------------
3116$ git-cat-file blob 263414f... >hello.c~1
3117$ git-cat-file blob 06fa6a2... >hello.c~2
3118$ git-cat-file blob cc44c73... >hello.c~3
c64415e2 3119$ git merge-file hello.c~2 hello.c~1 hello.c~3
b181d57f
BF
3120------------------------------------------------
3121
3122This would leave the merge result in `hello.c~2` file, along
3123with conflict markers if there are conflicts. After verifying
3124the merge result makes sense, you can tell git what the final
3125merge result for this file is by:
3126
3127-------------------------------------------------
3128$ mv -f hello.c~2 hello.c
3129$ git-update-index hello.c
3130-------------------------------------------------
3131
3132When a path is in unmerged state, running `git-update-index` for
3133that path tells git to mark the path resolved.
3134
3135The above is the description of a git merge at the lowest level,
3136to help you understand what conceptually happens under the hood.
3137In practice, nobody, not even git itself, uses three `git-cat-file`
3138for this. There is `git-merge-index` program that extracts the
3139stages to temporary files and calls a "merge" script on it:
3140
3141-------------------------------------------------
3142$ git-merge-index git-merge-one-file hello.c
3143-------------------------------------------------
3144
207dfa07 3145and that is what higher level `git merge -s resolve` is implemented with.
b181d57f 3146
e34caace 3147[[pack-files]]
b181d57f
BF
3148How git stores objects efficiently: pack files
3149----------------------------------------------
3150
3151We've seen how git stores each object in a file named after the
3152object's SHA1 hash.
3153
3154Unfortunately this system becomes inefficient once a project has a
3155lot of objects. Try this on an old project:
3156
3157------------------------------------------------
3158$ git count-objects
31596930 objects, 47620 kilobytes
3160------------------------------------------------
3161
3162The first number is the number of objects which are kept in
3163individual files. The second is the amount of space taken up by
3164those "loose" objects.
3165
3166You can save space and make git faster by moving these loose objects in
3167to a "pack file", which stores a group of objects in an efficient
3168compressed format; the details of how pack files are formatted can be
3169found in link:technical/pack-format.txt[technical/pack-format.txt].
3170
3171To put the loose objects into a pack, just run git repack:
3172
3173------------------------------------------------
3174$ git repack
3175Generating pack...
3176Done counting 6020 objects.
3177Deltifying 6020 objects.
3178 100% (6020/6020) done
3179Writing 6020 objects.
3180 100% (6020/6020) done
3181Total 6020, written 6020 (delta 4070), reused 0 (delta 0)
3182Pack pack-3e54ad29d5b2e05838c75df582c65257b8d08e1c created.
3183------------------------------------------------
3184
3185You can then run
3186
3187------------------------------------------------
3188$ git prune
3189------------------------------------------------
3190
3191to remove any of the "loose" objects that are now contained in the
3192pack. This will also remove any unreferenced objects (which may be
3193created when, for example, you use "git reset" to remove a commit).
3194You can verify that the loose objects are gone by looking at the
3195.git/objects directory or by running
3196
3197------------------------------------------------
3198$ git count-objects
31990 objects, 0 kilobytes
3200------------------------------------------------
3201
3202Although the object files are gone, any commands that refer to those
3203objects will work exactly as they did before.
3204
3205The gitlink:git-gc[1] command performs packing, pruning, and more for
3206you, so is normally the only high-level command you need.
d19fbc3c 3207
59723040 3208[[dangling-objects]]
21dcb3b7 3209Dangling objects
61b41790 3210----------------
21dcb3b7 3211
04e50e94 3212The gitlink:git-fsck[1] command will sometimes complain about dangling
21dcb3b7
BF
3213objects. They are not a problem.
3214
1191ee18
BF
3215The most common cause of dangling objects is that you've rebased a
3216branch, or you have pulled from somebody else who rebased a branch--see
3217<<cleaning-up-history>>. In that case, the old head of the original
59723040
BF
3218branch still exists, as does everything it pointed to. The branch
3219pointer itself just doesn't, since you replaced it with another one.
1191ee18 3220
59723040 3221There are also other situations that cause dangling objects. For
1191ee18
BF
3222example, a "dangling blob" may arise because you did a "git add" of a
3223file, but then, before you actually committed it and made it part of the
3224bigger picture, you changed something else in that file and committed
3225that *updated* thing - the old state that you added originally ends up
3226not being pointed to by any commit or tree, so it's now a dangling blob
3227object.
3228
3229Similarly, when the "recursive" merge strategy runs, and finds that
3230there are criss-cross merges and thus more than one merge base (which is
3231fairly unusual, but it does happen), it will generate one temporary
3232midway tree (or possibly even more, if you had lots of criss-crossing
3233merges and more than two merge bases) as a temporary internal merge
3234base, and again, those are real objects, but the end result will not end
3235up pointing to them, so they end up "dangling" in your repository.
3236
3237Generally, dangling objects aren't anything to worry about. They can
3238even be very useful: if you screw something up, the dangling objects can
3239be how you recover your old tree (say, you did a rebase, and realized
3240that you really didn't want to - you can look at what dangling objects
3241you have, and decide to reset your head to some old dangling state).
21dcb3b7 3242
59723040 3243For commits, you can just use:
21dcb3b7
BF
3244
3245------------------------------------------------
3246$ gitk <dangling-commit-sha-goes-here> --not --all
3247------------------------------------------------
3248
59723040
BF
3249This asks for all the history reachable from the given commit but not
3250from any branch, tag, or other reference. If you decide it's something
3251you want, you can always create a new reference to it, e.g.,
3252
3253------------------------------------------------
3254$ git branch recovered-branch <dangling-commit-sha-goes-here>
3255------------------------------------------------
3256
3257For blobs and trees, you can't do the same, but you can still examine
3258them. You can just do
21dcb3b7
BF
3259
3260------------------------------------------------
3261$ git show <dangling-blob/tree-sha-goes-here>
3262------------------------------------------------
3263
1191ee18
BF
3264to show what the contents of the blob were (or, for a tree, basically
3265what the "ls" for that directory was), and that may give you some idea
3266of what the operation was that left that dangling object.
21dcb3b7 3267
1191ee18
BF
3268Usually, dangling blobs and trees aren't very interesting. They're
3269almost always the result of either being a half-way mergebase (the blob
3270will often even have the conflict markers from a merge in it, if you
3271have had conflicting merges that you fixed up by hand), or simply
3272because you interrupted a "git fetch" with ^C or something like that,
3273leaving _some_ of the new objects in the object database, but just
3274dangling and useless.
21dcb3b7
BF
3275
3276Anyway, once you are sure that you're not interested in any dangling
3277state, you can just prune all unreachable objects:
3278
3279------------------------------------------------
3280$ git prune
3281------------------------------------------------
3282
1191ee18
BF
3283and they'll be gone. But you should only run "git prune" on a quiescent
3284repository - it's kind of like doing a filesystem fsck recovery: you
3285don't want to do that while the filesystem is mounted.
21dcb3b7 3286
04e50e94
BF
3287(The same is true of "git-fsck" itself, btw - but since
3288git-fsck never actually *changes* the repository, it just reports
3289on what it found, git-fsck itself is never "dangerous" to run.
21dcb3b7
BF
3290Running it while somebody is actually changing the repository can cause
3291confusing and scary messages, but it won't actually do anything bad. In
3292contrast, running "git prune" while somebody is actively changing the
3293repository is a *BAD* idea).
3294
126640af 3295[[birdview-on-the-source-code]]
a5fc33b4
BF
3296A birds-eye view of Git's source code
3297-------------------------------------
126640af 3298
a5fc33b4
BF
3299It is not always easy for new developers to find their way through Git's
3300source code. This section gives you a little guidance to show where to
3301start.
126640af 3302
a5fc33b4 3303A good place to start is with the contents of the initial commit, with:
126640af
JS
3304
3305----------------------------------------------------
a5fc33b4 3306$ git checkout e83c5163
126640af
JS
3307----------------------------------------------------
3308
a5fc33b4
BF
3309The initial revision lays the foundation for almost everything git has
3310today, but is small enough to read in one sitting.
126640af 3311
a5fc33b4
BF
3312Note that terminology has changed since that revision. For example, the
3313README in that revision uses the word "changeset" to describe what we
3314now call a <<def_commit_object,commit>>.
126640af 3315
a5fc33b4 3316Also, we do not call it "cache" any more, but "index", however, the
126640af
JS
3317file is still called `cache.h`. Remark: Not much reason to change it now,
3318especially since there is no good single name for it anyway, because it is
3319basically _the_ header file which is included by _all_ of Git's C sources.
3320
a5fc33b4
BF
3321If you grasp the ideas in that initial commit, you should check out a
3322more recent version and skim `cache.h`, `object.h` and `commit.h`.
126640af
JS
3323
3324In the early days, Git (in the tradition of UNIX) was a bunch of programs
3325which were extremely simple, and which you used in scripts, piping the
3326output of one into another. This turned out to be good for initial
3327development, since it was easier to test new things. However, recently
3328many of these parts have become builtins, and some of the core has been
3329"libified", i.e. put into libgit.a for performance, portability reasons,
3330and to avoid code duplication.
3331
3332By now, you know what the index is (and find the corresponding data
3333structures in `cache.h`), and that there are just a couple of object types
3334(blobs, trees, commits and tags) which inherit their common structure from
3335`struct object`, which is their first member (and thus, you can cast e.g.
3336`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e.
3337get at the object name and flags).
3338
3339Now is a good point to take a break to let this information sink in.
3340
3341Next step: get familiar with the object naming. Read <<naming-commits>>.
3342There are quite a few ways to name an object (and not only revisions!).
3343All of these are handled in `sha1_name.c`. Just have a quick look at
3344the function `get_sha1()`. A lot of the special handling is done by
3345functions like `get_sha1_basic()` or the likes.
3346
3347This is just to get you into the groove for the most libified part of Git:
3348the revision walker.
3349
3350Basically, the initial version of `git log` was a shell script:
3351
3352----------------------------------------------------------------
3353$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
3354 LESS=-S ${PAGER:-less}
3355----------------------------------------------------------------
3356
3357What does this mean?
3358
3359`git-rev-list` is the original version of the revision walker, which
3360_always_ printed a list of revisions to stdout. It is still functional,
3361and needs to, since most new Git programs start out as scripts using
3362`git-rev-list`.
3363
3364`git-rev-parse` is not as important any more; it was only used to filter out
3365options that were relevant for the different plumbing commands that were
3366called by the script.
3367
3368Most of what `git-rev-list` did is contained in `revision.c` and
3369`revision.h`. It wraps the options in a struct named `rev_info`, which
3370controls how and what revisions are walked, and more.
3371
3372The original job of `git-rev-parse` is now taken by the function
3373`setup_revisions()`, which parses the revisions and the common command line
3374options for the revision walker. This information is stored in the struct
3375`rev_info` for later consumption. You can do your own command line option
3376parsing after calling `setup_revisions()`. After that, you have to call
3377`prepare_revision_walk()` for initialization, and then you can get the
3378commits one by one with the function `get_revision()`.
3379
3380If you are interested in more details of the revision walking process,
3381just have a look at the first implementation of `cmd_log()`; call
3382`git-show v1.3.0~155^2~4` and scroll down to that function (note that you
3383no longer need to call `setup_pager()` directly).
3384
3385Nowadays, `git log` is a builtin, which means that it is _contained_ in the
3386command `git`. The source side of a builtin is
3387
3388- a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`,
3389 and declared in `builtin.h`,
3390
3391- an entry in the `commands[]` array in `git.c`, and
3392
3393- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
3394
3395Sometimes, more than one builtin is contained in one source file. For
3396example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`,
3397since they share quite a bit of code. In that case, the commands which are
3398_not_ named like the `.c` file in which they live have to be listed in
3399`BUILT_INS` in the `Makefile`.
3400
3401`git log` looks more complicated in C than it does in the original script,
3402but that allows for a much greater flexibility and performance.
3403
3404Here again it is a good point to take a pause.
3405
3406Lesson three is: study the code. Really, it is the best way to learn about
3407the organization of Git (after you know the basic concepts).
3408
3409So, think about something which you are interested in, say, "how can I
3410access a blob just knowing the object name of it?". The first step is to
3411find a Git command with which you can do it. In this example, it is either
3412`git show` or `git cat-file`.
3413
3414For the sake of clarity, let's stay with `git cat-file`, because it
3415
3416- is plumbing, and
3417
3418- was around even in the initial commit (it literally went only through
3419 some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c`
3420 when made a builtin, and then saw less than 10 versions).
3421
3422So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what
3423it does.
3424
3425------------------------------------------------------------------
3426 git_config(git_default_config);
3427 if (argc != 3)
3428 usage("git-cat-file [-t|-s|-e|-p|<type>] <sha1>");
3429 if (get_sha1(argv[2], sha1))
3430 die("Not a valid object name %s", argv[2]);
3431------------------------------------------------------------------
3432
3433Let's skip over the obvious details; the only really interesting part
3434here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an
3435object name, and if it refers to an object which is present in the current
3436repository, it writes the resulting SHA-1 into the variable `sha1`.
3437
3438Two things are interesting here:
3439
3440- `get_sha1()` returns 0 on _success_. This might surprise some new
3441 Git hackers, but there is a long tradition in UNIX to return different
3442 negative numbers in case of different errors -- and 0 on success.
3443
3444- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
a5fc33b4 3445 char \*`, but is actually expected to be a pointer to `unsigned
126640af 3446 char[20]`. This variable will contain the 160-bit SHA-1 of the given
a5fc33b4 3447 commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it
126640af 3448 is the binary representation, as opposed to the ASCII representation in
a5fc33b4 3449 hex characters, which is passed as `char *`.
126640af
JS
3450
3451You will see both of these things throughout the code.
3452
3453Now, for the meat:
3454
3455-----------------------------------------------------------------------------
3456 case 0:
3457 buf = read_object_with_reference(sha1, argv[1], &size, NULL);
3458-----------------------------------------------------------------------------
3459
3460This is how you read a blob (actually, not only a blob, but any type of
3461object). To know how the function `read_object_with_reference()` actually
3462works, find the source code for it (something like `git grep
3463read_object_with | grep ":[a-z]"` in the git repository), and read
3464the source.
3465
3466To find out how the result can be used, just read on in `cmd_cat_file()`:
3467
3468-----------------------------------
3469 write_or_die(1, buf, size);
3470-----------------------------------
3471
3472Sometimes, you do not know where to look for a feature. In many such cases,
3473it helps to search through the output of `git log`, and then `git show` the
3474corresponding commit.
3475
3476Example: If you know that there was some test case for `git bundle`, but
3477do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
3478does not illustrate the point!):
3479
3480------------------------
3481$ git log --no-merges t/
3482------------------------
3483
3484In the pager (`less`), just search for "bundle", go a few lines back,
3485and see that it is in commit 18449ab0... Now just copy this object name,
3486and paste it into the command line
3487
3488-------------------
3489$ git show 18449ab0
3490-------------------
3491
3492Voila.
3493
3494Another example: Find out what to do in order to make some script a
3495builtin:
3496
3497-------------------------------------------------
3498$ git log --no-merges --diff-filter=A builtin-*.c
3499-------------------------------------------------
3500
3501You see, Git is actually the best tool to find out about the source of Git
3502itself!
3503
e34caace 3504[[glossary]]
d19fbc3c
BF
3505include::glossary.txt[]
3506
2624d9a5
BF
3507[[git-quick-start]]
3508Appendix A: Git Quick Start
3509===========================
3510
3511This is a quick summary of the major commands; the following chapters
3512will explain how these work in more detail.
3513
3514[[quick-creating-a-new-repository]]
3515Creating a new repository
3516-------------------------
3517
3518From a tarball:
3519
3520-----------------------------------------------
3521$ tar xzf project.tar.gz
3522$ cd project
3523$ git init
3524Initialized empty Git repository in .git/
3525$ git add .
3526$ git commit
3527-----------------------------------------------
3528
3529From a remote repository:
3530
3531-----------------------------------------------
3532$ git clone git://example.com/pub/project.git
3533$ cd project
3534-----------------------------------------------
3535
3536[[managing-branches]]
3537Managing branches
3538-----------------
3539
3540-----------------------------------------------
3541$ git branch # list all local branches in this repo
3542$ git checkout test # switch working directory to branch "test"
3543$ git branch new # create branch "new" starting at current HEAD
3544$ git branch -d new # delete branch "new"
3545-----------------------------------------------
3546
3547Instead of basing new branch on current HEAD (the default), use:
3548
3549-----------------------------------------------
3550$ git branch new test # branch named "test"
3551$ git branch new v2.6.15 # tag named v2.6.15
3552$ git branch new HEAD^ # commit before the most recent
3553$ git branch new HEAD^^ # commit before that
3554$ git branch new test~10 # ten commits before tip of branch "test"
3555-----------------------------------------------
3556
3557Create and switch to a new branch at the same time:
3558
3559-----------------------------------------------
3560$ git checkout -b new v2.6.15
3561-----------------------------------------------
3562
3563Update and examine branches from the repository you cloned from:
3564
3565-----------------------------------------------
3566$ git fetch # update
3567$ git branch -r # list
3568 origin/master
3569 origin/next
3570 ...
3571$ git checkout -b masterwork origin/master
3572-----------------------------------------------
3573
3574Fetch a branch from a different repository, and give it a new
3575name in your repository:
3576
3577-----------------------------------------------
3578$ git fetch git://example.com/project.git theirbranch:mybranch
3579$ git fetch git://example.com/project.git v2.6.15:mybranch
3580-----------------------------------------------
3581
3582Keep a list of repositories you work with regularly:
3583
3584-----------------------------------------------
3585$ git remote add example git://example.com/project.git
3586$ git remote # list remote repositories
3587example
3588origin
3589$ git remote show example # get details
3590* remote example
3591 URL: git://example.com/project.git
3592 Tracked remote branches
3593 master next ...
3594$ git fetch example # update bra