user-manual.txt: render ASCII art correctly under Asciidoctor
[git/git.git] / Documentation / user-manual.txt
CommitLineData
fd5b820d 1= Git User Manual
99eaefdd
BF
2
3Git is a fast distributed revision control system.
4
02783075 5This manual is designed to be readable by someone with basic UNIX
2de9b711 6command-line skills, but no previous knowledge of Git.
d19fbc3c 7
2624d9a5
BF
8<<repositories-and-branches>> and <<exploring-git-history>> explain how
9to fetch and study a project using git--read these chapters to learn how
10to build and test a particular version of a software project, search for
11regressions, and so on.
ef89f701 12
2624d9a5 13People needing to do actual development will also want to read
aa971cb9 14<<Developing-With-git>> and <<sharing-development>>.
6bd9b682
BF
15
16Further chapters cover more specialized topics.
17
d19fbc3c 18Comprehensive reference documentation is available through the man
b3d98887 19pages, or linkgit:git-help[1] command. For example, for the command
1249d8ad 20`git clone <repo>`, you can either use:
d19fbc3c
BF
21
22------------------------------------------------
23$ man git-clone
24------------------------------------------------
25
b3d98887
CC
26or:
27
28------------------------------------------------
29$ git help clone
30------------------------------------------------
31
32With the latter, you can use the manual viewer of your choice; see
33linkgit:git-help[1] for more information.
34
2de9b711 35See also <<git-quick-start>> for a brief overview of Git commands,
2624d9a5 36without any explanation.
b181d57f 37
99f171bb 38Finally, see <<todo>> for ways that you can help make this manual more
2624d9a5 39complete.
b181d57f 40
b181d57f 41
e34caace 42[[repositories-and-branches]]
fd5b820d 43== Repositories and Branches
d19fbc3c 44
e34caace 45[[how-to-get-a-git-repository]]
fd5b820d 46=== How to get a Git repository
d19fbc3c 47
2de9b711 48It will be useful to have a Git repository to experiment with as you
d19fbc3c
BF
49read this manual.
50
5162e697 51The best way to get one is by using the linkgit:git-clone[1] command to
a5f90f31
BF
52download a copy of an existing repository. If you don't already have a
53project in mind, here are some interesting examples:
d19fbc3c
BF
54
55------------------------------------------------
4b9ced27 56 # Git itself (approx. 40MB download):
d19fbc3c 57$ git clone git://git.kernel.org/pub/scm/git/git.git
4b9ced27
TK
58 # the Linux kernel (approx. 640MB download):
59$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
d19fbc3c
BF
60------------------------------------------------
61
62The initial clone may be time-consuming for a large project, but you
63will only need to clone once.
64
283efb01
TK
65The clone command creates a new directory named after the project
66(`git` or `linux` in the examples above). After you cd into this
d19fbc3c 67directory, you will see that it contains a copy of the project files,
0c4a33b5 68called the <<def_working_tree,working tree>>, together with a special
1249d8ad 69top-level directory named `.git`, which contains all the information
0c4a33b5 70about the history of the project.
d19fbc3c 71
e34caace 72[[how-to-check-out]]
fd5b820d 73=== How to check out a different version of a project
d19fbc3c 74
a2ef9d63
BF
75Git is best thought of as a tool for storing the history of a collection
76of files. It stores the history as a compressed collection of
2de9b711 77interrelated snapshots of the project's contents. In Git each such
a2ef9d63 78version is called a <<def_commit,commit>>.
d19fbc3c 79
0c4a33b5
BF
80Those snapshots aren't necessarily all arranged in a single line from
81oldest to newest; instead, work may simultaneously proceed along
57283291 82parallel lines of development, called <<def_branch,branches>>, which may
0c4a33b5
BF
83merge and diverge.
84
2de9b711 85A single Git repository can track development on multiple branches. It
0c4a33b5 86does this by keeping a list of <<def_head,heads>> which reference the
5162e697 87latest commit on each branch; the linkgit:git-branch[1] command shows
81b6c950 88you the list of branch heads:
d19fbc3c
BF
89
90------------------------------------------------
91$ git branch
92* master
93------------------------------------------------
94
4f752407
BF
95A freshly cloned repository contains a single branch head, by default
96named "master", with the working directory initialized to the state of
97the project referred to by that branch head.
d19fbc3c 98
81b6c950
BF
99Most projects also use <<def_tag,tags>>. Tags, like heads, are
100references into the project's history, and can be listed using the
5162e697 101linkgit:git-tag[1] command:
d19fbc3c
BF
102
103------------------------------------------------
104$ git tag -l
105v2.6.11
106v2.6.11-tree
107v2.6.12
108v2.6.12-rc2
109v2.6.12-rc3
110v2.6.12-rc4
111v2.6.12-rc5
112v2.6.12-rc6
113v2.6.13
114...
115------------------------------------------------
116
fe4b3e59 117Tags are expected to always point at the same version of a project,
81b6c950 118while heads are expected to advance as development progresses.
fe4b3e59 119
81b6c950 120Create a new branch head pointing to one of these versions and check it
328c6cb8 121out using linkgit:git-switch[1]:
d19fbc3c
BF
122
123------------------------------------------------
328c6cb8 124$ git switch -c new v2.6.13
d19fbc3c
BF
125------------------------------------------------
126
127The working directory then reflects the contents that the project had
5162e697 128when it was tagged v2.6.13, and linkgit:git-branch[1] shows two
d19fbc3c
BF
129branches, with an asterisk marking the currently checked-out branch:
130
131------------------------------------------------
132$ git branch
133 master
134* new
135------------------------------------------------
136
137If you decide that you'd rather see version 2.6.17, you can modify
138the current branch to point at v2.6.17 instead, with
139
140------------------------------------------------
141$ git reset --hard v2.6.17
142------------------------------------------------
143
81b6c950 144Note that if the current branch head was your only reference to a
d19fbc3c 145particular point in history, then resetting that branch may leave you
81b6c950
BF
146with no way to find the history it used to point to; so use this command
147carefully.
d19fbc3c 148
e34caace 149[[understanding-commits]]
fd5b820d 150=== Understanding History: Commits
d19fbc3c
BF
151
152Every change in the history of a project is represented by a commit.
5162e697 153The linkgit:git-show[1] command shows the most recent commit on the
d19fbc3c
BF
154current branch:
155
156------------------------------------------------
157$ git show
e2618ff4
BF
158commit 17cf781661e6d38f737f15f53ab552f1e95960d7
159Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>
160Date: Tue Apr 19 14:11:06 2005 -0700
161
162 Remove duplicate getenv(DB_ENVIRONMENT) call
163
164 Noted by Tony Luck.
165
166diff --git a/init-db.c b/init-db.c
167index 65898fa..b002dc6 100644
168--- a/init-db.c
169+++ b/init-db.c
170@@ -7,7 +7,7 @@
d19fbc3c 171
e2618ff4
BF
172 int main(int argc, char **argv)
173 {
174- char *sha1_dir = getenv(DB_ENVIRONMENT), *path;
175+ char *sha1_dir, *path;
176 int len, i;
177
178 if (mkdir(".git", 0755) < 0) {
d19fbc3c
BF
179------------------------------------------------
180
181As you can see, a commit shows who made the latest change, what they
182did, and why.
183
35121930 184Every commit has a 40-hexdigit id, sometimes called the "object name" or the
1249d8ad 185"SHA-1 id", shown on the first line of the `git show` output. You can usually
35121930
BF
186refer to a commit by a shorter name, such as a tag or a branch name, but this
187longer name can also be useful. Most importantly, it is a globally unique
188name for this commit: so if you tell somebody else the object name (for
189example in email), then you are guaranteed that name will refer to the same
190commit in their repository that it does in yours (assuming their repository
191has that commit at all). Since the object name is computed as a hash over the
192contents of the commit, you are guaranteed that the commit can never change
193without its name also changing.
194
2de9b711 195In fact, in <<git-concepts>> we shall see that everything stored in Git
35121930
BF
196history, including file data and directory contents, is stored in an object
197with a name that is a hash of its contents.
d19fbc3c 198
e34caace 199[[understanding-reachability]]
fd5b820d 200==== Understanding history: commits, parents, and reachability
d19fbc3c
BF
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
2de9b711 207However, the commits do not form a simple list; Git allows lines of
d19fbc3c
BF
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
5162e697 214The best way to see how this works is using the linkgit:gitk[1]
2de9b711 215command; running gitk now on a Git repository and looking for merge
ddd4ddef 216commits will help understand how Git organizes history.
d19fbc3c
BF
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
02783075 220that Y is a descendant of X, or that there is a chain of parents
d19fbc3c
BF
221leading from commit Y to commit X.
222
e34caace 223[[history-diagrams]]
fd5b820d 224==== Understanding history: History diagrams
d19fbc3c 225
2de9b711 226We will sometimes represent Git history using diagrams like the one
d19fbc3c
BF
227below. Commits are shown as "o", and the links between them with
228lines drawn with - / and \. Time goes left to right:
229
1dc71a91
BF
230
231................................................
d19fbc3c
BF
232 o--o--o <-- Branch A
233 /
234 o--o--o <-- master
235 \
236 o--o--o <-- Branch B
1dc71a91 237................................................
d19fbc3c
BF
238
239If we need to talk about a particular commit, the character "o" may
240be replaced with another letter or number.
241
e34caace 242[[what-is-a-branch]]
fd5b820d 243==== Understanding history: What is a branch?
d19fbc3c 244
81b6c950
BF
245When we need to be precise, we will use the word "branch" to mean a line
246of development, and "branch head" (or just "head") to mean a reference
247to the most recent commit on a branch. In the example above, the branch
248head named "A" is a pointer to one particular commit, but we refer to
249the line of three commits leading up to that point as all being part of
d19fbc3c
BF
250"branch A".
251
81b6c950
BF
252However, when no confusion will result, we often just use the term
253"branch" both for branches and for branch heads.
d19fbc3c 254
e34caace 255[[manipulating-branches]]
fd5b820d 256=== Manipulating branches
d19fbc3c
BF
257
258Creating, deleting, and modifying branches is quick and easy; here's
259a summary of the commands:
260
1249d8ad 261`git branch`::
df47da75 262 list all branches.
1249d8ad
TK
263`git branch <branch>`::
264 create a new branch named `<branch>`, referencing the same
df47da75 265 point in history as the current branch.
1249d8ad
TK
266`git branch <branch> <start-point>`::
267 create a new branch named `<branch>`, referencing
268 `<start-point>`, which may be specified any way you like,
df47da75 269 including using a branch name or a tag name.
1249d8ad 270`git branch -d <branch>`::
df47da75
TA
271 delete the branch `<branch>`; if the branch is not fully
272 merged in its upstream branch or contained in the current branch,
273 this command will fail with a warning.
1249d8ad 274`git branch -D <branch>`::
df47da75 275 delete the branch `<branch>` irrespective of its merged status.
328c6cb8 276`git switch <branch>`::
1249d8ad 277 make the current branch `<branch>`, updating the working
df47da75 278 directory to reflect the version referenced by `<branch>`.
328c6cb8 279`git switch -c <new> <start-point>`::
1249d8ad 280 create a new branch `<new>` referencing `<start-point>`, and
d19fbc3c
BF
281 check it out.
282
72a76c95 283The special symbol "HEAD" can always be used to refer to the current
1249d8ad
TK
284branch. In fact, Git uses a file named `HEAD` in the `.git` directory
285to remember which branch is current:
72a76c95
BF
286
287------------------------------------------------
288$ cat .git/HEAD
289ref: refs/heads/master
290------------------------------------------------
291
25d9f3fa 292[[detached-head]]
fd5b820d 293=== Examining an old version without creating a new branch
72a76c95 294
328c6cb8
NTND
295The `git switch` command normally expects a branch head, but will also
296accept an arbitrary commit when invoked with --detach; for example,
297you can check out the commit referenced by a tag:
72a76c95
BF
298
299------------------------------------------------
328c6cb8 300$ git switch --detach v2.6.17
95f9be55
TA
301Note: checking out 'v2.6.17'.
302
303You are in 'detached HEAD' state. You can look around, make experimental
304changes and commit them, and you can discard any commits you make in this
328c6cb8 305state without impacting any branches by performing another switch.
95f9be55
TA
306
307If you want to create a new branch to retain commits you create, you may
328c6cb8 308do so (now or later) by using -c with the switch command again. Example:
95f9be55 309
328c6cb8 310 git switch -c new_branch_name
95f9be55 311
ca69d4d5 312HEAD is now at 427abfa Linux v2.6.17
72a76c95
BF
313------------------------------------------------
314
a6e5ef7d 315The HEAD then refers to the SHA-1 of the commit instead of to a branch,
72a76c95
BF
316and git branch shows that you are no longer on a branch:
317
318------------------------------------------------
319$ cat .git/HEAD
320427abfa28afedffadfca9dd8b067eb6d36bac53f
953f3d6f 321$ git branch
95f9be55 322* (detached from v2.6.17)
72a76c95
BF
323 master
324------------------------------------------------
325
326In this case we say that the HEAD is "detached".
327
953f3d6f
BF
328This is an easy way to check out a particular version without having to
329make up a name for the new branch. You can still create a new branch
330(or tag) for this version later if you decide to.
d19fbc3c 331
e34caace 332[[examining-remote-branches]]
fd5b820d 333=== Examining branches from a remote repository
d19fbc3c
BF
334
335The "master" branch that was created at the time you cloned is a copy
336of the HEAD in the repository that you cloned from. That repository
337may also have had other branches, though, and your local repository
66a062a1
MM
338keeps branches which track each of those remote branches, called
339remote-tracking branches, which you
1249d8ad 340can view using the `-r` option to linkgit:git-branch[1]:
d19fbc3c
BF
341
342------------------------------------------------
343$ git branch -r
344 origin/HEAD
345 origin/html
346 origin/maint
347 origin/man
348 origin/master
349 origin/next
350 origin/pu
351 origin/todo
352------------------------------------------------
353
66a062a1
MM
354In this example, "origin" is called a remote repository, or "remote"
355for short. The branches of this repository are called "remote
356branches" from our point of view. The remote-tracking branches listed
357above were created based on the remote branches at clone time and will
1249d8ad 358be updated by `git fetch` (hence `git pull`) and `git push`. See
66a062a1
MM
359<<Updating-a-repository-With-git-fetch>> for details.
360
45dfd403
JN
361You might want to build on one of these remote-tracking branches
362on a branch of your own, just as you would for a tag:
d19fbc3c
BF
363
364------------------------------------------------
328c6cb8 365$ git switch -c my-todo-copy origin/todo
d19fbc3c
BF
366------------------------------------------------
367
1249d8ad 368You can also check out `origin/todo` directly to examine it or
45dfd403
JN
369write a one-off patch. See <<detached-head,detached head>>.
370
2de9b711 371Note that the name "origin" is just the name that Git uses by default
d19fbc3c
BF
372to refer to the repository that you cloned from.
373
374[[how-git-stores-references]]
fd5b820d 375=== Naming branches, tags, and other references
d19fbc3c
BF
376
377Branches, remote-tracking branches, and tags are all references to
f60b9642 378commits. All references are named with a slash-separated path name
1249d8ad 379starting with `refs`; the names we've been using so far are actually
f60b9642 380shorthand:
d19fbc3c 381
1249d8ad
TK
382 - The branch `test` is short for `refs/heads/test`.
383 - The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
384 - `origin/master` is short for `refs/remotes/origin/master`.
d19fbc3c 385
f60b9642
BF
386The full name is occasionally useful if, for example, there ever
387exists a tag and a branch with the same name.
d19fbc3c 388
1249d8ad 389(Newly created refs are actually stored in the `.git/refs` directory,
fc74ecc1
BF
390under the path given by their name. However, for efficiency reasons
391they may also be packed together in a single file; see
5162e697 392linkgit:git-pack-refs[1]).
fc74ecc1 393
c64415e2
BF
394As another useful shortcut, the "HEAD" of a repository can be referred
395to just using the name of that repository. So, for example, "origin"
396is usually a shortcut for the HEAD branch in the repository "origin".
d19fbc3c 397
2de9b711 398For the complete list of paths which Git checks for references, and
f60b9642
BF
399the order it uses to decide which to choose when there are multiple
400references with the same shorthand name, see the "SPECIFYING
9d83e382 401REVISIONS" section of linkgit:gitrevisions[7].
d19fbc3c 402
aa971cb9 403[[Updating-a-repository-With-git-fetch]]
fd5b820d 404=== Updating a repository with git fetch
d19fbc3c 405
3c735e07
JM
406After you clone a repository and commit a few changes of your own, you
407may wish to check the original repository for updates.
d19fbc3c 408
3c735e07
JM
409The `git-fetch` command, with no arguments, will update all of the
410remote-tracking branches to the latest version found in the original
d19fbc3c
BF
411repository. It will not touch any of your own branches--not even the
412"master" branch that was created for you on clone.
413
e34caace 414[[fetching-branches]]
fd5b820d 415=== Fetching branches from other repositories
d5cd5de4
BF
416
417You can also track branches from repositories other than the one you
5162e697 418cloned from, using linkgit:git-remote[1]:
d5cd5de4
BF
419
420-------------------------------------------------
34a25d4c
TK
421$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
422$ git fetch staging
423...
424From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
425 * [new branch] master -> staging/master
426 * [new branch] staging-linus -> staging/staging-linus
427 * [new branch] staging-next -> staging/staging-next
d5cd5de4
BF
428-------------------------------------------------
429
430New remote-tracking branches will be stored under the shorthand name
34a25d4c 431that you gave `git remote add`, in this case `staging`:
d5cd5de4
BF
432
433-------------------------------------------------
434$ git branch -r
34a25d4c
TK
435 origin/HEAD -> origin/master
436 origin/master
437 staging/master
438 staging/staging-linus
439 staging/staging-next
d5cd5de4
BF
440-------------------------------------------------
441
1249d8ad
TK
442If you run `git fetch <remote>` later, the remote-tracking branches
443for the named `<remote>` will be updated.
d5cd5de4 444
1249d8ad 445If you examine the file `.git/config`, you will see that Git has added
d5cd5de4
BF
446a new stanza:
447
448-------------------------------------------------
449$ cat .git/config
450...
34a25d4c
TK
451[remote "staging"]
452 url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git
453 fetch = +refs/heads/*:refs/remotes/staging/*
d5cd5de4
BF
454...
455-------------------------------------------------
456
2de9b711 457This is what causes Git to track the remote's branches; you may modify
1249d8ad 458or delete these configuration options by editing `.git/config` with a
fc90c536 459text editor. (See the "CONFIGURATION FILE" section of
5162e697 460linkgit:git-config[1] for details.)
d5cd5de4 461
e34caace 462[[exploring-git-history]]
fd5b820d 463== Exploring Git history
d19fbc3c
BF
464
465Git is best thought of as a tool for storing the history of a
466collection of files. It does this by storing compressed snapshots of
1130845b 467the contents of a file hierarchy, together with "commits" which show
d19fbc3c
BF
468the relationships between these snapshots.
469
470Git provides extremely flexible and fast tools for exploring the
471history of a project.
472
aacd404e 473We start with one specialized tool that is useful for finding the
d19fbc3c
BF
474commit that introduced a bug into a project.
475
e34caace 476[[using-bisect]]
fd5b820d 477=== How to use bisect to find a regression
d19fbc3c
BF
478
479Suppose version 2.6.18 of your project worked, but the version at
480"master" crashes. Sometimes the best way to find the cause of such a
481regression is to perform a brute-force search through the project's
482history to find the particular commit that caused the problem. The
5162e697 483linkgit:git-bisect[1] command can help you do this:
d19fbc3c
BF
484
485-------------------------------------------------
486$ git bisect start
487$ git bisect good v2.6.18
488$ git bisect bad master
489Bisecting: 3537 revisions left to test after this
490[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
491-------------------------------------------------
492
1249d8ad 493If you run `git branch` at this point, you'll see that Git has
0e25790f 494temporarily moved you in "(no branch)". HEAD is now detached from any
f61d89e1 495branch and points directly to a commit (with commit id 65934) that
0e25790f
CC
496is reachable from "master" but not from v2.6.18. Compile and test it,
497and see whether it crashes. Assume it does crash. Then:
d19fbc3c
BF
498
499-------------------------------------------------
500$ git bisect bad
501Bisecting: 1769 revisions left to test after this
502[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
503-------------------------------------------------
504
2de9b711 505checks out an older version. Continue like this, telling Git at each
d19fbc3c
BF
506stage whether the version it gives you is good or bad, and notice
507that the number of revisions left to test is cut approximately in
508half each time.
509
510After about 13 tests (in this case), it will output the commit id of
511the guilty commit. You can then examine the commit with
5162e697 512linkgit:git-show[1], find out who wrote it, and mail them your bug
d19fbc3c
BF
513report with the commit id. Finally, run
514
515-------------------------------------------------
516$ git bisect reset
517-------------------------------------------------
518
0e25790f 519to return you to the branch you were on before.
d19fbc3c 520
6127c086 521Note that the version which `git bisect` checks out for you at each
d19fbc3c
BF
522point is just a suggestion, and you're free to try a different
523version if you think it would be a good idea. For example,
524occasionally you may land on a commit that broke something unrelated;
525run
526
527-------------------------------------------------
04483524 528$ git bisect visualize
d19fbc3c
BF
529-------------------------------------------------
530
531which will run gitk and label the commit it chose with a marker that
843c81dc 532says "bisect". Choose a safe-looking commit nearby, note its commit
d19fbc3c
BF
533id, and check it out with:
534
535-------------------------------------------------
f61d89e1 536$ git reset --hard fb47ddb2db
d19fbc3c
BF
537-------------------------------------------------
538
1249d8ad 539then test, run `bisect good` or `bisect bad` as appropriate, and
d19fbc3c
BF
540continue.
541
1249d8ad 542Instead of `git bisect visualize` and then `git reset --hard
f61d89e1 543fb47ddb2db`, you might just want to tell Git that you want to skip
0e25790f
CC
544the current commit:
545
546-------------------------------------------------
547$ git bisect skip
548-------------------------------------------------
549
2de9b711 550In this case, though, Git may not eventually be able to tell the first
a0178ae2 551bad one between some first skipped commits and a later bad commit.
0e25790f
CC
552
553There are also ways to automate the bisecting process if you have a
554test script that can tell a good from a bad commit. See
1249d8ad
TK
555linkgit:git-bisect[1] for more information about this and other `git
556bisect` features.
0e25790f 557
e34caace 558[[naming-commits]]
fd5b820d 559=== Naming commits
d19fbc3c
BF
560
561We have seen several ways of naming commits already:
562
d55ae921 563 - 40-hexdigit object name
d19fbc3c
BF
564 - branch name: refers to the commit at the head of the given
565 branch
566 - tag name: refers to the commit pointed to by the given tag
567 (we've seen branches and tags are special cases of
568 <<how-git-stores-references,references>>).
569 - HEAD: refers to the head of the current branch
570
eb6ae7f4 571There are many more; see the "SPECIFYING REVISIONS" section of the
9d83e382 572linkgit:gitrevisions[7] man page for the complete list of ways to
d19fbc3c
BF
573name revisions. Some examples:
574
575-------------------------------------------------
d55ae921 576$ git show fb47ddb2 # the first few characters of the object name
d19fbc3c
BF
577 # are usually enough to specify it uniquely
578$ git show HEAD^ # the parent of the HEAD commit
579$ git show HEAD^^ # the grandparent
580$ git show HEAD~4 # the great-great-grandparent
581-------------------------------------------------
582
583Recall that merge commits may have more than one parent; by default,
1249d8ad 584`^` and `~` follow the first parent listed in the commit, but you can
d19fbc3c
BF
585also choose:
586
587-------------------------------------------------
588$ git show HEAD^1 # show the first parent of HEAD
589$ git show HEAD^2 # show the second parent of HEAD
590-------------------------------------------------
591
592In addition to HEAD, there are several other special names for
593commits:
594
595Merges (to be discussed later), as well as operations such as
6127c086 596`git reset`, which change the currently checked-out commit, generally
d19fbc3c
BF
597set ORIG_HEAD to the value HEAD had before the current operation.
598
6127c086
FC
599The `git fetch` operation always stores the head of the last fetched
600branch in FETCH_HEAD. For example, if you run `git fetch` without
d19fbc3c
BF
601specifying a local branch as the target of the operation
602
603-------------------------------------------------
604$ git fetch git://example.com/proj.git theirbranch
605-------------------------------------------------
606
607the fetched commits will still be available from FETCH_HEAD.
608
609When we discuss merges we'll also see the special name MERGE_HEAD,
610which refers to the other branch that we're merging in to the current
611branch.
612
5162e697 613The linkgit:git-rev-parse[1] command is a low-level command that is
d55ae921
BF
614occasionally useful for translating some name for a commit to the object
615name for that commit:
aec053bb
BF
616
617-------------------------------------------------
618$ git rev-parse origin
619e05db0fd4f31dde7005f075a84f96b360d05984b
620-------------------------------------------------
621
e34caace 622[[creating-tags]]
fd5b820d 623=== Creating tags
d19fbc3c
BF
624
625We can also create a tag to refer to a particular commit; after
626running
627
628-------------------------------------------------
04483524 629$ git tag stable-1 1b2e1d63ff
d19fbc3c
BF
630-------------------------------------------------
631
1249d8ad 632You can use `stable-1` to refer to the commit 1b2e1d63ff.
d19fbc3c 633
c64415e2
BF
634This creates a "lightweight" tag. If you would also like to include a
635comment with the tag, and possibly sign it cryptographically, then you
5162e697 636should create a tag object instead; see the linkgit:git-tag[1] man page
c64415e2 637for details.
d19fbc3c 638
e34caace 639[[browsing-revisions]]
fd5b820d 640=== Browsing revisions
d19fbc3c 641
5162e697 642The linkgit:git-log[1] command can show lists of commits. On its
d19fbc3c
BF
643own, it shows all commits reachable from the parent commit; but you
644can also make more specific requests:
645
646-------------------------------------------------
647$ git log v2.5.. # commits since (not reachable from) v2.5
648$ git log test..master # commits reachable from master but not test
649$ git log master..test # ...reachable from test but not master
650$ git log master...test # ...reachable from either test or master,
651 # but not both
652$ git log --since="2 weeks ago" # commits from the last 2 weeks
653$ git log Makefile # commits which modify Makefile
654$ git log fs/ # ... which modify any file under fs/
655$ git log -S'foo()' # commits which add or remove any file data
656 # matching the string 'foo()'
657-------------------------------------------------
658
659And of course you can combine all of these; the following finds
1249d8ad 660commits since v2.5 which touch the `Makefile` or any file under `fs`:
d19fbc3c
BF
661
662-------------------------------------------------
663$ git log v2.5.. Makefile fs/
664-------------------------------------------------
665
666You can also ask git log to show patches:
667
668-------------------------------------------------
669$ git log -p
670-------------------------------------------------
671
1249d8ad 672See the `--pretty` option in the linkgit:git-log[1] man page for more
d19fbc3c
BF
673display options.
674
675Note that git log starts with the most recent commit and works
2de9b711 676backwards through the parents; however, since Git history can contain
3dff5379 677multiple independent lines of development, the particular order that
d19fbc3c
BF
678commits are listed in may be somewhat arbitrary.
679
e34caace 680[[generating-diffs]]
fd5b820d 681=== Generating diffs
d19fbc3c
BF
682
683You can generate diffs between any two versions using
5162e697 684linkgit:git-diff[1]:
d19fbc3c
BF
685
686-------------------------------------------------
687$ git diff master..test
688-------------------------------------------------
689
5b98d9bc
BF
690That will produce the diff between the tips of the two branches. If
691you'd prefer to find the diff from their common ancestor to test, you
692can use three dots instead of two:
693
694-------------------------------------------------
695$ git diff master...test
696-------------------------------------------------
697
698Sometimes what you want instead is a set of patches; for this you can
5162e697 699use linkgit:git-format-patch[1]:
d19fbc3c
BF
700
701-------------------------------------------------
702$ git format-patch master..test
703-------------------------------------------------
704
705will generate a file with a patch for each commit reachable from test
5b98d9bc 706but not from master.
d19fbc3c 707
e34caace 708[[viewing-old-file-versions]]
fd5b820d 709=== Viewing old file versions
d19fbc3c
BF
710
711You can always view an old version of a file by just checking out the
712correct revision first. But sometimes it is more convenient to be
713able to view an old version of a single file without checking
714anything out; this command does that:
715
716-------------------------------------------------
717$ git show v2.5:fs/locks.c
718-------------------------------------------------
719
720Before the colon may be anything that names a commit, and after it
2de9b711 721may be any path to a file tracked by Git.
d19fbc3c 722
e34caace 723[[history-examples]]
fd5b820d 724=== Examples
aec053bb 725
46acd3fa 726[[counting-commits-on-a-branch]]
fd5b820d 727==== Counting the number of commits on a branch
46acd3fa 728
1249d8ad
TK
729Suppose you want to know how many commits you've made on `mybranch`
730since it diverged from `origin`:
46acd3fa
BF
731
732-------------------------------------------------
733$ git log --pretty=oneline origin..mybranch | wc -l
734-------------------------------------------------
735
736Alternatively, you may often see this sort of thing done with the
a6e5ef7d 737lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's
46acd3fa
BF
738of all the given commits:
739
740-------------------------------------------------
741$ git rev-list origin..mybranch | wc -l
742-------------------------------------------------
743
e34caace 744[[checking-for-equal-branches]]
fd5b820d 745==== Check whether two branches point at the same history
aec053bb
BF
746
747Suppose you want to check whether two branches point at the same point
748in history.
749
750-------------------------------------------------
751$ git diff origin..master
752-------------------------------------------------
753
69f7ad73
BF
754will tell you whether the contents of the project are the same at the
755two branches; in theory, however, it's possible that the same project
756contents could have been arrived at by two different historical
d55ae921 757routes. You could compare the object names:
aec053bb
BF
758
759-------------------------------------------------
760$ git rev-list origin
761e05db0fd4f31dde7005f075a84f96b360d05984b
762$ git rev-list master
763e05db0fd4f31dde7005f075a84f96b360d05984b
764-------------------------------------------------
765
1249d8ad 766Or you could recall that the `...` operator selects all commits
ddd4ddef 767reachable from either one reference or the other but not
ddd2369c 768both; so
aec053bb
BF
769
770-------------------------------------------------
771$ git log origin...master
772-------------------------------------------------
773
774will return no commits when the two branches are equal.
775
e34caace 776[[finding-tagged-descendants]]
fd5b820d 777==== Find first tagged version including a given fix
aec053bb 778
69f7ad73
BF
779Suppose you know that the commit e05db0fd fixed a certain problem.
780You'd like to find the earliest tagged release that contains that
781fix.
782
783Of course, there may be more than one answer--if the history branched
784after commit e05db0fd, then there could be multiple "earliest" tagged
785releases.
786
787You could just visually inspect the commits since e05db0fd:
788
789-------------------------------------------------
790$ gitk e05db0fd..
791-------------------------------------------------
792
ddd4ddef 793or you can use linkgit:git-name-rev[1], which will give the commit a
b181d57f
BF
794name based on any tag it finds pointing to one of the commit's
795descendants:
796
797-------------------------------------------------
04483524 798$ git name-rev --tags e05db0fd
b181d57f
BF
799e05db0fd tags/v1.5.0-rc1^0~23
800-------------------------------------------------
801
5162e697 802The linkgit:git-describe[1] command does the opposite, naming the
b181d57f
BF
803revision using a tag on which the given commit is based:
804
805-------------------------------------------------
806$ git describe e05db0fd
04483524 807v1.5.0-rc0-260-ge05db0f
b181d57f
BF
808-------------------------------------------------
809
810but that may sometimes help you guess which tags might come after the
811given commit.
812
813If you just want to verify whether a given tagged version contains a
5162e697 814given commit, you could use linkgit:git-merge-base[1]:
b181d57f
BF
815
816-------------------------------------------------
817$ git merge-base e05db0fd v1.5.0-rc1
818e05db0fd4f31dde7005f075a84f96b360d05984b
819-------------------------------------------------
820
821The merge-base command finds a common ancestor of the given commits,
822and always returns one or the other in the case where one is a
823descendant of the other; so the above output shows that e05db0fd
824actually is an ancestor of v1.5.0-rc1.
825
826Alternatively, note that
827
828-------------------------------------------------
4a7979ca 829$ git log v1.5.0-rc1..e05db0fd
b181d57f
BF
830-------------------------------------------------
831
4a7979ca 832will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
b181d57f 833because it outputs only commits that are not reachable from v1.5.0-rc1.
aec053bb 834
5162e697 835As yet another alternative, the linkgit:git-show-branch[1] command lists
4a7979ca 836the commits reachable from its arguments with a display on the left-hand
ddd4ddef
TA
837side that indicates which arguments that commit is reachable from.
838So, if you run something like
4a7979ca
BF
839
840-------------------------------------------------
841$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
842! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
843available
844 ! [v1.5.0-rc0] GIT v1.5.0 preview
845 ! [v1.5.0-rc1] GIT v1.5.0-rc1
846 ! [v1.5.0-rc2] GIT v1.5.0-rc2
847...
848-------------------------------------------------
849
ddd4ddef 850then a line like
4a7979ca
BF
851
852-------------------------------------------------
853+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
854available
855-------------------------------------------------
856
ddd4ddef
TA
857shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
858and from v1.5.0-rc2, and not from v1.5.0-rc0.
4a7979ca 859
629d9f78 860[[showing-commits-unique-to-a-branch]]
fd5b820d 861==== Showing commits unique to a given branch
4a7979ca 862
629d9f78 863Suppose you would like to see all the commits reachable from the branch
1249d8ad 864head named `master` but not from any other head in your repository.
d19fbc3c 865
629d9f78 866We can list all the heads in this repository with
5162e697 867linkgit:git-show-ref[1]:
d19fbc3c 868
629d9f78
BF
869-------------------------------------------------
870$ git show-ref --heads
871bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
872db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
873a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
87424dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
8751e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
876-------------------------------------------------
d19fbc3c 877
1249d8ad 878We can get just the branch-head names, and remove `master`, with
629d9f78
BF
879the help of the standard utilities cut and grep:
880
881-------------------------------------------------
882$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
883refs/heads/core-tutorial
884refs/heads/maint
885refs/heads/tutorial-2
886refs/heads/tutorial-fixes
887-------------------------------------------------
888
889And then we can ask to see all the commits reachable from master
890but not from these other heads:
891
892-------------------------------------------------
893$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
894 grep -v '^refs/heads/master' )
895-------------------------------------------------
896
897Obviously, endless variations are possible; for example, to see all
898commits reachable from some head but not from any tag in the repository:
899
900-------------------------------------------------
c78974f7 901$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
629d9f78
BF
902-------------------------------------------------
903
9d83e382 904(See linkgit:gitrevisions[7] for explanations of commit-selecting
629d9f78
BF
905syntax such as `--not`.)
906
82c8bf28 907[[making-a-release]]
fd5b820d 908==== Creating a changelog and tarball for a software release
82c8bf28 909
5162e697 910The linkgit:git-archive[1] command can create a tar or zip archive from
82c8bf28
BF
911any version of a project; for example:
912
913-------------------------------------------------
7ed1690c 914$ git archive -o latest.tar.gz --prefix=project/ HEAD
82c8bf28
BF
915-------------------------------------------------
916
7ed1690c
TK
917will use HEAD to produce a gzipped tar archive in which each filename
918is preceded by `project/`. The output file format is inferred from
919the output file extension if possible, see linkgit:git-archive[1] for
920details.
921
1249d8ad 922Versions of Git older than 1.7.7 don't know about the `tar.gz` format,
7ed1690c
TK
923you'll need to use gzip explicitly:
924
925-------------------------------------------------
926$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
927-------------------------------------------------
82c8bf28
BF
928
929If you're releasing a new version of a software project, you may want
930to simultaneously make a changelog to include in the release
931announcement.
932
933Linus Torvalds, for example, makes new kernel releases by tagging them,
934then running:
935
936-------------------------------------------------
937$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
938-------------------------------------------------
939
940where release-script is a shell script that looks like:
941
942-------------------------------------------------
943#!/bin/sh
944stable="$1"
945last="$2"
946new="$3"
947echo "# git tag v$new"
948echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
949echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
950echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
951echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
952echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
953-------------------------------------------------
954
955and then he just cut-and-pastes the output commands after verifying that
956they look OK.
4a7979ca 957
e1ba4c32 958[[Finding-commits-With-given-Content]]
fd5b820d 959==== Finding commits referencing a file with given content
187b0d80
BF
960
961Somebody hands you a copy of a file, and asks which commits modified a
962file such that it contained the given content either before or after the
963commit. You can find out with this:
964
965-------------------------------------------------
477ff5b7 966$ git log --raw --abbrev=40 --pretty=oneline |
187b0d80
BF
967 grep -B 1 `git hash-object filename`
968-------------------------------------------------
969
970Figuring out why this works is left as an exercise to the (advanced)
5162e697
DM
971student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
972linkgit:git-hash-object[1] man pages may prove helpful.
187b0d80 973
aa971cb9 974[[Developing-With-git]]
fd5b820d 975== Developing with Git
d19fbc3c 976
e34caace 977[[telling-git-your-name]]
fd5b820d 978=== Telling Git your name
d19fbc3c 979
632cc3e6
TK
980Before creating any commits, you should introduce yourself to Git.
981The easiest way to do so is to use linkgit:git-config[1]:
982
983------------------------------------------------
984$ git config --global user.name 'Your Name Comes Here'
985$ git config --global user.email 'you@yourdomain.example.com'
986------------------------------------------------
987
988Which will add the following to a file named `.gitconfig` in your
989home directory:
d19fbc3c
BF
990
991------------------------------------------------
d19fbc3c
BF
992[user]
993 name = Your Name Comes Here
994 email = you@yourdomain.example.com
d19fbc3c
BF
995------------------------------------------------
996
632cc3e6
TK
997See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
998details on the configuration file. The file is plain text, so you can
999also edit it with your favorite editor.
fc90c536 1000
d19fbc3c 1001
e34caace 1002[[creating-a-new-repository]]
fd5b820d 1003=== Creating a new repository
d19fbc3c
BF
1004
1005Creating a new repository from scratch is very easy:
1006
1007-------------------------------------------------
1008$ mkdir project
1009$ cd project
f1d2b477 1010$ git init
d19fbc3c
BF
1011-------------------------------------------------
1012
1013If you have some initial content (say, a tarball):
1014
1015-------------------------------------------------
0ddd93b2 1016$ tar xzvf project.tar.gz
d19fbc3c 1017$ cd project
f1d2b477 1018$ git init
d19fbc3c
BF
1019$ git add . # include everything below ./ in the first commit:
1020$ git commit
1021-------------------------------------------------
1022
1023[[how-to-make-a-commit]]
fd5b820d 1024=== How to make a commit
d19fbc3c
BF
1025
1026Creating a new commit takes three steps:
1027
1028 1. Making some changes to the working directory using your
1029 favorite editor.
2de9b711
TA
1030 2. Telling Git about your changes.
1031 3. Creating the commit using the content you told Git about
d19fbc3c
BF
1032 in step 2.
1033
1034In practice, you can interleave and repeat steps 1 and 2 as many
1035times as you want: in order to keep track of what you want committed
2de9b711 1036at step 3, Git maintains a snapshot of the tree's contents in a
d19fbc3c
BF
1037special staging area called "the index."
1038
01997b4a 1039At the beginning, the content of the index will be identical to
1249d8ad 1040that of the HEAD. The command `git diff --cached`, which shows
01997b4a
BF
1041the difference between the HEAD and the index, should therefore
1042produce no output at that point.
eb6ae7f4 1043
d19fbc3c
BF
1044Modifying the index is easy:
1045
d39765b1 1046To update the index with the contents of a new or modified file, use
d19fbc3c
BF
1047
1048-------------------------------------------------
1049$ git add path/to/file
1050-------------------------------------------------
1051
d39765b1 1052To remove a file from the index and from the working tree, use
d19fbc3c
BF
1053
1054-------------------------------------------------
1055$ git rm path/to/file
1056-------------------------------------------------
1057
1058After each step you can verify that
1059
1060-------------------------------------------------
1061$ git diff --cached
1062-------------------------------------------------
1063
1064always shows the difference between the HEAD and the index file--this
1065is what you'd commit if you created the commit now--and that
1066
1067-------------------------------------------------
1068$ git diff
1069-------------------------------------------------
1070
1071shows the difference between the working tree and the index file.
1072
1249d8ad 1073Note that `git add` always adds just the current contents of a file
d19fbc3c 1074to the index; further changes to the same file will be ignored unless
6127c086 1075you run `git add` on the file again.
d19fbc3c
BF
1076
1077When you're ready, just run
1078
1079-------------------------------------------------
1080$ git commit
1081-------------------------------------------------
1082
2de9b711 1083and Git will prompt you for a commit message and then create the new
3dff5379 1084commit. Check to make sure it looks like what you expected with
d19fbc3c
BF
1085
1086-------------------------------------------------
1087$ git show
1088-------------------------------------------------
1089
1090As a special shortcut,
a6080a0a 1091
d19fbc3c
BF
1092-------------------------------------------------
1093$ git commit -a
1094-------------------------------------------------
1095
1096will update the index with any files that you've modified or removed
1097and create a commit, all in one step.
1098
1099A number of commands are useful for keeping track of what you're
1100about to commit:
1101
1102-------------------------------------------------
1103$ git diff --cached # difference between HEAD and the index; what
1130845b 1104 # would be committed if you ran "commit" now.
d19fbc3c
BF
1105$ git diff # difference between the index file and your
1106 # working directory; changes that would not
1107 # be included if you ran "commit" now.
c64415e2
BF
1108$ git diff HEAD # difference between HEAD and working tree; what
1109 # would be committed if you ran "commit -a" now.
d19fbc3c
BF
1110$ git status # a brief per-file summary of the above.
1111-------------------------------------------------
1112
5162e697 1113You can also use linkgit:git-gui[1] to create commits, view changes in
407c0c87
BF
1114the index and the working tree files, and individually select diff hunks
1115for inclusion in the index (by right-clicking on the diff hunk and
1116choosing "Stage Hunk For Commit").
1117
e34caace 1118[[creating-good-commit-messages]]
fd5b820d 1119=== Creating good commit messages
d19fbc3c
BF
1120
1121Though not required, it's a good idea to begin the commit message
1122with a single short (less than 50 character) line summarizing the
1123change, followed by a blank line and then a more thorough
52ffe995
JW
1124description. The text up to the first blank line in a commit
1125message is treated as the commit title, and that title is used
2de9b711 1126throughout Git. For example, linkgit:git-format-patch[1] turns a
52ffe995
JW
1127commit into email, and it uses the title on the Subject line and the
1128rest of the commit in the body.
1129
d19fbc3c 1130
2dc53617 1131[[ignoring-files]]
fd5b820d 1132=== Ignoring files
2dc53617 1133
2de9b711 1134A project will often generate files that you do 'not' want to track with Git.
2dc53617 1135This typically includes files generated by a build process or temporary
2de9b711 1136backup files made by your editor. Of course, 'not' tracking files with Git
6127c086 1137is just a matter of 'not' calling `git add` on them. But it quickly becomes
2dc53617 1138annoying to have these untracked files lying around; e.g. they make
dcb11263
CJ
1139`git add .` practically useless, and they keep showing up in the output of
1140`git status`.
2dc53617 1141
1249d8ad
TK
1142You can tell Git to ignore certain files by creating a file called
1143`.gitignore` in the top level of your working directory, with contents
1144such as:
2dc53617
JH
1145
1146-------------------------------------------------
1147# Lines starting with '#' are considered comments.
464a8a7a 1148# Ignore any file named foo.txt.
2dc53617
JH
1149foo.txt
1150# Ignore (generated) html files,
1151*.html
1152# except foo.html which is maintained by hand.
1153!foo.html
1154# Ignore objects and archives.
1155*.[oa]
1156-------------------------------------------------
1157
5162e697 1158See linkgit:gitignore[5] for a detailed explanation of the syntax. You can
464a8a7a
BF
1159also place .gitignore files in other directories in your working tree, and they
1160will apply to those directories and their subdirectories. The `.gitignore`
1161files can be added to your repository like any other files (just run `git add
1162.gitignore` and `git commit`, as usual), which is convenient when the exclude
1163patterns (such as patterns matching build output files) would also make sense
1164for other users who clone your repository.
1165
1166If you wish the exclude patterns to affect only certain repositories
1167(instead of every repository for a given project), you may instead put
1249d8ad 1168them in a file in your repository named `.git/info/exclude`, or in any
da0005b8 1169file specified by the `core.excludesFile` configuration variable.
1249d8ad
TK
1170Some Git commands can also take exclude patterns directly on the
1171command line. See linkgit:gitignore[5] for the details.
2dc53617 1172
e34caace 1173[[how-to-merge]]
fd5b820d 1174=== How to merge
d19fbc3c
BF
1175
1176You can rejoin two diverging branches of development using
5162e697 1177linkgit:git-merge[1]:
d19fbc3c
BF
1178
1179-------------------------------------------------
1180$ git merge branchname
1181-------------------------------------------------
1182
1249d8ad 1183merges the development in the branch `branchname` into the current
e63ec003
MM
1184branch.
1185
1249d8ad 1186A merge is made by combining the changes made in `branchname` and the
e63ec003
MM
1187changes made up to the latest commit in your current branch since
1188their histories forked. The work tree is overwritten by the result of
1189the merge when this combining is done cleanly, or overwritten by a
1190half-merged results when this combining results in conflicts.
1191Therefore, if you have uncommitted changes touching the same files as
1192the ones impacted by the merge, Git will refuse to proceed. Most of
1193the time, you will want to commit your changes before you can merge,
1194and if you don't, then linkgit:git-stash[1] can take these changes
1195away while you're doing the merge, and reapply them afterwards.
1196
6a5d0b0a 1197If the changes are independent enough, Git will automatically complete
e63ec003
MM
1198the merge and commit the result (or reuse an existing commit in case
1199of <<fast-forwards,fast-forward>>, see below). On the other hand,
1200if there are conflicts--for example, if the same file is
d19fbc3c
BF
1201modified in two different ways in the remote branch and the local
1202branch--then you are warned; the output may look something like this:
1203
1204-------------------------------------------------
fabbd8f6
BF
1205$ git merge next
1206 100% (4/4) done
1207Auto-merged file.txt
d19fbc3c
BF
1208CONFLICT (content): Merge conflict in file.txt
1209Automatic merge failed; fix conflicts and then commit the result.
1210-------------------------------------------------
1211
1212Conflict markers are left in the problematic files, and after
1213you resolve the conflicts manually, you can update the index
2de9b711 1214with the contents and run Git commit, as you normally would when
d19fbc3c
BF
1215creating a new file.
1216
1217If you examine the resulting commit using gitk, you will see that it
1218has two parents, one pointing to the top of the current branch, and
1219one to the top of the other branch.
1220
d19fbc3c 1221[[resolving-a-merge]]
fd5b820d 1222=== Resolving a merge
d19fbc3c 1223
2de9b711 1224When a merge isn't resolved automatically, Git leaves the index and
d19fbc3c
BF
1225the working tree in a special state that gives you all the
1226information you need to help resolve the merge.
1227
1228Files with conflicts are marked specially in the index, so until you
5162e697 1229resolve the problem and update the index, linkgit:git-commit[1] will
ef561ac7 1230fail:
d19fbc3c
BF
1231
1232-------------------------------------------------
1233$ git commit
1234file.txt: needs merge
1235-------------------------------------------------
1236
5162e697 1237Also, linkgit:git-status[1] will list those files as "unmerged", and the
ef561ac7
BF
1238files with conflicts will have conflict markers added, like this:
1239
1240-------------------------------------------------
1241<<<<<<< HEAD:file.txt
1242Hello world
1243=======
1244Goodbye
1245>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1246-------------------------------------------------
1247
1248All you need to do is edit the files to resolve the conflicts, and then
1249
1250-------------------------------------------------
1251$ git add file.txt
1252$ git commit
1253-------------------------------------------------
1254
1255Note that the commit message will already be filled in for you with
1256some information about the merge. Normally you can just use this
1257default message unchanged, but you may add additional commentary of
1258your own if desired.
1259
2de9b711 1260The above is all you need to know to resolve a simple merge. But Git
ef561ac7
BF
1261also provides more information to help resolve conflicts:
1262
e34caace 1263[[conflict-resolution]]
fd5b820d 1264==== Getting conflict-resolution help during a merge
d19fbc3c 1265
2de9b711 1266All of the changes that Git was able to merge automatically are
5162e697 1267already added to the index file, so linkgit:git-diff[1] shows only
ef561ac7 1268the conflicts. It uses an unusual syntax:
d19fbc3c
BF
1269
1270-------------------------------------------------
1271$ git diff
1272diff --cc file.txt
1273index 802992c,2b60207..0000000
1274--- a/file.txt
1275+++ b/file.txt
1276@@@ -1,1 -1,1 +1,5 @@@
1277++<<<<<<< HEAD:file.txt
1278 +Hello world
1279++=======
1280+ Goodbye
1281++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1282-------------------------------------------------
1283
1130845b 1284Recall that the commit which will be committed after we resolve this
d19fbc3c
BF
1285conflict will have two parents instead of the usual one: one parent
1286will be HEAD, the tip of the current branch; the other will be the
1287tip of the other branch, which is stored temporarily in MERGE_HEAD.
1288
ef561ac7
BF
1289During the merge, the index holds three versions of each file. Each of
1290these three "file stages" represents a different version of the file:
1291
1292-------------------------------------------------
1293$ git show :1:file.txt # the file in a common ancestor of both branches
4209752d
JH
1294$ git show :2:file.txt # the version from HEAD.
1295$ git show :3:file.txt # the version from MERGE_HEAD.
ef561ac7
BF
1296-------------------------------------------------
1297
4209752d
JH
1298When you ask linkgit:git-diff[1] to show the conflicts, it runs a
1299three-way diff between the conflicted merge results in the work tree with
1300stages 2 and 3 to show only hunks whose contents come from both sides,
1301mixed (in other words, when a hunk's merge results come only from stage 2,
1302that part is not conflicting and is not shown. Same for stage 3).
ef561ac7
BF
1303
1304The diff above shows the differences between the working-tree version of
1305file.txt and the stage 2 and stage 3 versions. So instead of preceding
1249d8ad 1306each line by a single `+` or `-`, it now uses two columns: the first
ef561ac7
BF
1307column is used for differences between the first parent and the working
1308directory copy, and the second for differences between the second parent
1309and the working directory copy. (See the "COMBINED DIFF FORMAT" section
5162e697 1310of linkgit:git-diff-files[1] for a details of the format.)
ef561ac7
BF
1311
1312After resolving the conflict in the obvious way (but before updating the
1313index), the diff will look like:
d19fbc3c
BF
1314
1315-------------------------------------------------
1316$ git diff
1317diff --cc file.txt
1318index 802992c,2b60207..0000000
1319--- a/file.txt
1320+++ b/file.txt
1321@@@ -1,1 -1,1 +1,1 @@@
1322- Hello world
1323 -Goodbye
1324++Goodbye world
1325-------------------------------------------------
1326
1327This shows that our resolved version deleted "Hello world" from the
1328first parent, deleted "Goodbye" from the second parent, and added
1329"Goodbye world", which was previously absent from both.
1330
ef561ac7
BF
1331Some special diff options allow diffing the working directory against
1332any of these stages:
1333
1334-------------------------------------------------
1335$ git diff -1 file.txt # diff against stage 1
1336$ git diff --base file.txt # same as the above
1337$ git diff -2 file.txt # diff against stage 2
1338$ git diff --ours file.txt # same as the above
1339$ git diff -3 file.txt # diff against stage 3
1340$ git diff --theirs file.txt # same as the above.
1341-------------------------------------------------
1342
0cafe944 1343The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
ef561ac7 1344for merges:
d19fbc3c
BF
1345
1346-------------------------------------------------
1347$ git log --merge
ef561ac7 1348$ gitk --merge
d19fbc3c
BF
1349-------------------------------------------------
1350
ef561ac7
BF
1351These will display all commits which exist only on HEAD or on
1352MERGE_HEAD, and which touch an unmerged file.
d19fbc3c 1353
5162e697 1354You may also use linkgit:git-mergetool[1], which lets you merge the
c7719fbe 1355unmerged files using external tools such as Emacs or kdiff3.
c64415e2 1356
ef561ac7 1357Each time you resolve the conflicts in a file and update the index:
d19fbc3c
BF
1358
1359-------------------------------------------------
1360$ git add file.txt
d19fbc3c
BF
1361-------------------------------------------------
1362
ef561ac7 1363the different stages of that file will be "collapsed", after which
6127c086 1364`git diff` will (by default) no longer show diffs for that file.
d19fbc3c
BF
1365
1366[[undoing-a-merge]]
fd5b820d 1367=== Undoing a merge
d19fbc3c
BF
1368
1369If you get stuck and decide to just give up and throw the whole mess
1370away, you can always return to the pre-merge state with
1371
1372-------------------------------------------------
fc991b43 1373$ git merge --abort
d19fbc3c
BF
1374-------------------------------------------------
1375
1130845b 1376Or, if you've already committed the merge that you want to throw away,
d19fbc3c
BF
1377
1378-------------------------------------------------
1c73bb0e 1379$ git reset --hard ORIG_HEAD
d19fbc3c
BF
1380-------------------------------------------------
1381
1382However, this last command can be dangerous in some cases--never
1383throw away a commit you have already committed if that commit may
1384itself have been merged into another branch, as doing so may confuse
1385further merges.
1386
e34caace 1387[[fast-forwards]]
fd5b820d 1388=== Fast-forward merges
d19fbc3c
BF
1389
1390There is one special case not mentioned above, which is treated
1391differently. Normally, a merge results in a merge commit, with two
1392parents, one pointing at each of the two lines of development that
1393were merged.
1394
b2af4829
XF
1395However, if the current branch is an ancestor of the other--so every commit
1396present in the current branch is already contained in the other branch--then Git
1397just performs a "fast-forward"; the head of the current branch is moved forward
1398to point at the head of the merged-in branch, without any new commits being
1399created.
d19fbc3c 1400
e34caace 1401[[fixing-mistakes]]
fd5b820d 1402=== Fixing mistakes
b684f830
BF
1403
1404If you've messed up the working tree, but haven't yet committed your
1405mistake, you can return the entire working tree to the last committed
1406state with
1407
1408-------------------------------------------------
80f537f7 1409$ git restore --staged --worktree :/
b684f830
BF
1410-------------------------------------------------
1411
1412If you make a commit that you later wish you hadn't, there are two
1413fundamentally different ways to fix the problem:
1414
1415 1. You can create a new commit that undoes whatever was done
93cbbd71 1416 by the old commit. This is the correct thing if your
b684f830
BF
1417 mistake has already been made public.
1418
1419 2. You can go back and modify the old commit. You should
1420 never do this if you have already made the history public;
2de9b711 1421 Git does not normally expect the "history" of a project to
b684f830
BF
1422 change, and cannot correctly perform repeated merges from
1423 a branch that has had its history changed.
1424
e34caace 1425[[reverting-a-commit]]
fd5b820d 1426==== Fixing a mistake with a new commit
b684f830
BF
1427
1428Creating a new commit that reverts an earlier change is very easy;
5162e697 1429just pass the linkgit:git-revert[1] command a reference to the bad
b684f830
BF
1430commit; for example, to revert the most recent commit:
1431
1432-------------------------------------------------
1433$ git revert HEAD
1434-------------------------------------------------
1435
1436This will create a new commit which undoes the change in HEAD. You
1437will be given a chance to edit the commit message for the new commit.
1438
1439You can also revert an earlier change, for example, the next-to-last:
1440
1441-------------------------------------------------
1442$ git revert HEAD^
1443-------------------------------------------------
1444
2de9b711 1445In this case Git will attempt to undo the old change while leaving
b684f830
BF
1446intact any changes made since then. If more recent changes overlap
1447with the changes to be reverted, then you will be asked to fix
1448conflicts manually, just as in the case of <<resolving-a-merge,
1449resolving a merge>>.
1450
7cb192ea 1451[[fixing-a-mistake-by-rewriting-history]]
fd5b820d 1452==== Fixing a mistake by rewriting history
b684f830
BF
1453
1454If the problematic commit is the most recent commit, and you have not
1455yet made that commit public, then you may just
6127c086 1456<<undoing-a-merge,destroy it using `git reset`>>.
b684f830
BF
1457
1458Alternatively, you
1459can edit the working directory and update the index to fix your
1460mistake, just as if you were going to <<how-to-make-a-commit,create a
1461new commit>>, then run
1462
1463-------------------------------------------------
1464$ git commit --amend
1465-------------------------------------------------
1466
1467which will replace the old commit by a new commit incorporating your
1468changes, giving you a chance to edit the old commit message first.
1469
1470Again, you should never do this to a commit that may already have
5162e697 1471been merged into another branch; use linkgit:git-revert[1] instead in
b684f830
BF
1472that case.
1473
7cb192ea 1474It is also possible to replace commits further back in the history, but
b684f830
BF
1475this is an advanced topic to be left for
1476<<cleaning-up-history,another chapter>>.
1477
e34caace 1478[[checkout-of-path]]
fd5b820d 1479==== Checking out an old version of a file
b684f830
BF
1480
1481In the process of undoing a previous bad change, you may find it
1482useful to check out an older version of a particular file using
80f537f7 1483linkgit:git-restore[1]. The command
b684f830
BF
1484
1485-------------------------------------------------
80f537f7 1486$ git restore --source=HEAD^ path/to/file
b684f830
BF
1487-------------------------------------------------
1488
1489replaces path/to/file by the contents it had in the commit HEAD^, and
1490also updates the index to match. It does not change branches.
1491
1492If you just want to look at an old version of the file, without
1493modifying the working directory, you can do that with
5162e697 1494linkgit:git-show[1]:
b684f830
BF
1495
1496-------------------------------------------------
ed4eb0d8 1497$ git show HEAD^:path/to/file
b684f830
BF
1498-------------------------------------------------
1499
1500which will display the given version of the file.
1501
7a7cc594 1502[[interrupted-work]]
fd5b820d 1503==== Temporarily setting aside work in progress
7a7cc594
JH
1504
1505While you are in the middle of working on something complicated, you
1506find an unrelated but obvious and trivial bug. You would like to fix it
5162e697 1507before continuing. You can use linkgit:git-stash[1] to save the current
7a7cc594
JH
1508state of your work, and after fixing the bug (or, optionally after doing
1509so on a different branch and then coming back), unstash the
1510work-in-progress changes.
1511
1512------------------------------------------------
db37745e 1513$ git stash push -m "work in progress for foo feature"
7a7cc594
JH
1514------------------------------------------------
1515
1516This command will save your changes away to the `stash`, and
1517reset your working tree and the index to match the tip of your
1518current branch. Then you can make your fix as usual.
1519
1520------------------------------------------------
1521... edit and test ...
1522$ git commit -a -m "blorpl: typofix"
1523------------------------------------------------
1524
1525After that, you can go back to what you were working on with
7b8988e1 1526`git stash pop`:
7a7cc594
JH
1527
1528------------------------------------------------
7b8988e1 1529$ git stash pop
7a7cc594
JH
1530------------------------------------------------
1531
1532
e34caace 1533[[ensuring-good-performance]]
fd5b820d 1534=== Ensuring good performance
d19fbc3c 1535
2de9b711 1536On large repositories, Git depends on compression to keep the history
901fd180 1537information from taking up too much space on disk or in memory. Some
e1ebf212 1538Git commands may automatically run linkgit:git-gc[1], so you don't
901fd180
TK
1539have to worry about running it manually. However, compressing a large
1540repository may take a while, so you may want to call `gc` explicitly
1541to avoid automatic compression kicking in when it is not convenient.
d19fbc3c 1542
e34caace
BF
1543
1544[[ensuring-reliability]]
fd5b820d 1545=== Ensuring reliability
11e016a3 1546
e34caace 1547[[checking-for-corruption]]
fd5b820d 1548==== Checking the repository for corruption
11e016a3 1549
5162e697 1550The linkgit:git-fsck[1] command runs a number of self-consistency checks
1191ee18 1551on the repository, and reports on any problems. This may take some
c6a13b2c 1552time.
21dcb3b7
BF
1553
1554-------------------------------------------------
04e50e94 1555$ git fsck
21dcb3b7
BF
1556dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1557dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1558dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1559dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
1560dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
1561dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
1562dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
1563dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1564...
1565-------------------------------------------------
1566
c6a13b2c
JH
1567You will see informational messages on dangling objects. They are objects
1568that still exist in the repository but are no longer referenced by any of
1249d8ad 1569your branches, and can (and will) be removed after a while with `gc`.
b4ab1980 1570You can run `git fsck --no-dangling` to suppress these messages, and still
c6a13b2c 1571view real errors.
1cdade2c 1572
e34caace 1573[[recovering-lost-changes]]
fd5b820d 1574==== Recovering lost changes
11e016a3 1575
e34caace 1576[[reflogs]]
fd5b820d 1577===== Reflogs
559e4d7a 1578
1249d8ad
TK
1579Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
1580and then realize that the branch was the only reference you had to
1581that point in history.
559e4d7a 1582
2de9b711 1583Fortunately, Git also keeps a log, called a "reflog", of all the
559e4d7a 1584previous values of each branch. So in this case you can still find the
a6080a0a 1585old history using, for example,
559e4d7a
BF
1586
1587-------------------------------------------------
1588$ git log master@{1}
1589-------------------------------------------------
1590
e502c2c3 1591This lists the commits reachable from the previous version of the
1249d8ad
TK
1592`master` branch head. This syntax can be used with any Git command
1593that accepts a commit, not just with `git log`. Some other examples:
559e4d7a
BF
1594
1595-------------------------------------------------
1596$ git show master@{2} # See where the branch pointed 2,
1597$ git show master@{3} # 3, ... changes ago.
1598$ gitk master@{yesterday} # See where it pointed yesterday,
1599$ gitk master@{"1 week ago"} # ... or last week
953f3d6f
BF
1600$ git log --walk-reflogs master # show reflog entries for master
1601-------------------------------------------------
1602
1603A separate reflog is kept for the HEAD, so
1604
1605-------------------------------------------------
1606$ git show HEAD@{"1 week ago"}
559e4d7a
BF
1607-------------------------------------------------
1608
953f3d6f
BF
1609will show what HEAD pointed to one week ago, not what the current branch
1610pointed to one week ago. This allows you to see the history of what
1611you've checked out.
1612
559e4d7a 1613The reflogs are kept by default for 30 days, after which they may be
5162e697 1614pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
559e4d7a 1615how to control this pruning, and see the "SPECIFYING REVISIONS"
9d83e382 1616section of linkgit:gitrevisions[7] for details.
559e4d7a 1617
2de9b711 1618Note that the reflog history is very different from normal Git history.
559e4d7a
BF
1619While normal history is shared by every repository that works on the
1620same project, the reflog history is not shared: it tells you only about
1621how the branches in your local repository have changed over time.
1622
59723040 1623[[dangling-object-recovery]]
fd5b820d 1624===== Examining dangling objects
559e4d7a 1625
59723040
BF
1626In some situations the reflog may not be able to save you. For example,
1627suppose you delete a branch, then realize you need the history it
1628contained. The reflog is also deleted; however, if you have not yet
1629pruned the repository, then you may still be able to find the lost
6127c086 1630commits in the dangling objects that `git fsck` reports. See
59723040 1631<<dangling-objects>> for the details.
559e4d7a
BF
1632
1633-------------------------------------------------
1634$ git fsck
1635dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1636dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1637dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1638...
1639-------------------------------------------------
1640
aacd404e 1641You can examine
559e4d7a
BF
1642one of those dangling commits with, for example,
1643
1644------------------------------------------------
1645$ gitk 7281251ddd --not --all
1646------------------------------------------------
1647
1648which does what it sounds like: it says that you want to see the commit
1649history that is described by the dangling commit(s), but not the
1650history that is described by all your existing branches and tags. Thus
1651you get exactly the history reachable from that commit that is lost.
1652(And notice that it might not be just one commit: we only report the
1653"tip of the line" as being dangling, but there might be a whole deep
79c96c57 1654and complex commit history that was dropped.)
559e4d7a
BF
1655
1656If you decide you want the history back, you can always create a new
1657reference pointing to it, for example, a new branch:
1658
1659------------------------------------------------
a6080a0a 1660$ git branch recovered-branch 7281251ddd
559e4d7a
BF
1661------------------------------------------------
1662
59723040
BF
1663Other types of dangling objects (blobs and trees) are also possible, and
1664dangling objects can arise in other situations.
1665
11e016a3 1666
e34caace 1667[[sharing-development]]
fd5b820d 1668== Sharing development with others
d19fbc3c 1669
aa971cb9 1670[[getting-updates-With-git-pull]]
fd5b820d 1671=== Getting updates with git pull
d19fbc3c 1672
e63ec003 1673After you clone a repository and commit a few changes of your own, you
d19fbc3c
BF
1674may wish to check the original repository for updates and merge them
1675into your own work.
1676
aa971cb9 1677We have already seen <<Updating-a-repository-With-git-fetch,how to
0e615b25 1678keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
d19fbc3c
BF
1679and how to merge two branches. So you can merge in changes from the
1680original repository's master branch with:
1681
1682-------------------------------------------------
1683$ git fetch
1684$ git merge origin/master
1685-------------------------------------------------
1686
5162e697 1687However, the linkgit:git-pull[1] command provides a way to do this in
d19fbc3c
BF
1688one step:
1689
1690-------------------------------------------------
1691$ git pull origin master
1692-------------------------------------------------
1693
1249d8ad
TK
1694In fact, if you have `master` checked out, then this branch has been
1695configured by `git clone` to get changes from the HEAD branch of the
66a062a1 1696origin repository. So often you can
0eb4f7cd 1697accomplish the above with just a simple
d19fbc3c
BF
1698
1699-------------------------------------------------
1700$ git pull
1701-------------------------------------------------
1702
66a062a1
MM
1703This command will fetch changes from the remote branches to your
1704remote-tracking branches `origin/*`, and merge the default branch into
1705the current branch.
1706
29b9a66f
MM
1707More generally, a branch that is created from a remote-tracking branch
1708will pull
0eb4f7cd 1709by default from that branch. See the descriptions of the
1249d8ad 1710`branch.<name>.remote` and `branch.<name>.merge` options in
5162e697
DM
1711linkgit:git-config[1], and the discussion of the `--track` option in
1712linkgit:git-checkout[1], to learn how to control these defaults.
d19fbc3c 1713
1249d8ad 1714In addition to saving you keystrokes, `git pull` also helps you by
d19fbc3c
BF
1715producing a default commit message documenting the branch and
1716repository that you pulled from.
1717
1718(But note that no such commit will be created in the case of a
a75d7b54 1719<<fast-forwards,fast-forward>>; instead, your branch will just be
79c96c57 1720updated to point to the latest commit from the upstream branch.)
d19fbc3c 1721
1249d8ad 1722The `git pull` command can also be given `.` as the "remote" repository,
1191ee18 1723in which case it just merges in a branch from the current repository; so
4c63ff45
BF
1724the commands
1725
1726-------------------------------------------------
1727$ git pull . branch
1728$ git merge branch
1729-------------------------------------------------
1730
a7bdee11 1731are roughly equivalent.
4c63ff45 1732
e34caace 1733[[submitting-patches]]
fd5b820d 1734=== Submitting patches to a project
d19fbc3c
BF
1735
1736If you just have a few changes, the simplest way to submit them may
1737just be to send them as patches in email:
1738
5162e697 1739First, use linkgit:git-format-patch[1]; for example:
d19fbc3c
BF
1740
1741-------------------------------------------------
eb6ae7f4 1742$ git format-patch origin
d19fbc3c
BF
1743-------------------------------------------------
1744
1745will produce a numbered series of files in the current directory, one
1249d8ad 1746for each patch in the current branch but not in `origin/HEAD`.
d19fbc3c 1747
d84cef18
PO
1748`git format-patch` can include an initial "cover letter". You can insert
1749commentary on individual patches after the three dash line which
1750`format-patch` places after the commit message but before the patch
1751itself. If you use `git notes` to track your cover letter material,
1752`git format-patch --notes` will include the commit's notes in a similar
1753manner.
1754
d19fbc3c
BF
1755You can then import these into your mail client and send them by
1756hand. However, if you have a lot to send at once, you may prefer to
5162e697 1757use the linkgit:git-send-email[1] script to automate the process.
3c735e07
JM
1758Consult the mailing list for your project first to determine
1759their requirements for submitting patches.
d19fbc3c 1760
e34caace 1761[[importing-patches]]
fd5b820d 1762=== Importing patches to a project
d19fbc3c 1763
5162e697 1764Git also provides a tool called linkgit:git-am[1] (am stands for
d19fbc3c
BF
1765"apply mailbox"), for importing such an emailed series of patches.
1766Just save all of the patch-containing messages, in order, into a
1249d8ad 1767single mailbox file, say `patches.mbox`, then run
d19fbc3c
BF
1768
1769-------------------------------------------------
eb6ae7f4 1770$ git am -3 patches.mbox
d19fbc3c
BF
1771-------------------------------------------------
1772
1773Git will apply each patch in order; if any conflicts are found, it
1774will stop, and you can fix the conflicts as described in
1249d8ad 1775"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells
2de9b711 1776Git to perform a merge; if you would prefer it just to abort and
01997b4a
BF
1777leave your tree and index untouched, you may omit that option.)
1778
1779Once the index is updated with the results of the conflict
1780resolution, instead of creating a new commit, just run
d19fbc3c
BF
1781
1782-------------------------------------------------
8ceb6fbd 1783$ git am --continue
d19fbc3c
BF
1784-------------------------------------------------
1785
2de9b711 1786and Git will create the commit for you and continue applying the
d19fbc3c
BF
1787remaining patches from the mailbox.
1788
1789The final result will be a series of commits, one for each patch in
1790the original mailbox, with authorship and commit log message each
1791taken from the message containing each patch.
1792
eda69449 1793[[public-repositories]]
fd5b820d 1794=== Public Git repositories
d19fbc3c 1795
6e30fb0c
DK
1796Another way to submit changes to a project is to tell the maintainer
1797of that project to pull the changes from your repository using
aa971cb9 1798linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull,
6127c086 1799Getting updates with `git pull`>>" we described this as a way to get
6e30fb0c
DK
1800updates from the "main" repository, but it works just as well in the
1801other direction.
d19fbc3c 1802
eda69449
BF
1803If you and the maintainer both have accounts on the same machine, then
1804you can just pull changes from each other's repositories directly;
11d51533 1805commands that accept repository URLs as arguments will also accept a
eda69449 1806local directory name:
d19fbc3c
BF
1807
1808-------------------------------------------------
1809$ git clone /path/to/repository
1810$ git pull /path/to/other/repository
1811-------------------------------------------------
1812
c9016158 1813or an ssh URL:
11d51533
BF
1814
1815-------------------------------------------------
1816$ git clone ssh://yourhost/~you/repository
1817-------------------------------------------------
1818
1819For projects with few developers, or for synchronizing a few private
1820repositories, this may be all you need.
1821
eda69449
BF
1822However, the more common way to do this is to maintain a separate public
1823repository (usually on a different host) for others to pull changes
1824from. This is usually more convenient, and allows you to cleanly
1825separate private work in progress from publicly visible work.
d19fbc3c
BF
1826
1827You will continue to do your day-to-day work in your personal
1828repository, but periodically "push" changes from your personal
1829repository into your public repository, allowing other developers to
1830pull from that repository. So the flow of changes, in a situation
1831where there is one other developer with a public repository, looks
1832like this:
1833
c4d2f614
1834....
1835 you push
1836your personal repo ------------------> your public repo
1837 ^ |
1838 | |
1839 | you pull | they pull
1840 | |
1841 | |
1842 | they push V
1843their public repo <------------------- their repo
1844....
d19fbc3c 1845
11d51533
BF
1846We explain how to do this in the following sections.
1847
eda69449 1848[[setting-up-a-public-repository]]
fd5b820d 1849==== Setting up a public repository
eda69449 1850
1249d8ad 1851Assume your personal repository is in the directory `~/proj`. We
6127c086 1852first create a new clone of the repository and tell `git daemon` that it
eda69449 1853is meant to be public:
d19fbc3c
BF
1854
1855-------------------------------------------------
52c80037 1856$ git clone --bare ~/proj proj.git
eda69449 1857$ touch proj.git/git-daemon-export-ok
d19fbc3c
BF
1858-------------------------------------------------
1859
52c80037 1860The resulting directory proj.git contains a "bare" git repository--it is
1249d8ad 1861just the contents of the `.git` directory, without any files checked out
eda69449 1862around it.
d19fbc3c 1863
1249d8ad 1864Next, copy `proj.git` to the server where you plan to host the
d19fbc3c
BF
1865public repository. You can use scp, rsync, or whatever is most
1866convenient.
1867
eda69449 1868[[exporting-via-git]]
fd5b820d 1869==== Exporting a Git repository via the Git protocol
eda69449
BF
1870
1871This is the preferred method.
1872
1873If someone else administers the server, they should tell you what
1249d8ad
TK
1874directory to put the repository in, and what `git://` URL it will
1875appear at. You can then skip to the section
d19fbc3c
BF
1876"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1877repository>>", below.
1878
5162e697 1879Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
eda69449 1880listen on port 9418. By default, it will allow access to any directory
2de9b711 1881that looks like a Git directory and contains the magic file
6127c086 1882git-daemon-export-ok. Passing some directory paths as `git daemon`
eda69449
BF
1883arguments will further restrict the exports to those paths.
1884
6127c086 1885You can also run `git daemon` as an inetd service; see the
5162e697 1886linkgit:git-daemon[1] man page for details. (See especially the
eda69449 1887examples section.)
d19fbc3c
BF
1888
1889[[exporting-via-http]]
fd5b820d 1890==== Exporting a git repository via HTTP
d19fbc3c 1891
2de9b711 1892The Git protocol gives better performance and reliability, but on a
de3f2c7b 1893host with a web server set up, HTTP exports may be simpler to set up.
d19fbc3c 1894
2de9b711 1895All you need to do is place the newly created bare Git repository in
d19fbc3c
BF
1896a directory that is exported by the web server, and make some
1897adjustments to give web clients some extra information they need:
1898
1899-------------------------------------------------
1900$ mv proj.git /home/you/public_html/proj.git
1901$ cd proj.git
c64415e2 1902$ git --bare update-server-info
7dce9918 1903$ mv hooks/post-update.sample hooks/post-update
d19fbc3c
BF
1904-------------------------------------------------
1905
1906(For an explanation of the last two lines, see
6998e4db 1907linkgit:git-update-server-info[1] and linkgit:githooks[5].)
d19fbc3c 1908
1249d8ad 1909Advertise the URL of `proj.git`. Anybody else should then be able to
c9016158 1910clone or pull from that URL, for example with a command line like:
d19fbc3c
BF
1911
1912-------------------------------------------------
1913$ git clone http://yourserver.com/~you/proj.git
1914-------------------------------------------------
1915
1916(See also
d5ff3b4b 1917link:howto/setup-git-server-over-http.html[setup-git-server-over-http]
d19fbc3c 1918for a slightly more sophisticated setup using WebDAV which also
de3f2c7b 1919allows pushing over HTTP.)
d19fbc3c 1920
d19fbc3c 1921[[pushing-changes-to-a-public-repository]]
fd5b820d 1922==== Pushing changes to a public repository
d19fbc3c 1923
eda69449 1924Note that the two techniques outlined above (exporting via
d19fbc3c
BF
1925<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1926maintainers to fetch your latest changes, but they do not allow write
1927access, which you will need to update the public repository with the
1928latest changes created in your private repository.
1929
5162e697 1930The simplest way to do this is using linkgit:git-push[1] and ssh; to
1249d8ad
TK
1931update the remote branch named `master` with the latest state of your
1932branch named `master`, run
d19fbc3c
BF
1933
1934-------------------------------------------------
1935$ git push ssh://yourserver.com/~you/proj.git master:master
1936-------------------------------------------------
1937
1938or just
1939
1940-------------------------------------------------
1941$ git push ssh://yourserver.com/~you/proj.git master
1942-------------------------------------------------
1943
6127c086 1944As with `git fetch`, `git push` will complain if this does not result in a
a75d7b54 1945<<fast-forwards,fast-forward>>; see the following section for details on
81eb417a 1946handling this case.
d19fbc3c 1947
1249d8ad 1948Note that the target of a `push` is normally a
11d51533 1949<<def_bare_repository,bare>> repository. You can also push to a
d9be2485
TK
1950repository that has a checked-out working tree, but a push to update the
1951currently checked-out branch is denied by default to prevent confusion.
50995edd 1952See the description of the receive.denyCurrentBranch option
d9be2485 1953in linkgit:git-config[1] for details.
11d51533 1954
6127c086 1955As with `git fetch`, you may also set up configuration options to
e9b49083
TK
1956save typing; so, for example:
1957
1958-------------------------------------------------
1959$ git remote add public-repo ssh://yourserver.com/~you/proj.git
1960-------------------------------------------------
1961
1962adds the following to `.git/config`:
d19fbc3c
BF
1963
1964-------------------------------------------------
d19fbc3c 1965[remote "public-repo"]
e9b49083
TK
1966 url = yourserver.com:proj.git
1967 fetch = +refs/heads/*:refs/remotes/example/*
d19fbc3c
BF
1968-------------------------------------------------
1969
e9b49083 1970which lets you do the same push with just
d19fbc3c
BF
1971
1972-------------------------------------------------
1973$ git push public-repo master
1974-------------------------------------------------
1975
1249d8ad
TK
1976See the explanations of the `remote.<name>.url`,
1977`branch.<name>.remote`, and `remote.<name>.push` options in
1978linkgit:git-config[1] for details.
d19fbc3c 1979
81eb417a 1980[[forcing-push]]
fd5b820d 1981==== What to do when a push fails
81eb417a 1982
a75d7b54 1983If a push would not result in a <<fast-forwards,fast-forward>> of the
81eb417a
BF
1984remote branch, then it will fail with an error like:
1985
1986-------------------------------------------------
3c82eec8
1987 ! [rejected] master -> master (non-fast-forward)
1988error: failed to push some refs to '...'
1989hint: Updates were rejected because the tip of your current branch is behind
1990hint: its remote counterpart. Integrate the remote changes (e.g.
1991hint: 'git pull ...') before pushing again.
1992hint: See the 'Note about fast-forwards' in 'git push --help' for details.
81eb417a
BF
1993-------------------------------------------------
1994
1995This can happen, for example, if you:
1996
6127c086
FC
1997 - use `git reset --hard` to remove already-published commits, or
1998 - use `git commit --amend` to replace already-published commits
7cb192ea 1999 (as in <<fixing-a-mistake-by-rewriting-history>>), or
6127c086 2000 - use `git rebase` to rebase any already-published commits (as
81eb417a
BF
2001 in <<using-git-rebase>>).
2002
6127c086 2003You may force `git push` to perform the update anyway by preceding the
81eb417a
BF
2004branch name with a plus sign:
2005
2006-------------------------------------------------
2007$ git push ssh://yourserver.com/~you/proj.git +master
2008-------------------------------------------------
2009
d1471e06
TK
2010Note the addition of the `+` sign. Alternatively, you can use the
2011`-f` flag to force the remote update, as in:
2012
2013-------------------------------------------------
2014$ git push -f ssh://yourserver.com/~you/proj.git master
2015-------------------------------------------------
2016
81eb417a 2017Normally whenever a branch head in a public repository is modified, it
9e5d87d4 2018is modified to point to a descendant of the commit that it pointed to
81eb417a 2019before. By forcing a push in this situation, you break that convention.
aa971cb9 2020(See <<problems-With-rewriting-history>>.)
81eb417a
BF
2021
2022Nevertheless, this is a common practice for people that need a simple
2023way to publish a work-in-progress patch series, and it is an acceptable
2024compromise as long as you warn other developers that this is how you
2025intend to manage the branch.
2026
2027It's also possible for a push to fail in this way when other people have
2028the right to push to the same repository. In that case, the correct
843c81dc
EH
2029solution is to retry the push after first updating your work: either by a
2030pull, or by a fetch followed by a rebase; see the
81eb417a 2031<<setting-up-a-shared-repository,next section>> and
6998e4db 2032linkgit:gitcvs-migration[7] for more.
81eb417a 2033
e34caace 2034[[setting-up-a-shared-repository]]
fd5b820d 2035==== Setting up a shared repository
d19fbc3c
BF
2036
2037Another way to collaborate is by using a model similar to that
2038commonly used in CVS, where several developers with special rights
2039all push to and pull from a single shared repository. See
6998e4db 2040linkgit:gitcvs-migration[7] for instructions on how to
d19fbc3c
BF
2041set this up.
2042
2de9b711 2043However, while there is nothing wrong with Git's support for shared
8fae2225 2044repositories, this mode of operation is not generally recommended,
2de9b711 2045simply because the mode of collaboration that Git supports--by
8fae2225
BF
2046exchanging patches and pulling from public repositories--has so many
2047advantages over the central shared repository:
2048
2049 - Git's ability to quickly import and merge patches allows a
2050 single maintainer to process incoming changes even at very
6127c086 2051 high rates. And when that becomes too much, `git pull` provides
8fae2225
BF
2052 an easy way for that maintainer to delegate this job to other
2053 maintainers while still allowing optional review of incoming
2054 changes.
2055 - Since every developer's repository has the same complete copy
2056 of the project history, no repository is special, and it is
2057 trivial for another developer to take over maintenance of a
2058 project, either by mutual agreement, or because a maintainer
2059 becomes unresponsive or difficult to work with.
2060 - The lack of a central group of "committers" means there is
2061 less need for formal decisions about who is "in" and who is
2062 "out".
2063
e34caace 2064[[setting-up-gitweb]]
fd5b820d 2065==== Allowing web browsing of a repository
d19fbc3c 2066
a8cd1402 2067The gitweb cgi script provides users an easy way to browse your
99487cf2
SS
2068project's revisions, file contents and logs without having to install
2069Git. Features like RSS/Atom feeds and blame/annotation details may
2070optionally be enabled.
2071
2072The linkgit:git-instaweb[1] command provides a simple way to start
2073browsing the repository using gitweb. The default server when using
2074instaweb is lighttpd.
2075
2076See the file gitweb/INSTALL in the Git source tree and
d285ab0a 2077linkgit:gitweb[1] for instructions on details setting up a permanent
99487cf2 2078installation with a CGI or Perl capable server.
d19fbc3c 2079
9cfde9ee 2080[[how-to-get-a-git-repository-with-minimal-history]]
fd5b820d 2081=== How to get a Git repository with minimal history
9cfde9ee
SS
2082
2083A <<def_shallow_clone,shallow clone>>, with its truncated
2084history, is useful when one is interested only in recent history
2085of a project and getting full history from the upstream is
2086expensive.
2087
2088A <<def_shallow_clone,shallow clone>> is created by specifying
2089the linkgit:git-clone[1] `--depth` switch. The depth can later be
2090changed with the linkgit:git-fetch[1] `--depth` switch, or full
2091history restored with `--unshallow`.
2092
2093Merging inside a <<def_shallow_clone,shallow clone>> will work as long
2094as a merge base is in the recent history.
2095Otherwise, it will be like merging unrelated histories and may
2096have to result in huge conflicts. This limitation may make such
2097a repository unsuitable to be used in merge based workflows.
d19fbc3c 2098
e34caace 2099[[sharing-development-examples]]
fd5b820d 2100=== Examples
d19fbc3c 2101
9e2163ea 2102[[maintaining-topic-branches]]
fd5b820d 2103==== Maintaining topic branches for a Linux subsystem maintainer
9e2163ea 2104
2de9b711 2105This describes how Tony Luck uses Git in his role as maintainer of the
9e2163ea
BF
2106IA64 architecture for the Linux kernel.
2107
2108He uses two public branches:
2109
2110 - A "test" tree into which patches are initially placed so that they
2111 can get some exposure when integrated with other ongoing development.
2112 This tree is available to Andrew for pulling into -mm whenever he
2113 wants.
2114
2115 - A "release" tree into which tested patches are moved for final sanity
2116 checking, and as a vehicle to send them upstream to Linus (by sending
2117 him a "please pull" request.)
2118
2119He also uses a set of temporary branches ("topic branches"), each
2120containing a logical grouping of patches.
2121
2122To set this up, first create your work tree by cloning Linus's public
2123tree:
2124
2125-------------------------------------------------
283efb01 2126$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work
9e2163ea
BF
2127$ cd work
2128-------------------------------------------------
2129
29b9a66f 2130Linus's tree will be stored in the remote-tracking branch named origin/master,
5162e697
DM
2131and can be updated using linkgit:git-fetch[1]; you can track other
2132public trees using linkgit:git-remote[1] to set up a "remote" and
7560f547 2133linkgit:git-fetch[1] to keep them up to date; see
6e30fb0c 2134<<repositories-and-branches>>.
9e2163ea
BF
2135
2136Now create the branches in which you are going to work; these start out
2137at the current tip of origin/master branch, and should be set up (using
1249d8ad 2138the `--track` option to linkgit:git-branch[1]) to merge changes in from
9e2163ea
BF
2139Linus by default.
2140
2141-------------------------------------------------
2142$ git branch --track test origin/master
2143$ git branch --track release origin/master
2144-------------------------------------------------
2145
5162e697 2146These can be easily kept up to date using linkgit:git-pull[1].
9e2163ea
BF
2147
2148-------------------------------------------------
328c6cb8
NTND
2149$ git switch test && git pull
2150$ git switch release && git pull
9e2163ea
BF
2151-------------------------------------------------
2152
2153Important note! If you have any local changes in these branches, then
2154this merge will create a commit object in the history (with no local
2de9b711 2155changes Git will simply do a "fast-forward" merge). Many people dislike
9e2163ea 2156the "noise" that this creates in the Linux history, so you should avoid
1249d8ad 2157doing this capriciously in the `release` branch, as these noisy commits
9e2163ea
BF
2158will become part of the permanent history when you ask Linus to pull
2159from the release branch.
2160
5162e697 2161A few configuration variables (see linkgit:git-config[1]) can
9e2163ea
BF
2162make it easy to push both branches to your public tree. (See
2163<<setting-up-a-public-repository>>.)
2164
2165-------------------------------------------------
2166$ cat >> .git/config <<EOF
2167[remote "mytree"]
283efb01 2168 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git
9e2163ea
BF
2169 push = release
2170 push = test
2171EOF
2172-------------------------------------------------
2173
2174Then you can push both the test and release trees using
5162e697 2175linkgit:git-push[1]:
9e2163ea
BF
2176
2177-------------------------------------------------
2178$ git push mytree
2179-------------------------------------------------
2180
2181or push just one of the test and release branches using:
2182
2183-------------------------------------------------
2184$ git push mytree test
2185-------------------------------------------------
2186
2187or
2188
2189-------------------------------------------------
2190$ git push mytree release
2191-------------------------------------------------
2192
2193Now to apply some patches from the community. Think of a short
2194snappy name for a branch to hold this patch (or related group of
352953a5
TL
2195patches), and create a new branch from a recent stable tag of
2196Linus's branch. Picking a stable base for your branch will:
21971) help you: by avoiding inclusion of unrelated and perhaps lightly
2198tested changes
1249d8ad 21992) help future bug hunters that use `git bisect` to find problems
9e2163ea
BF
2200
2201-------------------------------------------------
328c6cb8 2202$ git switch -c speed-up-spinlocks v2.6.35
9e2163ea
BF
2203-------------------------------------------------
2204
2205Now you apply the patch(es), run some tests, and commit the change(s). If
2206the patch is a multi-part series, then you should apply each as a separate
2207commit to this branch.
2208
2209-------------------------------------------------
2210$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
2211-------------------------------------------------
2212
a7bdee11 2213When you are happy with the state of this change, you can merge it into the
9e2163ea
BF
2214"test" branch in preparation to make it public:
2215
2216-------------------------------------------------
328c6cb8 2217$ git switch test && git merge speed-up-spinlocks
9e2163ea
BF
2218-------------------------------------------------
2219
2220It is unlikely that you would have any conflicts here ... but you might if you
2221spent a while on this step and had also pulled new versions from upstream.
2222
3c735e07 2223Sometime later when enough time has passed and testing done, you can pull the
1249d8ad 2224same branch into the `release` tree ready to go upstream. This is where you
9e2163ea 2225see the value of keeping each patch (or patch series) in its own branch. It
1249d8ad 2226means that the patches can be moved into the `release` tree in any order.
9e2163ea
BF
2227
2228-------------------------------------------------
328c6cb8 2229$ git switch release && git merge speed-up-spinlocks
9e2163ea
BF
2230-------------------------------------------------
2231
2232After a while, you will have a number of branches, and despite the
2233well chosen names you picked for each of them, you may forget what
2234they are for, or what status they are in. To get a reminder of what
2235changes are in a specific branch, use:
2236
2237-------------------------------------------------
467c0197 2238$ git log linux..branchname | git shortlog
9e2163ea
BF
2239-------------------------------------------------
2240
06ada152 2241To see whether it has already been merged into the test or release branches,
9e2163ea
BF
2242use:
2243
2244-------------------------------------------------
2245$ git log test..branchname
2246-------------------------------------------------
2247
2248or
2249
2250-------------------------------------------------
2251$ git log release..branchname
2252-------------------------------------------------
2253
06ada152 2254(If this branch has not yet been merged, you will see some log entries.
9e2163ea
BF
2255If it has been merged, then there will be no output.)
2256
2257Once a patch completes the great cycle (moving from test to release,
2258then pulled by Linus, and finally coming back into your local
1249d8ad 2259`origin/master` branch), the branch for this change is no longer needed.
9e2163ea
BF
2260You detect this when the output from:
2261
2262-------------------------------------------------
2263$ git log origin..branchname
2264-------------------------------------------------
2265
2266is empty. At this point the branch can be deleted:
2267
2268-------------------------------------------------
2269$ git branch -d branchname
2270-------------------------------------------------
2271
2272Some changes are so trivial that it is not necessary to create a separate
2273branch and then merge into each of the test and release branches. For
1249d8ad
TK
2274these changes, just apply directly to the `release` branch, and then
2275merge that into the `test` branch.
9e2163ea 2276
ae6ef554
TK
2277After pushing your work to `mytree`, you can use
2278linkgit:git-request-pull[1] to prepare a "please pull" request message
2279to send to Linus:
9e2163ea
BF
2280
2281-------------------------------------------------
ae6ef554
TK
2282$ git push mytree
2283$ git request-pull origin mytree release
9e2163ea
BF
2284-------------------------------------------------
2285
2286Here are some of the scripts that simplify all this even further.
2287
2288-------------------------------------------------
2289==== update script ====
48a8c26c 2290# Update a branch in my Git tree. If the branch to be updated
9e2163ea
BF
2291# is origin, then pull from kernel.org. Otherwise merge
2292# origin/master branch into test|release branch
2293
2294case "$1" in
2295test|release)
2296 git checkout $1 && git pull . origin
2297 ;;
2298origin)
fc74ecc1 2299 before=$(git rev-parse refs/remotes/origin/master)
9e2163ea 2300 git fetch origin
fc74ecc1 2301 after=$(git rev-parse refs/remotes/origin/master)
9e2163ea
BF
2302 if [ $before != $after ]
2303 then
2304 git log $before..$after | git shortlog
2305 fi
2306 ;;
2307*)
1a2ba8b9 2308 echo "usage: $0 origin|test|release" 1>&2
9e2163ea
BF
2309 exit 1
2310 ;;
2311esac
2312-------------------------------------------------
2313
2314-------------------------------------------------
2315==== merge script ====
2316# Merge a branch into either the test or release branch
2317
2318pname=$0
2319
2320usage()
2321{
1a2ba8b9 2322 echo "usage: $pname branch test|release" 1>&2
9e2163ea
BF
2323 exit 1
2324}
2325
fc74ecc1 2326git show-ref -q --verify -- refs/heads/"$1" || {
9e2163ea
BF
2327 echo "Can't see branch <$1>" 1>&2
2328 usage
fc74ecc1 2329}
9e2163ea
BF
2330
2331case "$2" in
2332test|release)
2333 if [ $(git log $2..$1 | wc -c) -eq 0 ]
2334 then
2335 echo $1 already merged into $2 1>&2
2336 exit 1
2337 fi
2338 git checkout $2 && git pull . $1
2339 ;;
2340*)
2341 usage
2342 ;;
2343esac
2344-------------------------------------------------
2345
2346-------------------------------------------------
2347==== status script ====
48a8c26c 2348# report on status of my ia64 Git tree
9e2163ea
BF
2349
2350gb=$(tput setab 2)
2351rb=$(tput setab 1)
2352restore=$(tput setab 9)
2353
2354if [ `git rev-list test..release | wc -c` -gt 0 ]
2355then
2356 echo $rb Warning: commits in release that are not in test $restore
2357 git log test..release
2358fi
2359
fc74ecc1 2360for branch in `git show-ref --heads | sed 's|^.*/||'`
9e2163ea
BF
2361do
2362 if [ $branch = test -o $branch = release ]
2363 then
2364 continue
2365 fi
2366
2367 echo -n $gb ======= $branch ====== $restore " "
2368 status=
2369 for ref in test release origin/master
2370 do
2371 if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
2372 then
2373 status=$status${ref:0:1}
2374 fi
2375 done
2376 case $status in
2377 trl)
2378 echo $rb Need to pull into test $restore
2379 ;;
2380 rl)
2381 echo "In test"
2382 ;;
2383 l)
2384 echo "Waiting for linus"
2385 ;;
2386 "")
2387 echo $rb All done $restore
2388 ;;
2389 *)
2390 echo $rb "<$status>" $restore
2391 ;;
2392 esac
2393 git log origin/master..$branch | git shortlog
2394done
2395-------------------------------------------------
d19fbc3c 2396
d19fbc3c 2397
d19fbc3c 2398[[cleaning-up-history]]
fd5b820d 2399== Rewriting history and maintaining patch series
4c63ff45
BF
2400
2401Normally commits are only added to a project, never taken away or
2402replaced. Git is designed with this assumption, and violating it will
2de9b711 2403cause Git's merge machinery (for example) to do the wrong thing.
4c63ff45
BF
2404
2405However, there is a situation in which it can be useful to violate this
2406assumption.
2407
e34caace 2408[[patch-series]]
fd5b820d 2409=== Creating the perfect patch series
4c63ff45
BF
2410
2411Suppose you are a contributor to a large project, and you want to add a
2412complicated feature, and to present it to the other developers in a way
2413that makes it easy for them to read your changes, verify that they are
2414correct, and understand why you made each change.
2415
b181d57f 2416If you present all of your changes as a single patch (or commit), they
79c96c57 2417may find that it is too much to digest all at once.
4c63ff45
BF
2418
2419If you present them with the entire history of your work, complete with
2420mistakes, corrections, and dead ends, they may be overwhelmed.
2421
2422So the ideal is usually to produce a series of patches such that:
2423
2424 1. Each patch can be applied in order.
2425
2426 2. Each patch includes a single logical change, together with a
2427 message explaining the change.
2428
2429 3. No patch introduces a regression: after applying any initial
2430 part of the series, the resulting project still compiles and
2431 works, and has no bugs that it didn't have before.
2432
2433 4. The complete series produces the same end result as your own
2434 (probably much messier!) development process did.
2435
b181d57f
BF
2436We will introduce some tools that can help you do this, explain how to
2437use them, and then explain some of the problems that can arise because
2438you are rewriting history.
4c63ff45 2439
e34caace 2440[[using-git-rebase]]
fd5b820d 2441=== Keeping a patch series up to date using git rebase
4c63ff45 2442
1249d8ad
TK
2443Suppose that you create a branch `mywork` on a remote-tracking branch
2444`origin`, and create some commits on top of it:
4c63ff45
BF
2445
2446-------------------------------------------------
328c6cb8 2447$ git switch -c mywork origin
4c63ff45
BF
2448$ vi file.txt
2449$ git commit
2450$ vi otherfile.txt
2451$ git commit
2452...
2453-------------------------------------------------
2454
2455You have performed no merges into mywork, so it is just a simple linear
1249d8ad 2456sequence of patches on top of `origin`:
4c63ff45 2457
1dc71a91 2458................................................
fa8347b8 2459 o--o--O <-- origin
4c63ff45 2460 \
fa8347b8 2461 a--b--c <-- mywork
1dc71a91 2462................................................
4c63ff45
BF
2463
2464Some more interesting work has been done in the upstream project, and
1249d8ad 2465`origin` has advanced:
4c63ff45 2466
1dc71a91 2467................................................
4c63ff45
BF
2468 o--o--O--o--o--o <-- origin
2469 \
2470 a--b--c <-- mywork
1dc71a91 2471................................................
4c63ff45 2472
1249d8ad 2473At this point, you could use `pull` to merge your changes back in;
4c63ff45
BF
2474the result would create a new merge commit, like this:
2475
1dc71a91 2476................................................
4c63ff45
BF
2477 o--o--O--o--o--o <-- origin
2478 \ \
2479 a--b--c--m <-- mywork
1dc71a91 2480................................................
a6080a0a 2481
4c63ff45
BF
2482However, if you prefer to keep the history in mywork a simple series of
2483commits without any merges, you may instead choose to use
5162e697 2484linkgit:git-rebase[1]:
4c63ff45
BF
2485
2486-------------------------------------------------
328c6cb8 2487$ git switch mywork
4c63ff45
BF
2488$ git rebase origin
2489-------------------------------------------------
2490
b181d57f 2491This will remove each of your commits from mywork, temporarily saving
1249d8ad 2492them as patches (in a directory named `.git/rebase-apply`), update mywork to
b181d57f
BF
2493point at the latest version of origin, then apply each of the saved
2494patches to the new mywork. The result will look like:
4c63ff45
BF
2495
2496
1dc71a91 2497................................................
4c63ff45
BF
2498 o--o--O--o--o--o <-- origin
2499 \
2500 a'--b'--c' <-- mywork
1dc71a91 2501................................................
4c63ff45 2502
b181d57f 2503In the process, it may discover conflicts. In that case it will stop
6127c086 2504and allow you to fix the conflicts; after fixing conflicts, use `git add`
7a7d4ef6 2505to update the index with those contents, and then, instead of
6127c086 2506running `git commit`, just run
4c63ff45
BF
2507
2508-------------------------------------------------
2509$ git rebase --continue
2510-------------------------------------------------
2511
2de9b711 2512and Git will continue applying the rest of the patches.
4c63ff45 2513
b6cbca38 2514At any point you may use the `--abort` option to abort this process and
4c63ff45
BF
2515return mywork to the state it had before you started the rebase:
2516
2517-------------------------------------------------
2518$ git rebase --abort
2519-------------------------------------------------
2520
6c26bf4d
TK
2521If you need to reorder or edit a number of commits in a branch, it may
2522be easier to use `git rebase -i`, which allows you to reorder and
2523squash commits, as well as marking them for individual editing during
2524the rebase. See <<interactive-rebase>> for details, and
2525<<reordering-patch-series>> for alternatives.
2526
7cb192ea 2527[[rewriting-one-commit]]
fd5b820d 2528=== Rewriting a single commit
365aa199 2529
7cb192ea 2530We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
365aa199
BF
2531most recent commit using
2532
2533-------------------------------------------------
2534$ git commit --amend
2535-------------------------------------------------
2536
2537which will replace the old commit by a new commit incorporating your
2538changes, giving you a chance to edit the old commit message first.
6c26bf4d
TK
2539This is useful for fixing typos in your last commit, or for adjusting
2540the patch contents of a poorly staged commit.
365aa199 2541
6c26bf4d
TK
2542If you need to amend commits from deeper in your history, you can
2543use <<interactive-rebase,interactive rebase's `edit` instruction>>.
365aa199 2544
6c26bf4d 2545[[reordering-patch-series]]
fd5b820d 2546=== Reordering or selecting from a patch series
365aa199 2547
6c26bf4d
TK
2548Sometimes you want to edit a commit deeper in your history. One
2549approach is to use `git format-patch` to create a series of patches
2550and then reset the state to before the patches:
365aa199
BF
2551
2552-------------------------------------------------
6c26bf4d
TK
2553$ git format-patch origin
2554$ git reset --hard origin
365aa199
BF
2555-------------------------------------------------
2556
6c26bf4d
TK
2557Then modify, reorder, or eliminate patches as needed before applying
2558them again with linkgit:git-am[1]:
365aa199
BF
2559
2560-------------------------------------------------
6c26bf4d 2561$ git am *.patch
365aa199
BF
2562-------------------------------------------------
2563
6c26bf4d 2564[[interactive-rebase]]
fd5b820d 2565=== Using interactive rebases
365aa199 2566
6c26bf4d
TK
2567You can also edit a patch series with an interactive rebase. This is
2568the same as <<reordering-patch-series,reordering a patch series using
2569`format-patch`>>, so use whichever interface you like best.
4c63ff45 2570
6c26bf4d
TK
2571Rebase your current HEAD on the last commit you want to retain as-is.
2572For example, if you want to reorder the last 5 commits, use:
b181d57f
BF
2573
2574-------------------------------------------------
6c26bf4d 2575$ git rebase -i HEAD~5
b181d57f
BF
2576-------------------------------------------------
2577
6c26bf4d
TK
2578This will open your editor with a list of steps to be taken to perform
2579your rebase.
4c63ff45 2580
b181d57f 2581-------------------------------------------------
6c26bf4d
TK
2582pick deadbee The oneline of this commit
2583pick fa1afe1 The oneline of the next commit
2584...
4c63ff45 2585
6c26bf4d
TK
2586# Rebase c0ffeee..deadbee onto c0ffeee
2587#
2588# Commands:
2589# p, pick = use commit
2590# r, reword = use commit, but edit the commit message
2591# e, edit = use commit, but stop for amending
2592# s, squash = use commit, but meld into previous commit
2593# f, fixup = like "squash", but discard this commit's log message
2594# x, exec = run command (the rest of the line) using shell
2595#
2596# These lines can be re-ordered; they are executed from top to bottom.
2597#
2598# If you remove a line here THAT COMMIT WILL BE LOST.
2599#
2600# However, if you remove everything, the rebase will be aborted.
2601#
2602# Note that empty commits are commented out
2603-------------------------------------------------
2604
2605As explained in the comments, you can reorder commits, squash them
2606together, edit commit messages, etc. by editing the list. Once you
2607are satisfied, save the list and close your editor, and the rebase
2608will begin.
2609
2610The rebase will stop where `pick` has been replaced with `edit` or
2611when a step in the list fails to mechanically resolve conflicts and
2612needs your help. When you are done editing and/or resolving conflicts
2613you can continue with `git rebase --continue`. If you decide that
2614things are getting too hairy, you can always bail out with `git rebase
2615--abort`. Even after the rebase is complete, you can still recover
2616the original branch by using the <<reflogs,reflog>>.
2617
2618For a more detailed discussion of the procedure and additional tips,
2619see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
4c63ff45 2620
e34caace 2621[[patch-series-tools]]
fd5b820d 2622=== Other tools
4c63ff45 2623
73a1d050 2624There are numerous other tools, such as StGit, which exist for the
79c96c57 2625purpose of maintaining a patch series. These are outside of the scope of
b181d57f 2626this manual.
4c63ff45 2627
aa971cb9 2628[[problems-With-rewriting-history]]
fd5b820d 2629=== Problems with rewriting history
4c63ff45 2630
b181d57f
BF
2631The primary problem with rewriting the history of a branch has to do
2632with merging. Suppose somebody fetches your branch and merges it into
2633their branch, with a result something like this:
2634
1dc71a91 2635................................................
b181d57f
BF
2636 o--o--O--o--o--o <-- origin
2637 \ \
2638 t--t--t--m <-- their branch:
1dc71a91 2639................................................
b181d57f
BF
2640
2641Then suppose you modify the last three commits:
2642
1dc71a91 2643................................................
b181d57f
BF
2644 o--o--o <-- new head of origin
2645 /
2646 o--o--O--o--o--o <-- old head of origin
1dc71a91 2647................................................
b181d57f
BF
2648
2649If we examined all this history together in one repository, it will
2650look like:
2651
1dc71a91 2652................................................
b181d57f
BF
2653 o--o--o <-- new head of origin
2654 /
2655 o--o--O--o--o--o <-- old head of origin
2656 \ \
2657 t--t--t--m <-- their branch:
1dc71a91 2658................................................
b181d57f
BF
2659
2660Git has no way of knowing that the new head is an updated version of
2661the old head; it treats this situation exactly the same as it would if
2662two developers had independently done the work on the old and new heads
2663in parallel. At this point, if someone attempts to merge the new head
2de9b711 2664in to their branch, Git will attempt to merge together the two (old and
b181d57f
BF
2665new) lines of development, instead of trying to replace the old by the
2666new. The results are likely to be unexpected.
2667
2668You may still choose to publish branches whose history is rewritten,
2669and it may be useful for others to be able to fetch those branches in
2670order to examine or test them, but they should not attempt to pull such
2671branches into their own work.
2672
2673For true distributed development that supports proper merging,
2674published branches should never be rewritten.
2675
3fb00282 2676[[bisect-merges]]
fd5b820d 2677=== Why bisecting merge commits can be harder than bisecting linear history
3fb00282 2678
5162e697 2679The linkgit:git-bisect[1] command correctly handles history that
3fb00282
SP
2680includes merge commits. However, when the commit that it finds is a
2681merge commit, the user may need to work harder than usual to figure out
2682why that commit introduced a problem.
2683
2684Imagine this history:
2685
2686................................................
2687 ---Z---o---X---...---o---A---C---D
2688 \ /
2689 o---o---Y---...---o---B
2690................................................
2691
2692Suppose that on the upper line of development, the meaning of one
2693of the functions that exists at Z is changed at commit X. The
2694commits from Z leading to A change both the function's
2695implementation and all calling sites that exist at Z, as well
2696as new calling sites they add, to be consistent. There is no
2697bug at A.
2698
2699Suppose that in the meantime on the lower line of development somebody
2700adds a new calling site for that function at commit Y. The
2701commits from Z leading to B all assume the old semantics of that
2702function and the callers and the callee are consistent with each
2703other. There is no bug at B, either.
2704
2705Suppose further that the two development lines merge cleanly at C,
2706so no conflict resolution is required.
2707
2708Nevertheless, the code at C is broken, because the callers added
2709on the lower line of development have not been converted to the new
2710semantics introduced on the upper line of development. So if all
2711you know is that D is bad, that Z is good, and that
5162e697 2712linkgit:git-bisect[1] identifies C as the culprit, how will you
3fb00282
SP
2713figure out that the problem is due to this change in semantics?
2714
6127c086 2715When the result of a `git bisect` is a non-merge commit, you should
3fb00282
SP
2716normally be able to discover the problem by examining just that commit.
2717Developers can make this easy by breaking their changes into small
2718self-contained commits. That won't help in the case above, however,
2719because the problem isn't obvious from examination of any single
2720commit; instead, a global view of the development is required. To
2721make matters worse, the change in semantics in the problematic
2722function may be just one small part of the changes in the upper
2723line of development.
2724
2725On the other hand, if instead of merging at C you had rebased the
2726history between Z to B on top of A, you would have gotten this
2727linear history:
2728
2729................................................................
2730 ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
2731................................................................
2732
2733Bisecting between Z and D* would hit a single culprit commit Y*,
2734and understanding why Y* was broken would probably be easier.
2735
2de9b711 2736Partly for this reason, many experienced Git users, even when
3fb00282
SP
2737working on an otherwise merge-heavy project, keep the history
2738linear by rebasing against the latest upstream version before
2739publishing.
2740
e34caace 2741[[advanced-branch-management]]
fd5b820d 2742== Advanced branch management
4c63ff45 2743
e34caace 2744[[fetching-individual-branches]]
fd5b820d 2745=== Fetching individual branches
b181d57f 2746
5162e697 2747Instead of using linkgit:git-remote[1], you can also choose just
b181d57f
BF
2748to update one branch at a time, and to store it locally under an
2749arbitrary name:
2750
2751-------------------------------------------------
2752$ git fetch origin todo:my-todo-work
2753-------------------------------------------------
2754
1249d8ad 2755The first argument, `origin`, just tells Git to fetch from the
2de9b711 2756repository you originally cloned from. The second argument tells Git
1249d8ad
TK
2757to fetch the branch named `todo` from the remote repository, and to
2758store it locally under the name `refs/heads/my-todo-work`.
b181d57f
BF
2759
2760You can also fetch branches from other repositories; so
2761
2762-------------------------------------------------
2763$ git fetch git://example.com/proj.git master:example-master
2764-------------------------------------------------
2765
1249d8ad
TK
2766will create a new branch named `example-master` and store in it the
2767branch named `master` from the repository at the given URL. If you
b181d57f 2768already have a branch named example-master, it will attempt to
59723040
BF
2769<<fast-forwards,fast-forward>> to the commit given by example.com's
2770master branch. In more detail:
b181d57f 2771
59723040 2772[[fetch-fast-forwards]]
fd5b820d 2773=== git fetch and fast-forwards
b181d57f 2774
1249d8ad 2775In the previous example, when updating an existing branch, `git fetch`
7a7d4ef6 2776checks to make sure that the most recent commit on the remote
b181d57f
BF
2777branch is a descendant of the most recent commit on your copy of the
2778branch before updating your copy of the branch to point at the new
a75d7b54 2779commit. Git calls this process a <<fast-forwards,fast-forward>>.
b181d57f 2780
a75d7b54 2781A fast-forward looks something like this:
b181d57f 2782
1dc71a91 2783................................................
b181d57f
BF
2784 o--o--o--o <-- old head of the branch
2785 \
2786 o--o--o <-- new head of the branch
1dc71a91 2787................................................
b181d57f
BF
2788
2789
2790In some cases it is possible that the new head will *not* actually be
2791a descendant of the old head. For example, the developer may have
2792realized she made a serious mistake, and decided to backtrack,
2793resulting in a situation like:
2794
1dc71a91 2795................................................
b181d57f
BF
2796 o--o--o--o--a--b <-- old head of the branch
2797 \
2798 o--o--o <-- new head of the branch
1dc71a91 2799................................................
b181d57f 2800
1249d8ad 2801In this case, `git fetch` will fail, and print out a warning.
b181d57f 2802
2de9b711 2803In that case, you can still force Git to update to the new head, as
b181d57f 2804described in the following section. However, note that in the
1249d8ad 2805situation above this may mean losing the commits labeled `a` and `b`,
b181d57f
BF
2806unless you've already created a reference of your own pointing to
2807them.
2808
e34caace 2809[[forcing-fetch]]
fd5b820d 2810=== Forcing git fetch to do non-fast-forward updates
b181d57f
BF
2811
2812If git fetch fails because the new head of a branch is not a
2813descendant of the old head, you may force the update with:
2814
2815-------------------------------------------------
2816$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
2817-------------------------------------------------
2818
1249d8ad 2819Note the addition of the `+` sign. Alternatively, you can use the `-f`
c64415e2
BF
2820flag to force updates of all the fetched branches, as in:
2821
2822-------------------------------------------------
2823$ git fetch -f origin
2824-------------------------------------------------
2825
2826Be aware that commits that the old version of example/master pointed at
2827may be lost, as we saw in the previous section.
b181d57f 2828
e34caace 2829[[remote-branch-configuration]]
fd5b820d 2830=== Configuring remote-tracking branches
b181d57f 2831
1249d8ad 2832We saw above that `origin` is just a shortcut to refer to the
79c96c57 2833repository that you originally cloned from. This information is
2de9b711 2834stored in Git configuration variables, which you can see using
5162e697 2835linkgit:git-config[1]:
b181d57f
BF
2836
2837-------------------------------------------------
9d13bda3 2838$ git config -l
b181d57f
BF
2839core.repositoryformatversion=0
2840core.filemode=true
2841core.logallrefupdates=true
2842remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
2843remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
2844branch.master.remote=origin
2845branch.master.merge=refs/heads/master
2846-------------------------------------------------
2847
2848If there are other repositories that you also use frequently, you can
2849create similar configuration options to save typing; for example,
b181d57f
BF
2850
2851-------------------------------------------------
47adb8ac 2852$ git remote add example git://example.com/proj.git
b181d57f
BF
2853-------------------------------------------------
2854
47adb8ac 2855adds the following to `.git/config`:
b181d57f
BF
2856
2857-------------------------------------------------
47adb8ac
TK
2858[remote "example"]
2859 url = git://example.com/proj.git
2860 fetch = +refs/heads/*:refs/remotes/example/*
b181d57f
BF
2861-------------------------------------------------
2862
47adb8ac
TK
2863Also note that the above configuration can be performed by directly
2864editing the file `.git/config` instead of using linkgit:git-remote[1].
b181d57f 2865
47adb8ac
TK
2866After configuring the remote, the following three commands will do the
2867same thing:
b181d57f
BF
2868
2869-------------------------------------------------
47adb8ac
TK
2870$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
2871$ git fetch example +refs/heads/*:refs/remotes/example/*
b181d57f
BF
2872$ git fetch example
2873-------------------------------------------------
2874
5162e697 2875See linkgit:git-config[1] for more details on the configuration
47adb8ac
TK
2876options mentioned above and linkgit:git-fetch[1] for more details on
2877the refspec syntax.
d19fbc3c 2878
d19fbc3c 2879
036f8199 2880[[git-concepts]]
fd5b820d 2881== Git concepts
d19fbc3c 2882
036f8199
BF
2883Git is built on a small number of simple but powerful ideas. While it
2884is possible to get things done without understanding them, you will find
2de9b711 2885Git much more intuitive if you do.
036f8199
BF
2886
2887We start with the most important, the <<def_object_database,object
2888database>> and the <<def_index,index>>.
b181d57f 2889
e34caace 2890[[the-object-database]]
fd5b820d 2891=== The Object Database
b181d57f 2892
1bbf1c79
BF
2893
2894We already saw in <<understanding-commits>> that all commits are stored
2895under a 40-digit "object name". In fact, all the information needed to
2896represent the history of a project is stored in objects with such names.
a6e5ef7d
FC
2897In each case the name is calculated by taking the SHA-1 hash of the
2898contents of the object. The SHA-1 hash is a cryptographic hash function.
1bbf1c79
BF
2899What that means to us is that it is impossible to find two different
2900objects with the same name. This has a number of advantages; among
2901others:
2902
2903- Git can quickly determine whether two objects are identical or not,
2904 just by comparing names.
06ada152 2905- Since object names are computed the same way in every repository, the
1bbf1c79
BF
2906 same content stored in two repositories will always be stored under
2907 the same name.
2908- Git can detect errors when it reads an object, by checking that the
a6e5ef7d 2909 object's name is still the SHA-1 hash of its contents.
1bbf1c79
BF
2910
2911(See <<object-details>> for the details of the object formatting and
a6e5ef7d 2912SHA-1 calculation.)
1bbf1c79
BF
2913
2914There are four different types of objects: "blob", "tree", "commit", and
2915"tag".
2916
2917- A <<def_blob_object,"blob" object>> is used to store file data.
843c81dc 2918- A <<def_tree_object,"tree" object>> ties one or more
1bbf1c79
BF
2919 "blob" objects into a directory structure. In addition, a tree object
2920 can refer to other tree objects, thus creating a directory hierarchy.
2921- A <<def_commit_object,"commit" object>> ties such directory hierarchies
2ef8ac1b 2922 together into a <<def_DAG,directed acyclic graph>> of revisions--each
1bbf1c79
BF
2923 commit contains the object name of exactly one tree designating the
2924 directory hierarchy at the time of the commit. In addition, a commit
2925 refers to "parent" commit objects that describe the history of how we
2926 arrived at that directory hierarchy.
2927- A <<def_tag_object,"tag" object>> symbolically identifies and can be
2928 used to sign other objects. It contains the object name and type of
2929 another object, a symbolic name (of course!) and, optionally, a
2930 signature.
b181d57f 2931
b181d57f
BF
2932The object types in some more detail:
2933
513d419c 2934[[commit-object]]
fd5b820d 2935==== Commit Object
b181d57f 2936
1bbf1c79 2937The "commit" object links a physical state of a tree with a description
1249d8ad 2938of how we got there and why. Use the `--pretty=raw` option to
5162e697 2939linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
1bbf1c79
BF
2940commit:
2941
2942------------------------------------------------
2943$ git show -s --pretty=raw 2be7fcb476
2944commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
2945tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
2946parent 257a84d9d02e90447b149af58b271c19405edb6a
2947author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
2948committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
2949
2950 Fix misspelling of 'suppress' in docs
2951
2952 Signed-off-by: Junio C Hamano <gitster@pobox.com>
2953------------------------------------------------
2954
2955As you can see, a commit is defined by:
2956
a6e5ef7d 2957- a tree: The SHA-1 name of a tree object (as defined below), representing
1bbf1c79 2958 the contents of a directory at a certain point in time.
edfbbf7e 2959- parent(s): The SHA-1 name(s) of some number of commits which represent the
9e5d87d4 2960 immediately previous step(s) in the history of the project. The
1bbf1c79
BF
2961 example above has one parent; merge commits may have more than
2962 one. A commit with no parents is called a "root" commit, and
2963 represents the initial revision of a project. Each project must have
2964 at least one root. A project can also have multiple roots, though
2965 that isn't common (or necessarily a good idea).
2966- an author: The name of the person responsible for this change, together
2967 with its date.
2968- a committer: The name of the person who actually created the commit,
2969 with the date it was done. This may be different from the author, for
2970 example, if the author was someone who wrote a patch and emailed it
2971 to the person who used it to create the commit.
2972- a comment describing this commit.
2973
2974Note that a commit does not itself contain any information about what
2975actually changed; all changes are calculated by comparing the contents
2976of the tree referred to by this commit with the trees associated with
2de9b711 2977its parents. In particular, Git does not attempt to record file renames
1bbf1c79
BF
2978explicitly, though it can identify cases where the existence of the same
2979file data at changing paths suggests a rename. (See, for example, the
1249d8ad 2980`-M` option to linkgit:git-diff[1]).
1bbf1c79 2981
5162e697 2982A commit is usually created by linkgit:git-commit[1], which creates a
1bbf1c79
BF
2983commit whose parent is normally the current HEAD, and whose tree is
2984taken from the content currently stored in the index.
b181d57f 2985
e34caace 2986[[tree-object]]
fd5b820d 2987==== Tree Object
b181d57f 2988
5162e697
DM
2989The ever-versatile linkgit:git-show[1] command can also be used to
2990examine tree objects, but linkgit:git-ls-tree[1] will give you more
1bbf1c79
BF
2991details:
2992
2993------------------------------------------------
2994$ git ls-tree fb3a8bdd0ce
2995100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
2996100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
2997100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
2998040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
2999100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
3000100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
3001100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
3002100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
3003...
3004------------------------------------------------
3005
3006As you can see, a tree object contains a list of entries, each with a
a6e5ef7d 3007mode, object type, SHA-1 name, and name, sorted by name. It represents
1bbf1c79
BF
3008the contents of a single directory tree.
3009
3010The object type may be a blob, representing the contents of a file, or
3011another tree, representing the contents of a subdirectory. Since trees
a6e5ef7d
FC
3012and blobs, like all other objects, are named by the SHA-1 hash of their
3013contents, two trees have the same SHA-1 name if and only if their
1bbf1c79 3014contents (including, recursively, the contents of all subdirectories)
2de9b711 3015are identical. This allows Git to quickly determine the differences
1bbf1c79
BF
3016between two related tree objects, since it can ignore any entries with
3017identical object names.
3018
3019(Note: in the presence of submodules, trees may also have commits as
6dd14366 3020entries. See <<submodules>> for documentation.)
1bbf1c79 3021
2de9b711 3022Note that the files all have mode 644 or 755: Git actually only pays
1bbf1c79 3023attention to the executable bit.
b181d57f 3024
513d419c 3025[[blob-object]]
fd5b820d 3026==== Blob Object
b181d57f 3027
5162e697 3028You can use linkgit:git-show[1] to examine the contents of a blob; take,
1249d8ad 3029for example, the blob in the entry for `COPYING` from the tree above:
b181d57f 3030
1bbf1c79
BF
3031------------------------------------------------
3032$ git show 6ff87c4664
3033
3034 Note that the only valid version of the GPL as far as this project
3035 is concerned is _this_ particular version of the license (ie v2, not
3036 v2.2 or v3.x or whatever), unless explicitly otherwise stated.
3037...
3038------------------------------------------------
b181d57f 3039
1bbf1c79
BF
3040A "blob" object is nothing but a binary blob of data. It doesn't refer
3041to anything else or have attributes of any kind.
3042
3043Since the blob is entirely defined by its data, if two files in a
3044directory tree (or in multiple different versions of the repository)
3045have the same contents, they will share the same blob object. The object
3046is totally independent of its location in the directory tree, and
3047renaming a file does not change the object that file is associated with.
3048
3049Note that any tree or blob object can be examined using
5162e697 3050linkgit:git-show[1] with the <revision>:<path> syntax. This can
1bbf1c79
BF
3051sometimes be useful for browsing the contents of a tree that is not
3052currently checked out.
b181d57f 3053
e34caace 3054[[trust]]
fd5b820d 3055==== Trust
b181d57f 3056
a6e5ef7d 3057If you receive the SHA-1 name of a blob from one source, and its contents
1bbf1c79 3058from another (possibly untrusted) source, you can still trust that those
a6e5ef7d
FC
3059contents are correct as long as the SHA-1 name agrees. This is because
3060the SHA-1 is designed so that it is infeasible to find different contents
1bbf1c79 3061that produce the same hash.
b181d57f 3062
a6e5ef7d 3063Similarly, you need only trust the SHA-1 name of a top-level tree object
1bbf1c79 3064to trust the contents of the entire directory that it refers to, and if
a6e5ef7d 3065you receive the SHA-1 name of a commit from a trusted source, then you
1bbf1c79
BF
3066can easily verify the entire history of commits reachable through
3067parents of that commit, and all of those contents of the trees referred
3068to by those commits.
b181d57f
BF
3069
3070So to introduce some real trust in the system, the only thing you need
3071to do is to digitally sign just 'one' special note, which includes the
3072name of a top-level commit. Your digital signature shows others
3073that you trust that commit, and the immutability of the history of
3074commits tells others that they can trust the whole history.
3075
3076In other words, you can easily validate a whole archive by just
a6e5ef7d 3077sending out a single email that tells the people