user-manual.txt: change header notation
[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
1834 you push
1835 your personal repo ------------------> your public repo
a6080a0a 1836 ^ |
d19fbc3c
BF
1837 | |
1838 | you pull | they pull
1839 | |
1840 | |
1841 | they push V
1842 their public repo <------------------- their repo
1843
11d51533
BF
1844We explain how to do this in the following sections.
1845
eda69449 1846[[setting-up-a-public-repository]]
fd5b820d 1847==== Setting up a public repository
eda69449 1848
1249d8ad 1849Assume your personal repository is in the directory `~/proj`. We
6127c086 1850first create a new clone of the repository and tell `git daemon` that it
eda69449 1851is meant to be public:
d19fbc3c
BF
1852
1853-------------------------------------------------
52c80037 1854$ git clone --bare ~/proj proj.git
eda69449 1855$ touch proj.git/git-daemon-export-ok
d19fbc3c
BF
1856-------------------------------------------------
1857
52c80037 1858The resulting directory proj.git contains a "bare" git repository--it is
1249d8ad 1859just the contents of the `.git` directory, without any files checked out
eda69449 1860around it.
d19fbc3c 1861
1249d8ad 1862Next, copy `proj.git` to the server where you plan to host the
d19fbc3c
BF
1863public repository. You can use scp, rsync, or whatever is most
1864convenient.
1865
eda69449 1866[[exporting-via-git]]
fd5b820d 1867==== Exporting a Git repository via the Git protocol
eda69449
BF
1868
1869This is the preferred method.
1870
1871If someone else administers the server, they should tell you what
1249d8ad
TK
1872directory to put the repository in, and what `git://` URL it will
1873appear at. You can then skip to the section
d19fbc3c
BF
1874"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1875repository>>", below.
1876
5162e697 1877Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
eda69449 1878listen on port 9418. By default, it will allow access to any directory
2de9b711 1879that looks like a Git directory and contains the magic file
6127c086 1880git-daemon-export-ok. Passing some directory paths as `git daemon`
eda69449
BF
1881arguments will further restrict the exports to those paths.
1882
6127c086 1883You can also run `git daemon` as an inetd service; see the
5162e697 1884linkgit:git-daemon[1] man page for details. (See especially the
eda69449 1885examples section.)
d19fbc3c
BF
1886
1887[[exporting-via-http]]
fd5b820d 1888==== Exporting a git repository via HTTP
d19fbc3c 1889
2de9b711 1890The Git protocol gives better performance and reliability, but on a
de3f2c7b 1891host with a web server set up, HTTP exports may be simpler to set up.
d19fbc3c 1892
2de9b711 1893All you need to do is place the newly created bare Git repository in
d19fbc3c
BF
1894a directory that is exported by the web server, and make some
1895adjustments to give web clients some extra information they need:
1896
1897-------------------------------------------------
1898$ mv proj.git /home/you/public_html/proj.git
1899$ cd proj.git
c64415e2 1900$ git --bare update-server-info
7dce9918 1901$ mv hooks/post-update.sample hooks/post-update
d19fbc3c
BF
1902-------------------------------------------------
1903
1904(For an explanation of the last two lines, see
6998e4db 1905linkgit:git-update-server-info[1] and linkgit:githooks[5].)
d19fbc3c 1906
1249d8ad 1907Advertise the URL of `proj.git`. Anybody else should then be able to
c9016158 1908clone or pull from that URL, for example with a command line like:
d19fbc3c
BF
1909
1910-------------------------------------------------
1911$ git clone http://yourserver.com/~you/proj.git
1912-------------------------------------------------
1913
1914(See also
d5ff3b4b 1915link:howto/setup-git-server-over-http.html[setup-git-server-over-http]
d19fbc3c 1916for a slightly more sophisticated setup using WebDAV which also
de3f2c7b 1917allows pushing over HTTP.)
d19fbc3c 1918
d19fbc3c 1919[[pushing-changes-to-a-public-repository]]
fd5b820d 1920==== Pushing changes to a public repository
d19fbc3c 1921
eda69449 1922Note that the two techniques outlined above (exporting via
d19fbc3c
BF
1923<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1924maintainers to fetch your latest changes, but they do not allow write
1925access, which you will need to update the public repository with the
1926latest changes created in your private repository.
1927
5162e697 1928The simplest way to do this is using linkgit:git-push[1] and ssh; to
1249d8ad
TK
1929update the remote branch named `master` with the latest state of your
1930branch named `master`, run
d19fbc3c
BF
1931
1932-------------------------------------------------
1933$ git push ssh://yourserver.com/~you/proj.git master:master
1934-------------------------------------------------
1935
1936or just
1937
1938-------------------------------------------------
1939$ git push ssh://yourserver.com/~you/proj.git master
1940-------------------------------------------------
1941
6127c086 1942As with `git fetch`, `git push` will complain if this does not result in a
a75d7b54 1943<<fast-forwards,fast-forward>>; see the following section for details on
81eb417a 1944handling this case.
d19fbc3c 1945
1249d8ad 1946Note that the target of a `push` is normally a
11d51533 1947<<def_bare_repository,bare>> repository. You can also push to a
d9be2485
TK
1948repository that has a checked-out working tree, but a push to update the
1949currently checked-out branch is denied by default to prevent confusion.
50995edd 1950See the description of the receive.denyCurrentBranch option
d9be2485 1951in linkgit:git-config[1] for details.
11d51533 1952
6127c086 1953As with `git fetch`, you may also set up configuration options to
e9b49083
TK
1954save typing; so, for example:
1955
1956-------------------------------------------------
1957$ git remote add public-repo ssh://yourserver.com/~you/proj.git
1958-------------------------------------------------
1959
1960adds the following to `.git/config`:
d19fbc3c
BF
1961
1962-------------------------------------------------
d19fbc3c 1963[remote "public-repo"]
e9b49083
TK
1964 url = yourserver.com:proj.git
1965 fetch = +refs/heads/*:refs/remotes/example/*
d19fbc3c
BF
1966-------------------------------------------------
1967
e9b49083 1968which lets you do the same push with just
d19fbc3c
BF
1969
1970-------------------------------------------------
1971$ git push public-repo master
1972-------------------------------------------------
1973
1249d8ad
TK
1974See the explanations of the `remote.<name>.url`,
1975`branch.<name>.remote`, and `remote.<name>.push` options in
1976linkgit:git-config[1] for details.
d19fbc3c 1977
81eb417a 1978[[forcing-push]]
fd5b820d 1979==== What to do when a push fails
81eb417a 1980
a75d7b54 1981If a push would not result in a <<fast-forwards,fast-forward>> of the
81eb417a
BF
1982remote branch, then it will fail with an error like:
1983
1984-------------------------------------------------
3c82eec8
1985 ! [rejected] master -> master (non-fast-forward)
1986error: failed to push some refs to '...'
1987hint: Updates were rejected because the tip of your current branch is behind
1988hint: its remote counterpart. Integrate the remote changes (e.g.
1989hint: 'git pull ...') before pushing again.
1990hint: See the 'Note about fast-forwards' in 'git push --help' for details.
81eb417a
BF
1991-------------------------------------------------
1992
1993This can happen, for example, if you:
1994
6127c086
FC
1995 - use `git reset --hard` to remove already-published commits, or
1996 - use `git commit --amend` to replace already-published commits
7cb192ea 1997 (as in <<fixing-a-mistake-by-rewriting-history>>), or
6127c086 1998 - use `git rebase` to rebase any already-published commits (as
81eb417a
BF
1999 in <<using-git-rebase>>).
2000
6127c086 2001You may force `git push` to perform the update anyway by preceding the
81eb417a
BF
2002branch name with a plus sign:
2003
2004-------------------------------------------------
2005$ git push ssh://yourserver.com/~you/proj.git +master
2006-------------------------------------------------
2007
d1471e06
TK
2008Note the addition of the `+` sign. Alternatively, you can use the
2009`-f` flag to force the remote update, as in:
2010
2011-------------------------------------------------
2012$ git push -f ssh://yourserver.com/~you/proj.git master
2013-------------------------------------------------
2014
81eb417a 2015Normally whenever a branch head in a public repository is modified, it
9e5d87d4 2016is modified to point to a descendant of the commit that it pointed to
81eb417a 2017before. By forcing a push in this situation, you break that convention.
aa971cb9 2018(See <<problems-With-rewriting-history>>.)
81eb417a
BF
2019
2020Nevertheless, this is a common practice for people that need a simple
2021way to publish a work-in-progress patch series, and it is an acceptable
2022compromise as long as you warn other developers that this is how you
2023intend to manage the branch.
2024
2025It's also possible for a push to fail in this way when other people have
2026the right to push to the same repository. In that case, the correct
843c81dc
EH
2027solution is to retry the push after first updating your work: either by a
2028pull, or by a fetch followed by a rebase; see the
81eb417a 2029<<setting-up-a-shared-repository,next section>> and
6998e4db 2030linkgit:gitcvs-migration[7] for more.
81eb417a 2031
e34caace 2032[[setting-up-a-shared-repository]]
fd5b820d 2033==== Setting up a shared repository
d19fbc3c
BF
2034
2035Another way to collaborate is by using a model similar to that
2036commonly used in CVS, where several developers with special rights
2037all push to and pull from a single shared repository. See
6998e4db 2038linkgit:gitcvs-migration[7] for instructions on how to
d19fbc3c
BF
2039set this up.
2040
2de9b711 2041However, while there is nothing wrong with Git's support for shared
8fae2225 2042repositories, this mode of operation is not generally recommended,
2de9b711 2043simply because the mode of collaboration that Git supports--by
8fae2225
BF
2044exchanging patches and pulling from public repositories--has so many
2045advantages over the central shared repository:
2046
2047 - Git's ability to quickly import and merge patches allows a
2048 single maintainer to process incoming changes even at very
6127c086 2049 high rates. And when that becomes too much, `git pull` provides
8fae2225
BF
2050 an easy way for that maintainer to delegate this job to other
2051 maintainers while still allowing optional review of incoming
2052 changes.
2053 - Since every developer's repository has the same complete copy
2054 of the project history, no repository is special, and it is
2055 trivial for another developer to take over maintenance of a
2056 project, either by mutual agreement, or because a maintainer
2057 becomes unresponsive or difficult to work with.
2058 - The lack of a central group of "committers" means there is
2059 less need for formal decisions about who is "in" and who is
2060 "out".
2061
e34caace 2062[[setting-up-gitweb]]
fd5b820d 2063==== Allowing web browsing of a repository
d19fbc3c 2064
a8cd1402 2065The gitweb cgi script provides users an easy way to browse your
99487cf2
SS
2066project's revisions, file contents and logs without having to install
2067Git. Features like RSS/Atom feeds and blame/annotation details may
2068optionally be enabled.
2069
2070The linkgit:git-instaweb[1] command provides a simple way to start
2071browsing the repository using gitweb. The default server when using
2072instaweb is lighttpd.
2073
2074See the file gitweb/INSTALL in the Git source tree and
d285ab0a 2075linkgit:gitweb[1] for instructions on details setting up a permanent
99487cf2 2076installation with a CGI or Perl capable server.
d19fbc3c 2077
9cfde9ee 2078[[how-to-get-a-git-repository-with-minimal-history]]
fd5b820d 2079=== How to get a Git repository with minimal history
9cfde9ee
SS
2080
2081A <<def_shallow_clone,shallow clone>>, with its truncated
2082history, is useful when one is interested only in recent history
2083of a project and getting full history from the upstream is
2084expensive.
2085
2086A <<def_shallow_clone,shallow clone>> is created by specifying
2087the linkgit:git-clone[1] `--depth` switch. The depth can later be
2088changed with the linkgit:git-fetch[1] `--depth` switch, or full
2089history restored with `--unshallow`.
2090
2091Merging inside a <<def_shallow_clone,shallow clone>> will work as long
2092as a merge base is in the recent history.
2093Otherwise, it will be like merging unrelated histories and may
2094have to result in huge conflicts. This limitation may make such
2095a repository unsuitable to be used in merge based workflows.
d19fbc3c 2096
e34caace 2097[[sharing-development-examples]]
fd5b820d 2098=== Examples
d19fbc3c 2099
9e2163ea 2100[[maintaining-topic-branches]]
fd5b820d 2101==== Maintaining topic branches for a Linux subsystem maintainer
9e2163ea 2102
2de9b711 2103This describes how Tony Luck uses Git in his role as maintainer of the
9e2163ea
BF
2104IA64 architecture for the Linux kernel.
2105
2106He uses two public branches:
2107
2108 - A "test" tree into which patches are initially placed so that they
2109 can get some exposure when integrated with other ongoing development.
2110 This tree is available to Andrew for pulling into -mm whenever he
2111 wants.
2112
2113 - A "release" tree into which tested patches are moved for final sanity
2114 checking, and as a vehicle to send them upstream to Linus (by sending
2115 him a "please pull" request.)
2116
2117He also uses a set of temporary branches ("topic branches"), each
2118containing a logical grouping of patches.
2119
2120To set this up, first create your work tree by cloning Linus's public
2121tree:
2122
2123-------------------------------------------------
283efb01 2124$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work
9e2163ea
BF
2125$ cd work
2126-------------------------------------------------
2127
29b9a66f 2128Linus's tree will be stored in the remote-tracking branch named origin/master,
5162e697
DM
2129and can be updated using linkgit:git-fetch[1]; you can track other
2130public trees using linkgit:git-remote[1] to set up a "remote" and
7560f547 2131linkgit:git-fetch[1] to keep them up to date; see
6e30fb0c 2132<<repositories-and-branches>>.
9e2163ea
BF
2133
2134Now create the branches in which you are going to work; these start out
2135at the current tip of origin/master branch, and should be set up (using
1249d8ad 2136the `--track` option to linkgit:git-branch[1]) to merge changes in from
9e2163ea
BF
2137Linus by default.
2138
2139-------------------------------------------------
2140$ git branch --track test origin/master
2141$ git branch --track release origin/master
2142-------------------------------------------------
2143
5162e697 2144These can be easily kept up to date using linkgit:git-pull[1].
9e2163ea
BF
2145
2146-------------------------------------------------
328c6cb8
NTND
2147$ git switch test && git pull
2148$ git switch release && git pull
9e2163ea
BF
2149-------------------------------------------------
2150
2151Important note! If you have any local changes in these branches, then
2152this merge will create a commit object in the history (with no local
2de9b711 2153changes Git will simply do a "fast-forward" merge). Many people dislike
9e2163ea 2154the "noise" that this creates in the Linux history, so you should avoid
1249d8ad 2155doing this capriciously in the `release` branch, as these noisy commits
9e2163ea
BF
2156will become part of the permanent history when you ask Linus to pull
2157from the release branch.
2158
5162e697 2159A few configuration variables (see linkgit:git-config[1]) can
9e2163ea
BF
2160make it easy to push both branches to your public tree. (See
2161<<setting-up-a-public-repository>>.)
2162
2163-------------------------------------------------
2164$ cat >> .git/config <<EOF
2165[remote "mytree"]
283efb01 2166 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git
9e2163ea
BF
2167 push = release
2168 push = test
2169EOF
2170-------------------------------------------------
2171
2172Then you can push both the test and release trees using
5162e697 2173linkgit:git-push[1]:
9e2163ea
BF
2174
2175-------------------------------------------------
2176$ git push mytree
2177-------------------------------------------------
2178
2179or push just one of the test and release branches using:
2180
2181-------------------------------------------------
2182$ git push mytree test
2183-------------------------------------------------
2184
2185or
2186
2187-------------------------------------------------
2188$ git push mytree release
2189-------------------------------------------------
2190
2191Now to apply some patches from the community. Think of a short
2192snappy name for a branch to hold this patch (or related group of
352953a5
TL
2193patches), and create a new branch from a recent stable tag of
2194Linus's branch. Picking a stable base for your branch will:
21951) help you: by avoiding inclusion of unrelated and perhaps lightly
2196tested changes
1249d8ad 21972) help future bug hunters that use `git bisect` to find problems
9e2163ea
BF
2198
2199-------------------------------------------------
328c6cb8 2200$ git switch -c speed-up-spinlocks v2.6.35
9e2163ea
BF
2201-------------------------------------------------
2202
2203Now you apply the patch(es), run some tests, and commit the change(s). If
2204the patch is a multi-part series, then you should apply each as a separate
2205commit to this branch.
2206
2207-------------------------------------------------
2208$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
2209-------------------------------------------------
2210
a7bdee11 2211When you are happy with the state of this change, you can merge it into the
9e2163ea
BF
2212"test" branch in preparation to make it public:
2213
2214-------------------------------------------------
328c6cb8 2215$ git switch test && git merge speed-up-spinlocks
9e2163ea
BF
2216-------------------------------------------------
2217
2218It is unlikely that you would have any conflicts here ... but you might if you
2219spent a while on this step and had also pulled new versions from upstream.
2220
3c735e07 2221Sometime later when enough time has passed and testing done, you can pull the
1249d8ad 2222same branch into the `release` tree ready to go upstream. This is where you
9e2163ea 2223see the value of keeping each patch (or patch series) in its own branch. It
1249d8ad 2224means that the patches can be moved into the `release` tree in any order.
9e2163ea
BF
2225
2226-------------------------------------------------
328c6cb8 2227$ git switch release && git merge speed-up-spinlocks
9e2163ea
BF
2228-------------------------------------------------
2229
2230After a while, you will have a number of branches, and despite the
2231well chosen names you picked for each of them, you may forget what
2232they are for, or what status they are in. To get a reminder of what
2233changes are in a specific branch, use:
2234
2235-------------------------------------------------
467c0197 2236$ git log linux..branchname | git shortlog
9e2163ea
BF
2237-------------------------------------------------
2238
06ada152 2239To see whether it has already been merged into the test or release branches,
9e2163ea
BF
2240use:
2241
2242-------------------------------------------------
2243$ git log test..branchname
2244-------------------------------------------------
2245
2246or
2247
2248-------------------------------------------------
2249$ git log release..branchname
2250-------------------------------------------------
2251
06ada152 2252(If this branch has not yet been merged, you will see some log entries.
9e2163ea
BF
2253If it has been merged, then there will be no output.)
2254
2255Once a patch completes the great cycle (moving from test to release,
2256then pulled by Linus, and finally coming back into your local
1249d8ad 2257`origin/master` branch), the branch for this change is no longer needed.
9e2163ea
BF
2258You detect this when the output from:
2259
2260-------------------------------------------------
2261$ git log origin..branchname
2262-------------------------------------------------
2263
2264is empty. At this point the branch can be deleted:
2265
2266-------------------------------------------------
2267$ git branch -d branchname
2268-------------------------------------------------
2269
2270Some changes are so trivial that it is not necessary to create a separate
2271branch and then merge into each of the test and release branches. For
1249d8ad
TK
2272these changes, just apply directly to the `release` branch, and then
2273merge that into the `test` branch.
9e2163ea 2274
ae6ef554
TK
2275After pushing your work to `mytree`, you can use
2276linkgit:git-request-pull[1] to prepare a "please pull" request message
2277to send to Linus:
9e2163ea
BF
2278
2279-------------------------------------------------
ae6ef554
TK
2280$ git push mytree
2281$ git request-pull origin mytree release
9e2163ea
BF
2282-------------------------------------------------
2283
2284Here are some of the scripts that simplify all this even further.
2285
2286-------------------------------------------------
2287==== update script ====
48a8c26c 2288# Update a branch in my Git tree. If the branch to be updated
9e2163ea
BF
2289# is origin, then pull from kernel.org. Otherwise merge
2290# origin/master branch into test|release branch
2291
2292case "$1" in
2293test|release)
2294 git checkout $1 && git pull . origin
2295 ;;
2296origin)
fc74ecc1 2297 before=$(git rev-parse refs/remotes/origin/master)
9e2163ea 2298 git fetch origin
fc74ecc1 2299 after=$(git rev-parse refs/remotes/origin/master)
9e2163ea
BF
2300 if [ $before != $after ]
2301 then
2302 git log $before..$after | git shortlog
2303 fi
2304 ;;
2305*)
1a2ba8b9 2306 echo "usage: $0 origin|test|release" 1>&2
9e2163ea
BF
2307 exit 1
2308 ;;
2309esac
2310-------------------------------------------------
2311
2312-------------------------------------------------
2313==== merge script ====
2314# Merge a branch into either the test or release branch
2315
2316pname=$0
2317
2318usage()
2319{
1a2ba8b9 2320 echo "usage: $pname branch test|release" 1>&2
9e2163ea
BF
2321 exit 1
2322}
2323
fc74ecc1 2324git show-ref -q --verify -- refs/heads/"$1" || {
9e2163ea
BF
2325 echo "Can't see branch <$1>" 1>&2
2326 usage
fc74ecc1 2327}
9e2163ea
BF
2328
2329case "$2" in
2330test|release)
2331 if [ $(git log $2..$1 | wc -c) -eq 0 ]
2332 then
2333 echo $1 already merged into $2 1>&2
2334 exit 1
2335 fi
2336 git checkout $2 && git pull . $1
2337 ;;
2338*)
2339 usage
2340 ;;
2341esac
2342-------------------------------------------------
2343
2344-------------------------------------------------
2345==== status script ====
48a8c26c 2346# report on status of my ia64 Git tree
9e2163ea
BF
2347
2348gb=$(tput setab 2)
2349rb=$(tput setab 1)
2350restore=$(tput setab 9)
2351
2352if [ `git rev-list test..release | wc -c` -gt 0 ]
2353then
2354 echo $rb Warning: commits in release that are not in test $restore
2355 git log test..release
2356fi
2357
fc74ecc1 2358for branch in `git show-ref --heads | sed 's|^.*/||'`
9e2163ea
BF
2359do
2360 if [ $branch = test -o $branch = release ]
2361 then
2362 continue
2363 fi
2364
2365 echo -n $gb ======= $branch ====== $restore " "
2366 status=
2367 for ref in test release origin/master
2368 do
2369 if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
2370 then
2371 status=$status${ref:0:1}
2372 fi
2373 done
2374 case $status in
2375 trl)
2376 echo $rb Need to pull into test $restore
2377 ;;
2378 rl)
2379 echo "In test"
2380 ;;
2381 l)
2382 echo "Waiting for linus"
2383 ;;
2384 "")
2385 echo $rb All done $restore
2386 ;;
2387 *)
2388 echo $rb "<$status>" $restore
2389 ;;
2390 esac
2391 git log origin/master..$branch | git shortlog
2392done
2393-------------------------------------------------
d19fbc3c 2394
d19fbc3c 2395
d19fbc3c 2396[[cleaning-up-history]]
fd5b820d 2397== Rewriting history and maintaining patch series
4c63ff45
BF
2398
2399Normally commits are only added to a project, never taken away or
2400replaced. Git is designed with this assumption, and violating it will
2de9b711 2401cause Git's merge machinery (for example) to do the wrong thing.
4c63ff45
BF
2402
2403However, there is a situation in which it can be useful to violate this
2404assumption.
2405
e34caace 2406[[patch-series]]
fd5b820d 2407=== Creating the perfect patch series
4c63ff45
BF
2408
2409Suppose you are a contributor to a large project, and you want to add a
2410complicated feature, and to present it to the other developers in a way
2411that makes it easy for them to read your changes, verify that they are
2412correct, and understand why you made each change.
2413
b181d57f 2414If you present all of your changes as a single patch (or commit), they
79c96c57 2415may find that it is too much to digest all at once.
4c63ff45
BF
2416
2417If you present them with the entire history of your work, complete with
2418mistakes, corrections, and dead ends, they may be overwhelmed.
2419
2420So the ideal is usually to produce a series of patches such that:
2421
2422 1. Each patch can be applied in order.
2423
2424 2. Each patch includes a single logical change, together with a
2425 message explaining the change.
2426
2427 3. No patch introduces a regression: after applying any initial
2428 part of the series, the resulting project still compiles and
2429 works, and has no bugs that it didn't have before.
2430
2431 4. The complete series produces the same end result as your own
2432 (probably much messier!) development process did.
2433
b181d57f
BF
2434We will introduce some tools that can help you do this, explain how to
2435use them, and then explain some of the problems that can arise because
2436you are rewriting history.
4c63ff45 2437
e34caace 2438[[using-git-rebase]]
fd5b820d 2439=== Keeping a patch series up to date using git rebase
4c63ff45 2440
1249d8ad
TK
2441Suppose that you create a branch `mywork` on a remote-tracking branch
2442`origin`, and create some commits on top of it:
4c63ff45
BF
2443
2444-------------------------------------------------
328c6cb8 2445$ git switch -c mywork origin
4c63ff45
BF
2446$ vi file.txt
2447$ git commit
2448$ vi otherfile.txt
2449$ git commit
2450...
2451-------------------------------------------------
2452
2453You have performed no merges into mywork, so it is just a simple linear
1249d8ad 2454sequence of patches on top of `origin`:
4c63ff45 2455
1dc71a91 2456................................................
fa8347b8 2457 o--o--O <-- origin
4c63ff45 2458 \
fa8347b8 2459 a--b--c <-- mywork
1dc71a91 2460................................................
4c63ff45
BF
2461
2462Some more interesting work has been done in the upstream project, and
1249d8ad 2463`origin` has advanced:
4c63ff45 2464
1dc71a91 2465................................................
4c63ff45
BF
2466 o--o--O--o--o--o <-- origin
2467 \
2468 a--b--c <-- mywork
1dc71a91 2469................................................
4c63ff45 2470
1249d8ad 2471At this point, you could use `pull` to merge your changes back in;
4c63ff45
BF
2472the result would create a new merge commit, like this:
2473
1dc71a91 2474................................................
4c63ff45
BF
2475 o--o--O--o--o--o <-- origin
2476 \ \
2477 a--b--c--m <-- mywork
1dc71a91 2478................................................
a6080a0a 2479
4c63ff45
BF
2480However, if you prefer to keep the history in mywork a simple series of
2481commits without any merges, you may instead choose to use
5162e697 2482linkgit:git-rebase[1]:
4c63ff45
BF
2483
2484-------------------------------------------------
328c6cb8 2485$ git switch mywork
4c63ff45
BF
2486$ git rebase origin
2487-------------------------------------------------
2488
b181d57f 2489This will remove each of your commits from mywork, temporarily saving
1249d8ad 2490them as patches (in a directory named `.git/rebase-apply`), update mywork to
b181d57f
BF
2491point at the latest version of origin, then apply each of the saved
2492patches to the new mywork. The result will look like:
4c63ff45
BF
2493
2494
1dc71a91 2495................................................
4c63ff45
BF
2496 o--o--O--o--o--o <-- origin
2497 \
2498 a'--b'--c' <-- mywork
1dc71a91 2499................................................
4c63ff45 2500
b181d57f 2501In the process, it may discover conflicts. In that case it will stop
6127c086 2502and allow you to fix the conflicts; after fixing conflicts, use `git add`
7a7d4ef6 2503to update the index with those contents, and then, instead of
6127c086 2504running `git commit`, just run
4c63ff45
BF
2505
2506-------------------------------------------------
2507$ git rebase --continue
2508-------------------------------------------------
2509
2de9b711 2510and Git will continue applying the rest of the patches.
4c63ff45 2511
b6cbca38 2512At any point you may use the `--abort` option to abort this process and
4c63ff45
BF
2513return mywork to the state it had before you started the rebase:
2514
2515-------------------------------------------------
2516$ git rebase --abort
2517-------------------------------------------------
2518
6c26bf4d
TK
2519If you need to reorder or edit a number of commits in a branch, it may
2520be easier to use `git rebase -i`, which allows you to reorder and
2521squash commits, as well as marking them for individual editing during
2522the rebase. See <<interactive-rebase>> for details, and
2523<<reordering-patch-series>> for alternatives.
2524
7cb192ea 2525[[rewriting-one-commit]]
fd5b820d 2526=== Rewriting a single commit
365aa199 2527
7cb192ea 2528We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
365aa199
BF
2529most recent commit using
2530
2531-------------------------------------------------
2532$ git commit --amend
2533-------------------------------------------------
2534
2535which will replace the old commit by a new commit incorporating your
2536changes, giving you a chance to edit the old commit message first.
6c26bf4d
TK
2537This is useful for fixing typos in your last commit, or for adjusting
2538the patch contents of a poorly staged commit.
365aa199 2539
6c26bf4d
TK
2540If you need to amend commits from deeper in your history, you can
2541use <<interactive-rebase,interactive rebase's `edit` instruction>>.
365aa199 2542
6c26bf4d 2543[[reordering-patch-series]]
fd5b820d 2544=== Reordering or selecting from a patch series
365aa199 2545
6c26bf4d
TK
2546Sometimes you want to edit a commit deeper in your history. One
2547approach is to use `git format-patch` to create a series of patches
2548and then reset the state to before the patches:
365aa199
BF
2549
2550-------------------------------------------------
6c26bf4d
TK
2551$ git format-patch origin
2552$ git reset --hard origin
365aa199
BF
2553-------------------------------------------------
2554
6c26bf4d
TK
2555Then modify, reorder, or eliminate patches as needed before applying
2556them again with linkgit:git-am[1]:
365aa199
BF
2557
2558-------------------------------------------------
6c26bf4d 2559$ git am *.patch
365aa199
BF
2560-------------------------------------------------
2561
6c26bf4d 2562[[interactive-rebase]]
fd5b820d 2563=== Using interactive rebases
365aa199 2564
6c26bf4d
TK
2565You can also edit a patch series with an interactive rebase. This is
2566the same as <<reordering-patch-series,reordering a patch series using
2567`format-patch`>>, so use whichever interface you like best.
4c63ff45 2568
6c26bf4d
TK
2569Rebase your current HEAD on the last commit you want to retain as-is.
2570For example, if you want to reorder the last 5 commits, use:
b181d57f
BF
2571
2572-------------------------------------------------
6c26bf4d 2573$ git rebase -i HEAD~5
b181d57f
BF
2574-------------------------------------------------
2575
6c26bf4d
TK
2576This will open your editor with a list of steps to be taken to perform
2577your rebase.
4c63ff45 2578
b181d57f 2579-------------------------------------------------
6c26bf4d
TK
2580pick deadbee The oneline of this commit
2581pick fa1afe1 The oneline of the next commit
2582...
4c63ff45 2583
6c26bf4d
TK
2584# Rebase c0ffeee..deadbee onto c0ffeee
2585#
2586# Commands:
2587# p, pick = use commit
2588# r, reword = use commit, but edit the commit message
2589# e, edit = use commit, but stop for amending
2590# s, squash = use commit, but meld into previous commit
2591# f, fixup = like "squash", but discard this commit's log message
2592# x, exec = run command (the rest of the line) using shell
2593#
2594# These lines can be re-ordered; they are executed from top to bottom.
2595#
2596# If you remove a line here THAT COMMIT WILL BE LOST.
2597#
2598# However, if you remove everything, the rebase will be aborted.
2599#
2600# Note that empty commits are commented out
2601-------------------------------------------------
2602
2603As explained in the comments, you can reorder commits, squash them
2604together, edit commit messages, etc. by editing the list. Once you
2605are satisfied, save the list and close your editor, and the rebase
2606will begin.
2607
2608The rebase will stop where `pick` has been replaced with `edit` or
2609when a step in the list fails to mechanically resolve conflicts and
2610needs your help. When you are done editing and/or resolving conflicts
2611you can continue with `git rebase --continue`. If you decide that
2612things are getting too hairy, you can always bail out with `git rebase
2613--abort`. Even after the rebase is complete, you can still recover
2614the original branch by using the <<reflogs,reflog>>.
2615
2616For a more detailed discussion of the procedure and additional tips,
2617see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
4c63ff45 2618
e34caace 2619[[patch-series-tools]]
fd5b820d 2620=== Other tools
4c63ff45 2621
73a1d050 2622There are numerous other tools, such as StGit, which exist for the
79c96c57 2623purpose of maintaining a patch series. These are outside of the scope of
b181d57f 2624this manual.
4c63ff45 2625
aa971cb9 2626[[problems-With-rewriting-history]]
fd5b820d 2627=== Problems with rewriting history
4c63ff45 2628
b181d57f
BF
2629The primary problem with rewriting the history of a branch has to do
2630with merging. Suppose somebody fetches your branch and merges it into
2631their branch, with a result something like this:
2632
1dc71a91 2633................................................
b181d57f
BF
2634 o--o--O--o--o--o <-- origin
2635 \ \
2636 t--t--t--m <-- their branch:
1dc71a91 2637................................................
b181d57f
BF
2638
2639Then suppose you modify the last three commits:
2640
1dc71a91 2641................................................
b181d57f
BF
2642 o--o--o <-- new head of origin
2643 /
2644 o--o--O--o--o--o <-- old head of origin
1dc71a91 2645................................................
b181d57f
BF
2646
2647If we examined all this history together in one repository, it will
2648look like:
2649
1dc71a91 2650................................................
b181d57f
BF
2651 o--o--o <-- new head of origin
2652 /
2653 o--o--O--o--o--o <-- old head of origin
2654 \ \
2655 t--t--t--m <-- their branch:
1dc71a91 2656................................................
b181d57f
BF
2657
2658Git has no way of knowing that the new head is an updated version of
2659the old head; it treats this situation exactly the same as it would if
2660two developers had independently done the work on the old and new heads
2661in parallel. At this point, if someone attempts to merge the new head
2de9b711 2662in to their branch, Git will attempt to merge together the two (old and
b181d57f
BF
2663new) lines of development, instead of trying to replace the old by the
2664new. The results are likely to be unexpected.
2665
2666You may still choose to publish branches whose history is rewritten,
2667and it may be useful for others to be able to fetch those branches in
2668order to examine or test them, but they should not attempt to pull such
2669branches into their own work.
2670
2671For true distributed development that supports proper merging,
2672published branches should never be rewritten.
2673
3fb00282 2674[[bisect-merges]]
fd5b820d 2675=== Why bisecting merge commits can be harder than bisecting linear history
3fb00282 2676
5162e697 2677The linkgit:git-bisect[1] command correctly handles history that
3fb00282
SP
2678includes merge commits. However, when the commit that it finds is a
2679merge commit, the user may need to work harder than usual to figure out
2680why that commit introduced a problem.
2681
2682Imagine this history:
2683
2684................................................
2685 ---Z---o---X---...---o---A---C---D
2686 \ /
2687 o---o---Y---...---o---B
2688................................................
2689
2690Suppose that on the upper line of development, the meaning of one
2691of the functions that exists at Z is changed at commit X. The
2692commits from Z leading to A change both the function's
2693implementation and all calling sites that exist at Z, as well
2694as new calling sites they add, to be consistent. There is no
2695bug at A.
2696
2697Suppose that in the meantime on the lower line of development somebody
2698adds a new calling site for that function at commit Y. The
2699commits from Z leading to B all assume the old semantics of that
2700function and the callers and the callee are consistent with each
2701other. There is no bug at B, either.
2702
2703Suppose further that the two development lines merge cleanly at C,
2704so no conflict resolution is required.
2705
2706Nevertheless, the code at C is broken, because the callers added
2707on the lower line of development have not been converted to the new
2708semantics introduced on the upper line of development. So if all
2709you know is that D is bad, that Z is good, and that
5162e697 2710linkgit:git-bisect[1] identifies C as the culprit, how will you
3fb00282
SP
2711figure out that the problem is due to this change in semantics?
2712
6127c086 2713When the result of a `git bisect` is a non-merge commit, you should
3fb00282
SP
2714normally be able to discover the problem by examining just that commit.
2715Developers can make this easy by breaking their changes into small
2716self-contained commits. That won't help in the case above, however,
2717because the problem isn't obvious from examination of any single
2718commit; instead, a global view of the development is required. To
2719make matters worse, the change in semantics in the problematic
2720function may be just one small part of the changes in the upper
2721line of development.
2722
2723On the other hand, if instead of merging at C you had rebased the
2724history between Z to B on top of A, you would have gotten this
2725linear history:
2726
2727................................................................
2728 ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
2729................................................................
2730
2731Bisecting between Z and D* would hit a single culprit commit Y*,
2732and understanding why Y* was broken would probably be easier.
2733
2de9b711 2734Partly for this reason, many experienced Git users, even when
3fb00282
SP
2735working on an otherwise merge-heavy project, keep the history
2736linear by rebasing against the latest upstream version before
2737publishing.
2738
e34caace 2739[[advanced-branch-management]]
fd5b820d 2740== Advanced branch management
4c63ff45 2741
e34caace 2742[[fetching-individual-branches]]
fd5b820d 2743=== Fetching individual branches
b181d57f 2744
5162e697 2745Instead of using linkgit:git-remote[1], you can also choose just
b181d57f
BF
2746to update one branch at a time, and to store it locally under an
2747arbitrary name:
2748
2749-------------------------------------------------
2750$ git fetch origin todo:my-todo-work
2751-------------------------------------------------
2752
1249d8ad 2753The first argument, `origin`, just tells Git to fetch from the
2de9b711 2754repository you originally cloned from. The second argument tells Git
1249d8ad
TK
2755to fetch the branch named `todo` from the remote repository, and to
2756store it locally under the name `refs/heads/my-todo-work`.
b181d57f
BF
2757
2758You can also fetch branches from other repositories; so
2759
2760-------------------------------------------------
2761$ git fetch git://example.com/proj.git master:example-master
2762-------------------------------------------------
2763
1249d8ad
TK
2764will create a new branch named `example-master` and store in it the
2765branch named `master` from the repository at the given URL. If you
b181d57f 2766already have a branch named example-master, it will attempt to
59723040
BF
2767<<fast-forwards,fast-forward>> to the commit given by example.com's
2768master branch. In more detail:
b181d57f 2769
59723040 2770[[fetch-fast-forwards]]
fd5b820d 2771=== git fetch and fast-forwards
b181d57f 2772
1249d8ad 2773In the previous example, when updating an existing branch, `git fetch`
7a7d4ef6 2774checks to make sure that the most recent commit on the remote
b181d57f
BF
2775branch is a descendant of the most recent commit on your copy of the
2776branch before updating your copy of the branch to point at the new
a75d7b54 2777commit. Git calls this process a <<fast-forwards,fast-forward>>.
b181d57f 2778
a75d7b54 2779A fast-forward looks something like this:
b181d57f 2780
1dc71a91 2781................................................
b181d57f
BF
2782 o--o--o--o <-- old head of the branch
2783 \
2784 o--o--o <-- new head of the branch
1dc71a91 2785................................................
b181d57f
BF
2786
2787
2788In some cases it is possible that the new head will *not* actually be
2789a descendant of the old head. For example, the developer may have
2790realized she made a serious mistake, and decided to backtrack,
2791resulting in a situation like:
2792
1dc71a91 2793................................................
b181d57f
BF
2794 o--o--o--o--a--b <-- old head of the branch
2795 \
2796 o--o--o <-- new head of the branch
1dc71a91 2797................................................
b181d57f 2798
1249d8ad 2799In this case, `git fetch` will fail, and print out a warning.
b181d57f 2800
2de9b711 2801In that case, you can still force Git to update to the new head, as
b181d57f 2802described in the following section. However, note that in the
1249d8ad 2803situation above this may mean losing the commits labeled `a` and `b`,
b181d57f
BF
2804unless you've already created a reference of your own pointing to
2805them.
2806
e34caace 2807[[forcing-fetch]]
fd5b820d 2808=== Forcing git fetch to do non-fast-forward updates
b181d57f
BF
2809
2810If git fetch fails because the new head of a branch is not a
2811descendant of the old head, you may force the update with:
2812
2813-------------------------------------------------
2814$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
2815-------------------------------------------------
2816
1249d8ad 2817Note the addition of the `+` sign. Alternatively, you can use the `-f`
c64415e2
BF
2818flag to force updates of all the fetched branches, as in:
2819
2820-------------------------------------------------
2821$ git fetch -f origin
2822-------------------------------------------------
2823
2824Be aware that commits that the old version of example/master pointed at
2825may be lost, as we saw in the previous section.
b181d57f 2826
e34caace 2827[[remote-branch-configuration]]
fd5b820d 2828=== Configuring remote-tracking branches
b181d57f 2829
1249d8ad 2830We saw above that `origin` is just a shortcut to refer to the
79c96c57 2831repository that you originally cloned from. This information is
2de9b711 2832stored in Git configuration variables, which you can see using
5162e697 2833linkgit:git-config[1]:
b181d57f
BF
2834
2835-------------------------------------------------
9d13bda3 2836$ git config -l
b181d57f
BF
2837core.repositoryformatversion=0
2838core.filemode=true
2839core.logallrefupdates=true
2840remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
2841remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
2842branch.master.remote=origin
2843branch.master.merge=refs/heads/master
2844-------------------------------------------------
2845
2846If there are other repositories that you also use frequently, you can
2847create similar configuration options to save typing; for example,
b181d57f
BF
2848
2849-------------------------------------------------
47adb8ac 2850$ git remote add example git://example.com/proj.git
b181d57f
BF
2851-------------------------------------------------
2852
47adb8ac 2853adds the following to `.git/config`:
b181d57f
BF
2854
2855-------------------------------------------------
47adb8ac
TK
2856[remote "example"]
2857 url = git://example.com/proj.git
2858 fetch = +refs/heads/*:refs/remotes/example/*
b181d57f
BF
2859-------------------------------------------------
2860
47adb8ac
TK
2861Also note that the above configuration can be performed by directly
2862editing the file `.git/config` instead of using linkgit:git-remote[1].
b181d57f 2863
47adb8ac
TK
2864After configuring the remote, the following three commands will do the
2865same thing:
b181d57f
BF
2866
2867-------------------------------------------------
47adb8ac
TK
2868$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
2869$ git fetch example +refs/heads/*:refs/remotes/example/*
b181d57f
BF
2870$ git fetch example
2871-------------------------------------------------
2872
5162e697 2873See linkgit:git-config[1] for more details on the configuration
47adb8ac
TK
2874options mentioned above and linkgit:git-fetch[1] for more details on
2875the refspec syntax.
d19fbc3c 2876
d19fbc3c 2877
036f8199 2878[[git-concepts]]
fd5b820d 2879== Git concepts
d19fbc3c 2880
036f8199
BF
2881Git is built on a small number of simple but powerful ideas. While it
2882is possible to get things done without understanding them, you will find
2de9b711 2883Git much more intuitive if you do.
036f8199
BF
2884
2885We start with the most important, the <<def_object_database,object
2886database>> and the <<def_index,index>>.
b181d57f 2887
e34caace 2888[[the-object-database]]
fd5b820d 2889=== The Object Database
b181d57f 2890
1bbf1c79
BF
2891
2892We already saw in <<understanding-commits>> that all commits are stored
2893under a 40-digit "object name". In fact, all the information needed to
2894represent the history of a project is stored in objects with such names.
a6e5ef7d
FC
2895In each case the name is calculated by taking the SHA-1 hash of the
2896contents of the object. The SHA-1 hash is a cryptographic hash function.
1bbf1c79
BF
2897What that means to us is that it is impossible to find two different
2898objects with the same name. This has a number of advantages; among
2899others:
2900
2901- Git can quickly determine whether two objects are identical or not,
2902 just by comparing names.
06ada152 2903- Since object names are computed the same way in every repository, the
1bbf1c79
BF
2904 same content stored in two repositories will always be stored under
2905 the same name.
2906- Git can detect errors when it reads an object, by checking that the
a6e5ef7d 2907 object's name is still the SHA-1 hash of its contents.
1bbf1c79
BF
2908
2909(See <<object-details>> for the details of the object formatting and
a6e5ef7d 2910SHA-1 calculation.)
1bbf1c79
BF
2911
2912There are four different types of objects: "blob", "tree", "commit", and
2913"tag".
2914
2915- A <<def_blob_object,"blob" object>> is used to store file data.
843c81dc 2916- A <<def_tree_object,"tree" object>> ties one or more
1bbf1c79
BF
2917 "blob" objects into a directory structure. In addition, a tree object
2918 can refer to other tree objects, thus creating a directory hierarchy.
2919- A <<def_commit_object,"commit" object>> ties such directory hierarchies
2ef8ac1b 2920 together into a <<def_DAG,directed acyclic graph>> of revisions--each
1bbf1c79
BF
2921 commit contains the object name of exactly one tree designating the
2922 directory hierarchy at the time of the commit. In addition, a commit
2923 refers to "parent" commit objects that describe the history of how we
2924 arrived at that directory hierarchy.
2925- A <<def_tag_object,"tag" object>> symbolically identifies and can be
2926 used to sign other objects. It contains the object name and type of
2927 another object, a symbolic name (of course!) and, optionally, a
2928 signature.
b181d57f 2929
b181d57f
BF
2930The object types in some more detail:
2931
513d419c 2932[[commit-object]]
fd5b820d 2933==== Commit Object
b181d57f 2934
1bbf1c79 2935The "commit" object links a physical state of a tree with a description
1249d8ad 2936of how we got there and why. Use the `--pretty=raw` option to
5162e697 2937linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
1bbf1c79
BF
2938commit:
2939
2940------------------------------------------------
2941$ git show -s --pretty=raw 2be7fcb476
2942commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
2943tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
2944parent 257a84d9d02e90447b149af58b271c19405edb6a
2945author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
2946committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
2947
2948 Fix misspelling of 'suppress' in docs
2949
2950 Signed-off-by: Junio C Hamano <gitster@pobox.com>
2951------------------------------------------------
2952
2953As you can see, a commit is defined by:
2954
a6e5ef7d 2955- a tree: The SHA-1 name of a tree object (as defined below), representing
1bbf1c79 2956 the contents of a directory at a certain point in time.
edfbbf7e 2957- parent(s): The SHA-1 name(s) of some number of commits which represent the
9e5d87d4 2958 immediately previous step(s) in the history of the project. The
1bbf1c79
BF
2959 example above has one parent; merge commits may have more than
2960 one. A commit with no parents is called a "root" commit, and
2961 represents the initial revision of a project. Each project must have
2962 at least one root. A project can also have multiple roots, though
2963 that isn't common (or necessarily a good idea).
2964- an author: The name of the person responsible for this change, together
2965 with its date.
2966- a committer: The name of the person who actually created the commit,
2967 with the date it was done. This may be different from the author, for
2968 example, if the author was someone who wrote a patch and emailed it
2969 to the person who used it to create the commit.
2970- a comment describing this commit.
2971
2972Note that a commit does not itself contain any information about what
2973actually changed; all changes are calculated by comparing the contents
2974of the tree referred to by this commit with the trees associated with
2de9b711 2975its parents. In particular, Git does not attempt to record file renames
1bbf1c79
BF
2976explicitly, though it can identify cases where the existence of the same
2977file data at changing paths suggests a rename. (See, for example, the
1249d8ad 2978`-M` option to linkgit:git-diff[1]).
1bbf1c79 2979
5162e697 2980A commit is usually created by linkgit:git-commit[1], which creates a
1bbf1c79
BF
2981commit whose parent is normally the current HEAD, and whose tree is
2982taken from the content currently stored in the index.
b181d57f 2983
e34caace 2984[[tree-object]]
fd5b820d 2985==== Tree Object
b181d57f 2986
5162e697
DM
2987The ever-versatile linkgit:git-show[1] command can also be used to
2988examine tree objects, but linkgit:git-ls-tree[1] will give you more
1bbf1c79
BF
2989details:
2990
2991------------------------------------------------
2992$ git ls-tree fb3a8bdd0ce
2993100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
2994100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
2995100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
2996040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
2997100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
2998100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
2999100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
3000100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
3001...
3002------------------------------------------------
3003
3004As you can see, a tree object contains a list of entries, each with a
a6e5ef7d 3005mode, object type, SHA-1 name, and name, sorted by name. It represents
1bbf1c79
BF
3006the contents of a single directory tree.
3007
3008The object type may be a blob, representing the contents of a file, or
3009another tree, representing the contents of a subdirectory. Since trees
a6e5ef7d
FC
3010and blobs, like all other objects, are named by the SHA-1 hash of their
3011contents, two trees have the same SHA-1 name if and only if their
1bbf1c79 3012contents (including, recursively, the contents of all subdirectories)
2de9b711 3013are identical. This allows Git to quickly determine the differences
1bbf1c79
BF
3014between two related tree objects, since it can ignore any entries with
3015identical object names.
3016
3017(Note: in the presence of submodules, trees may also have commits as
6dd14366 3018entries. See <<submodules>> for documentation.)
1bbf1c79 3019
2de9b711 3020Note that the files all have mode 644 or 755: Git actually only pays
1bbf1c79 3021attention to the executable bit.
b181d57f 3022
513d419c 3023[[blob-object]]
fd5b820d 3024==== Blob Object
b181d57f 3025
5162e697 3026You can use linkgit:git-show[1] to examine the contents of a blob; take,
1249d8ad 3027for example, the blob in the entry for `COPYING` from the tree above:
b181d57f 3028
1bbf1c79
BF
3029------------------------------------------------
3030$ git show 6ff87c4664
3031
3032 Note that the only valid version of the GPL as far as this project
3033 is concerned is _this_ particular version of the license (ie v2, not
3034 v2.2 or v3.x or whatever), unless explicitly otherwise stated.
3035...
3036------------------------------------------------
b181d57f 3037
1bbf1c79
BF
3038A "blob" object is nothing but a binary blob of data. It doesn't refer
3039to anything else or have attributes of any kind.
3040
3041Since the blob is entirely defined by its data, if two files in a
3042directory tree (or in multiple different versions of the repository)
3043have the same contents, they will share the same blob object. The object
3044is totally independent of its location in the directory tree, and
3045renaming a file does not change the object that file is associated with.
3046
3047Note that any tree or blob object can be examined using
5162e697 3048linkgit:git-show[1] with the <revision>:<path> syntax. This can
1bbf1c79
BF
3049sometimes be useful for browsing the contents of a tree that is not
3050currently checked out.
b181d57f 3051
e34caace 3052[[trust]]
fd5b820d 3053==== Trust
b181d57f 3054
a6e5ef7d 3055If you receive the SHA-1 name of a blob from one source, and its contents
1bbf1c79 3056from another (possibly untrusted) source, you can still trust that those
a6e5ef7d
FC
3057contents are correct as long as the SHA-1 name agrees. This is because
3058the SHA-1 is designed so that it is infeasible to find different contents
1bbf1c79 3059that produce the same hash.
b181d57f 3060
a6e5ef7d 3061Similarly, you need only trust the SHA-1 name of a top-level tree object
1bbf1c79 3062to trust the contents of the entire directory that it refers to, and if
a6e5ef7d 3063you receive the SHA-1 name of a commit from a trusted source, then you
1bbf1c79
BF
3064can easily verify the entire history of commits reachable through
3065parents of that commit, and all of those contents of the trees referred
3066to by those commits.
b181d57f
BF
3067
3068So to introduce some real trust in the system, the only thing you need
3069to do is to digitally sign just 'one' special note, which includes the
3070name of a top-level commit. Your digital signature shows others
3071that you trust that commit, and the immutability of the history of
3072commits tells others that they can trust the whole history.
3073
3074In other words, you can easily validate a whole archive by just
a6e5ef7d 3075sending out a single email that tells the people the name (SHA-1 hash)
b181d57f
BF