freshlybakedca.ke
Git fork
1= Git User Manual
2
3[preface]
4== Introduction
5
6Git is a fast distributed revision control system.
7
8This manual is designed to be readable by someone with basic UNIX
9command-line skills, but no previous knowledge of Git.
10
11<<repositories-and-branches>> and <<exploring-git-history>> explain how
12to fetch and study a project using git--read these chapters to learn how
13to build and test a particular version of a software project, search for
14regressions, and so on.
15
16People needing to do actual development will also want to read
17<<Developing-With-git>> and <<sharing-development>>.
18
19Further chapters cover more specialized topics.
20
21Comprehensive reference documentation is available through the man
22pages, or linkgit:git-help[1] command. For example, for the command
23`git clone <repo>`, you can either use:
24
25------------------------------------------------
26$ man git-clone
27------------------------------------------------
28
29or:
30
31------------------------------------------------
32$ git help clone
33------------------------------------------------
34
35With the latter, you can use the manual viewer of your choice; see
36linkgit:git-help[1] for more information.
37
38See also <<git-quick-start>> for a brief overview of Git commands,
39without any explanation.
40
41Finally, see <<todo>> for ways that you can help make this manual more
42complete.
43
44
45[[repositories-and-branches]]
46== Repositories and Branches
47
48[[how-to-get-a-git-repository]]
49=== How to get a Git repository
50
51It will be useful to have a Git repository to experiment with as you
52read this manual.
53
54The best way to get one is by using the linkgit:git-clone[1] command to
55download a copy of an existing repository. If you don't already have a
56project in mind, here are some interesting examples:
57
58------------------------------------------------
59 # Git itself (approx. 40MB download):
60$ git clone git://git.kernel.org/pub/scm/git/git.git
61 # the Linux kernel (approx. 640MB download):
62$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
63------------------------------------------------
64
65The initial clone may be time-consuming for a large project, but you
66will only need to clone once.
67
68The clone command creates a new directory named after the project
69(`git` or `linux` in the examples above). After you cd into this
70directory, you will see that it contains a copy of the project files,
71called the <<def_working_tree,working tree>>, together with a special
72top-level directory named `.git`, which contains all the information
73about the history of the project.
74
75[[how-to-check-out]]
76=== How to check out a different version of a project
77
78Git is best thought of as a tool for storing the history of a collection
79of files. It stores the history as a compressed collection of
80interrelated snapshots of the project's contents. In Git each such
81version is called a <<def_commit,commit>>.
82
83Those snapshots aren't necessarily all arranged in a single line from
84oldest to newest; instead, work may simultaneously proceed along
85parallel lines of development, called <<def_branch,branches>>, which may
86merge and diverge.
87
88A single Git repository can track development on multiple branches. It
89does this by keeping a list of <<def_head,heads>> which reference the
90latest commit on each branch; the linkgit:git-branch[1] command shows
91you the list of branch heads:
92
93------------------------------------------------
94$ git branch
95* master
96------------------------------------------------
97
98A freshly cloned repository contains a single branch head, by default
99named "master", with the working directory initialized to the state of
100the project referred to by that branch head.
101
102Most projects also use <<def_tag,tags>>. Tags, like heads, are
103references into the project's history, and can be listed using the
104linkgit:git-tag[1] command:
105
106------------------------------------------------
107$ git tag -l
108v2.6.11
109v2.6.11-tree
110v2.6.12
111v2.6.12-rc2
112v2.6.12-rc3
113v2.6.12-rc4
114v2.6.12-rc5
115v2.6.12-rc6
116v2.6.13
117...
118------------------------------------------------
119
120Tags are expected to always point at the same version of a project,
121while heads are expected to advance as development progresses.
122
123Create a new branch head pointing to one of these versions and check it
124out using linkgit:git-switch[1]:
125
126------------------------------------------------
127$ git switch -c new v2.6.13
128------------------------------------------------
129
130The working directory then reflects the contents that the project had
131when it was tagged v2.6.13, and linkgit:git-branch[1] shows two
132branches, with an asterisk marking the currently checked-out branch:
133
134------------------------------------------------
135$ git branch
136 master
137* new
138------------------------------------------------
139
140If you decide that you'd rather see version 2.6.17, you can modify
141the current branch to point at v2.6.17 instead, with
142
143------------------------------------------------
144$ git reset --hard v2.6.17
145------------------------------------------------
146
147Note that if the current branch head was your only reference to a
148particular point in history, then resetting that branch may leave you
149with no way to find the history it used to point to; so use this command
150carefully.
151
152[[understanding-commits]]
153=== Understanding History: Commits
154
155Every change in the history of a project is represented by a commit.
156The linkgit:git-show[1] command shows the most recent commit on the
157current branch:
158
159------------------------------------------------
160$ git show
161commit 17cf781661e6d38f737f15f53ab552f1e95960d7
162Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>
163Date: Tue Apr 19 14:11:06 2005 -0700
164
165 Remove duplicate getenv(DB_ENVIRONMENT) call
166
167 Noted by Tony Luck.
168
169diff --git a/init-db.c b/init-db.c
170index 65898fa..b002dc6 100644
171--- a/init-db.c
172+++ b/init-db.c
173@@ -7,7 +7,7 @@
174
175 int main(int argc, char **argv)
176 {
177- char *sha1_dir = getenv(DB_ENVIRONMENT), *path;
178+ char *sha1_dir, *path;
179 int len, i;
180
181 if (mkdir(".git", 0755) < 0) {
182------------------------------------------------
183
184As you can see, a commit shows who made the latest change, what they
185did, and why.
186
187Every commit has a 40-hexdigit id, sometimes called the "object name" or the
188"SHA-1 id", shown on the first line of the `git show` output. You can usually
189refer to a commit by a shorter name, such as a tag or a branch name, but this
190longer name can also be useful. Most importantly, it is a globally unique
191name for this commit: so if you tell somebody else the object name (for
192example in email), then you are guaranteed that name will refer to the same
193commit in their repository that it does in yours (assuming their repository
194has that commit at all). Since the object name is computed as a hash over the
195contents of the commit, you are guaranteed that the commit can never change
196without its name also changing.
197
198In fact, in <<git-concepts>> we shall see that everything stored in Git
199history, including file data and directory contents, is stored in an object
200with a name that is a hash of its contents.
201
202[[understanding-reachability]]
203==== Understanding history: commits, parents, and reachability
204
205Every commit (except the very first commit in a project) also has a
206parent commit which shows what happened before this commit.
207Following the chain of parents will eventually take you back to the
208beginning of the project.
209
210However, the commits do not form a simple list; Git allows lines of
211development to diverge and then reconverge, and the point where two
212lines of development reconverge is called a "merge". The commit
213representing a merge can therefore have more than one parent, with
214each parent representing the most recent commit on one of the lines
215of development leading to that point.
216
217The best way to see how this works is using the linkgit:gitk[1]
218command; running gitk now on a Git repository and looking for merge
219commits will help understand how Git organizes history.
220
221In the following, we say that commit X is "reachable" from commit Y
222if commit X is an ancestor of commit Y. Equivalently, you could say
223that Y is a descendant of X, or that there is a chain of parents
224leading from commit Y to commit X.
225
226[[history-diagrams]]
227==== Understanding history: History diagrams
228
229We will sometimes represent Git history using diagrams like the one
230below. Commits are shown as "o", and the links between them with
231lines drawn with - / and \. Time goes left to right:
232
233
234................................................
235 o--o--o <-- Branch A
236 /
237 o--o--o <-- master
238 \
239 o--o--o <-- Branch B
240................................................
241
242If we need to talk about a particular commit, the character "o" may
243be replaced with another letter or number.
244
245[[what-is-a-branch]]
246==== Understanding history: What is a branch?
247
248When we need to be precise, we will use the word "branch" to mean a line
249of development, and "branch head" (or just "head") to mean a reference
250to the most recent commit on a branch. In the example above, the branch
251head named "A" is a pointer to one particular commit, but we refer to
252the line of three commits leading up to that point as all being part of
253"branch A".
254
255However, when no confusion will result, we often just use the term
256"branch" both for branches and for branch heads.
257
258[[manipulating-branches]]
259=== Manipulating branches
260
261Creating, deleting, and modifying branches is quick and easy; here's
262a summary of the commands:
263
264`git branch`::
265 list all branches.
266`git branch <branch>`::
267 create a new branch named `<branch>`, referencing the same
268 point in history as the current branch.
269`git branch <branch> <start-point>`::
270 create a new branch named `<branch>`, referencing
271 `<start-point>`, which may be specified any way you like,
272 including using a branch name or a tag name.
273`git branch -d <branch>`::
274 delete the branch `<branch>`; if the branch is not fully
275 merged in its upstream branch or contained in the current branch,
276 this command will fail with a warning.
277`git branch -D <branch>`::
278 delete the branch `<branch>` irrespective of its merged status.
279`git switch <branch>`::
280 make the current branch `<branch>`, updating the working
281 directory to reflect the version referenced by `<branch>`.
282`git switch -c <new> <start-point>`::
283 create a new branch `<new>` referencing `<start-point>`, and
284 check it out.
285
286The special symbol "HEAD" can always be used to refer to the current
287branch. In fact, Git uses a file named `HEAD` in the `.git` directory
288to remember which branch is current:
289
290------------------------------------------------
291$ cat .git/HEAD
292ref: refs/heads/master
293------------------------------------------------
294
295[[detached-head]]
296=== Examining an old version without creating a new branch
297
298The `git switch` command normally expects a branch head, but will also
299accept an arbitrary commit when invoked with --detach; for example,
300you can check out the commit referenced by a tag:
301
302------------------------------------------------
303$ git switch --detach v2.6.17
304Note: checking out 'v2.6.17'.
305
306You are in 'detached HEAD' state. You can look around, make experimental
307changes and commit them, and you can discard any commits you make in this
308state without impacting any branches by performing another switch.
309
310If you want to create a new branch to retain commits you create, you may
311do so (now or later) by using -c with the switch command again. Example:
312
313 git switch -c new_branch_name
314
315HEAD is now at 427abfa Linux v2.6.17
316------------------------------------------------
317
318The HEAD then refers to the SHA-1 of the commit instead of to a branch,
319and git branch shows that you are no longer on a branch:
320
321------------------------------------------------
322$ cat .git/HEAD
323427abfa28afedffadfca9dd8b067eb6d36bac53f
324$ git branch
325* (detached from v2.6.17)
326 master
327------------------------------------------------
328
329In this case we say that the HEAD is "detached".
330
331This is an easy way to check out a particular version without having to
332make up a name for the new branch. You can still create a new branch
333(or tag) for this version later if you decide to.
334
335[[examining-remote-branches]]
336=== Examining branches from a remote repository
337
338The "master" branch that was created at the time you cloned is a copy
339of the HEAD in the repository that you cloned from. That repository
340may also have had other branches, though, and your local repository
341keeps branches which track each of those remote branches, called
342remote-tracking branches, which you
343can view using the `-r` option to linkgit:git-branch[1]:
344
345------------------------------------------------
346$ git branch -r
347 origin/HEAD
348 origin/html
349 origin/maint
350 origin/man
351 origin/master
352 origin/next
353 origin/seen
354 origin/todo
355------------------------------------------------
356
357In this example, "origin" is called a remote repository, or "remote"
358for short. The branches of this repository are called "remote
359branches" from our point of view. The remote-tracking branches listed
360above were created based on the remote branches at clone time and will
361be updated by `git fetch` (hence `git pull`) and `git push`. See
362<<Updating-a-repository-With-git-fetch>> for details.
363
364You might want to build on one of these remote-tracking branches
365on a branch of your own, just as you would for a tag:
366
367------------------------------------------------
368$ git switch -c my-todo-copy origin/todo
369------------------------------------------------
370
371You can also check out `origin/todo` directly to examine it or
372write a one-off patch. See <<detached-head,detached head>>.
373
374Note that the name "origin" is just the name that Git uses by default
375to refer to the repository that you cloned from.
376
377[[how-git-stores-references]]
378=== Naming branches, tags, and other references
379
380Branches, remote-tracking branches, and tags are all references to
381commits. All references are named with a slash-separated path name
382starting with `refs`; the names we've been using so far are actually
383shorthand:
384
385 - The branch `test` is short for `refs/heads/test`.
386 - The tag `v2.6.18` is short for `refs/tags/v2.6.18`.
387 - `origin/master` is short for `refs/remotes/origin/master`.
388
389The full name is occasionally useful if, for example, there ever
390exists a tag and a branch with the same name.
391
392(Newly created refs are actually stored in the `.git/refs` directory,
393under the path given by their name. However, for efficiency reasons
394they may also be packed together in a single file; see
395linkgit:git-pack-refs[1]).
396
397As another useful shortcut, the "HEAD" of a repository can be referred
398to just using the name of that repository. So, for example, "origin"
399is usually a shortcut for the HEAD branch in the repository "origin".
400
401For the complete list of paths which Git checks for references, and
402the order it uses to decide which to choose when there are multiple
403references with the same shorthand name, see the "SPECIFYING
404REVISIONS" section of linkgit:gitrevisions[7].
405
406[[Updating-a-repository-With-git-fetch]]
407=== Updating a repository with git fetch
408
409After you clone a repository and commit a few changes of your own, you
410may wish to check the original repository for updates.
411
412The `git-fetch` command, with no arguments, will update all of the
413remote-tracking branches to the latest version found in the original
414repository. It will not touch any of your own branches--not even the
415"master" branch that was created for you on clone.
416
417[[fetching-branches]]
418=== Fetching branches from other repositories
419
420You can also track branches from repositories other than the one you
421cloned from, using linkgit:git-remote[1]:
422
423-------------------------------------------------
424$ git remote add staging git://git.kernel.org/.../gregkh/staging.git
425$ git fetch staging
426...
427From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging
428 * [new branch] master -> staging/master
429 * [new branch] staging-linus -> staging/staging-linus
430 * [new branch] staging-next -> staging/staging-next
431-------------------------------------------------
432
433New remote-tracking branches will be stored under the shorthand name
434that you gave `git remote add`, in this case `staging`:
435
436-------------------------------------------------
437$ git branch -r
438 origin/HEAD -> origin/master
439 origin/master
440 staging/master
441 staging/staging-linus
442 staging/staging-next
443-------------------------------------------------
444
445If you run `git fetch <remote>` later, the remote-tracking branches
446for the named `<remote>` will be updated.
447
448If you examine the file `.git/config`, you will see that Git has added
449a new stanza:
450
451-------------------------------------------------
452$ cat .git/config
453...
454[remote "staging"]
455 url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git
456 fetch = +refs/heads/*:refs/remotes/staging/*
457...
458-------------------------------------------------
459
460This is what causes Git to track the remote's branches; you may modify
461or delete these configuration options by editing `.git/config` with a
462text editor. (See the "CONFIGURATION FILE" section of
463linkgit:git-config[1] for details.)
464
465[[exploring-git-history]]
466== Exploring Git history
467
468Git is best thought of as a tool for storing the history of a
469collection of files. It does this by storing compressed snapshots of
470the contents of a file hierarchy, together with "commits" which show
471the relationships between these snapshots.
472
473Git provides extremely flexible and fast tools for exploring the
474history of a project.
475
476We start with one specialized tool that is useful for finding the
477commit that introduced a bug into a project.
478
479[[using-bisect]]
480=== How to use bisect to find a regression
481
482Suppose version 2.6.18 of your project worked, but the version at
483"master" crashes. Sometimes the best way to find the cause of such a
484regression is to perform a brute-force search through the project's
485history to find the particular commit that caused the problem. The
486linkgit:git-bisect[1] command can help you do this:
487
488-------------------------------------------------
489$ git bisect start
490$ git bisect good v2.6.18
491$ git bisect bad master
492Bisecting: 3537 revisions left to test after this
493[65934a9a028b88e83e2b0f8b36618fe503349f8e] BLOCK: Make USB storage depend on SCSI rather than selecting it [try #6]
494-------------------------------------------------
495
496If you run `git branch` at this point, you'll see that Git has
497temporarily moved you in "(no branch)". HEAD is now detached from any
498branch and points directly to a commit (with commit id 65934) that
499is reachable from "master" but not from v2.6.18. Compile and test it,
500and see whether it crashes. Assume it does crash. Then:
501
502-------------------------------------------------
503$ git bisect bad
504Bisecting: 1769 revisions left to test after this
505[7eff82c8b1511017ae605f0c99ac275a7e21b867] i2c-core: Drop useless bitmaskings
506-------------------------------------------------
507
508checks out an older version. Continue like this, telling Git at each
509stage whether the version it gives you is good or bad, and notice
510that the number of revisions left to test is cut approximately in
511half each time.
512
513After about 13 tests (in this case), it will output the commit id of
514the guilty commit. You can then examine the commit with
515linkgit:git-show[1], find out who wrote it, and mail them your bug
516report with the commit id. Finally, run
517
518-------------------------------------------------
519$ git bisect reset
520-------------------------------------------------
521
522to return you to the branch you were on before.
523
524Note that the version which `git bisect` checks out for you at each
525point is just a suggestion, and you're free to try a different
526version if you think it would be a good idea. For example,
527occasionally you may land on a commit that broke something unrelated;
528run
529
530-------------------------------------------------
531$ git bisect visualize
532-------------------------------------------------
533
534which will run gitk and label the commit it chose with a marker that
535says "bisect". Choose a safe-looking commit nearby, note its commit
536id, and check it out with:
537
538-------------------------------------------------
539$ git reset --hard fb47ddb2db
540-------------------------------------------------
541
542then test, run `bisect good` or `bisect bad` as appropriate, and
543continue.
544
545Instead of `git bisect visualize` and then `git reset --hard
546fb47ddb2db`, you might just want to tell Git that you want to skip
547the current commit:
548
549-------------------------------------------------
550$ git bisect skip
551-------------------------------------------------
552
553In this case, though, Git may not eventually be able to tell the first
554bad one between some first skipped commits and a later bad commit.
555
556There are also ways to automate the bisecting process if you have a
557test script that can tell a good from a bad commit. See
558linkgit:git-bisect[1] for more information about this and other `git
559bisect` features.
560
561[[naming-commits]]
562=== Naming commits
563
564We have seen several ways of naming commits already:
565
566 - 40-hexdigit object name
567 - branch name: refers to the commit at the head of the given
568 branch
569 - tag name: refers to the commit pointed to by the given tag
570 (we've seen branches and tags are special cases of
571 <<how-git-stores-references,references>>).
572 - HEAD: refers to the head of the current branch
573
574There are many more; see the "SPECIFYING REVISIONS" section of the
575linkgit:gitrevisions[7] man page for the complete list of ways to
576name revisions. Some examples:
577
578-------------------------------------------------
579$ git show fb47ddb2 # the first few characters of the object name
580 # are usually enough to specify it uniquely
581$ git show HEAD^ # the parent of the HEAD commit
582$ git show HEAD^^ # the grandparent
583$ git show HEAD~4 # the great-great-grandparent
584-------------------------------------------------
585
586Recall that merge commits may have more than one parent; by default,
587`^` and `~` follow the first parent listed in the commit, but you can
588also choose:
589
590-------------------------------------------------
591$ git show HEAD^1 # show the first parent of HEAD
592$ git show HEAD^2 # show the second parent of HEAD
593-------------------------------------------------
594
595In addition to HEAD, there are several other special names for
596commits:
597
598Merges (to be discussed later), as well as operations such as
599`git reset`, which change the currently checked-out commit, generally
600set ORIG_HEAD to the value HEAD had before the current operation.
601
602The `git fetch` operation always stores the head of the last fetched
603branch in FETCH_HEAD. For example, if you run `git fetch` without
604specifying a local branch as the target of the operation
605
606-------------------------------------------------
607$ git fetch git://example.com/proj.git theirbranch
608-------------------------------------------------
609
610the fetched commits will still be available from FETCH_HEAD.
611
612When we discuss merges we'll also see the special name MERGE_HEAD,
613which refers to the other branch that we're merging in to the current
614branch.
615
616The linkgit:git-rev-parse[1] command is a low-level command that is
617occasionally useful for translating some name for a commit to the object
618name for that commit:
619
620-------------------------------------------------
621$ git rev-parse origin
622e05db0fd4f31dde7005f075a84f96b360d05984b
623-------------------------------------------------
624
625[[creating-tags]]
626=== Creating tags
627
628We can also create a tag to refer to a particular commit; after
629running
630
631-------------------------------------------------
632$ git tag stable-1 1b2e1d63ff
633-------------------------------------------------
634
635You can use `stable-1` to refer to the commit 1b2e1d63ff.
636
637This creates a "lightweight" tag. If you would also like to include a
638comment with the tag, and possibly sign it cryptographically, then you
639should create a tag object instead; see the linkgit:git-tag[1] man page
640for details.
641
642[[browsing-revisions]]
643=== Browsing revisions
644
645The linkgit:git-log[1] command can show lists of commits. On its
646own, it shows all commits reachable from the parent commit; but you
647can also make more specific requests:
648
649-------------------------------------------------
650$ git log v2.5.. # commits since (not reachable from) v2.5
651$ git log test..master # commits reachable from master but not test
652$ git log master..test # ...reachable from test but not master
653$ git log master...test # ...reachable from either test or master,
654 # but not both
655$ git log --since="2 weeks ago" # commits from the last 2 weeks
656$ git log Makefile # commits which modify Makefile
657$ git log fs/ # ... which modify any file under fs/
658$ git log -S'foo()' # commits which add or remove any file data
659 # matching the string 'foo()'
660-------------------------------------------------
661
662And of course you can combine all of these; the following finds
663commits since v2.5 which touch the `Makefile` or any file under `fs`:
664
665-------------------------------------------------
666$ git log v2.5.. Makefile fs/
667-------------------------------------------------
668
669You can also ask git log to show patches:
670
671-------------------------------------------------
672$ git log -p
673-------------------------------------------------
674
675See the `--pretty` option in the linkgit:git-log[1] man page for more
676display options.
677
678Note that git log starts with the most recent commit and works
679backwards through the parents; however, since Git history can contain
680multiple independent lines of development, the particular order that
681commits are listed in may be somewhat arbitrary.
682
683[[generating-diffs]]
684=== Generating diffs
685
686You can generate diffs between any two versions using
687linkgit:git-diff[1]:
688
689-------------------------------------------------
690$ git diff master..test
691-------------------------------------------------
692
693That will produce the diff between the tips of the two branches. If
694you'd prefer to find the diff from their common ancestor to test, you
695can use three dots instead of two:
696
697-------------------------------------------------
698$ git diff master...test
699-------------------------------------------------
700
701Sometimes what you want instead is a set of patches; for this you can
702use linkgit:git-format-patch[1]:
703
704-------------------------------------------------
705$ git format-patch master..test
706-------------------------------------------------
707
708will generate a file with a patch for each commit reachable from test
709but not from master.
710
711[[viewing-old-file-versions]]
712=== Viewing old file versions
713
714You can always view an old version of a file by just checking out the
715correct revision first. But sometimes it is more convenient to be
716able to view an old version of a single file without checking
717anything out; this command does that:
718
719-------------------------------------------------
720$ git show v2.5:fs/locks.c
721-------------------------------------------------
722
723Before the colon may be anything that names a commit, and after it
724may be any path to a file tracked by Git.
725
726[[history-examples]]
727=== Examples
728
729[[counting-commits-on-a-branch]]
730==== Counting the number of commits on a branch
731
732Suppose you want to know how many commits you've made on `mybranch`
733since it diverged from `origin`:
734
735-------------------------------------------------
736$ git log --pretty=oneline origin..mybranch | wc -l
737-------------------------------------------------
738
739Alternatively, you may often see this sort of thing done with the
740lower-level command linkgit:git-rev-list[1], which just lists the SHA-1's
741of all the given commits:
742
743-------------------------------------------------
744$ git rev-list origin..mybranch | wc -l
745-------------------------------------------------
746
747[[checking-for-equal-branches]]
748==== Check whether two branches point at the same history
749
750Suppose you want to check whether two branches point at the same point
751in history.
752
753-------------------------------------------------
754$ git diff origin..master
755-------------------------------------------------
756
757will tell you whether the contents of the project are the same at the
758two branches; in theory, however, it's possible that the same project
759contents could have been arrived at by two different historical
760routes. You could compare the object names:
761
762-------------------------------------------------
763$ git rev-list origin
764e05db0fd4f31dde7005f075a84f96b360d05984b
765$ git rev-list master
766e05db0fd4f31dde7005f075a84f96b360d05984b
767-------------------------------------------------
768
769Or you could recall that the `...` operator selects all commits
770reachable from either one reference or the other but not
771both; so
772
773-------------------------------------------------
774$ git log origin...master
775-------------------------------------------------
776
777will return no commits when the two branches are equal.
778
779[[finding-tagged-descendants]]
780==== Find first tagged version including a given fix
781
782Suppose you know that the commit e05db0fd fixed a certain problem.
783You'd like to find the earliest tagged release that contains that
784fix.
785
786Of course, there may be more than one answer--if the history branched
787after commit e05db0fd, then there could be multiple "earliest" tagged
788releases.
789
790You could just visually inspect the commits since e05db0fd:
791
792-------------------------------------------------
793$ gitk e05db0fd..
794-------------------------------------------------
795
796or you can use linkgit:git-name-rev[1], which will give the commit a
797name based on any tag it finds pointing to one of the commit's
798descendants:
799
800-------------------------------------------------
801$ git name-rev --tags e05db0fd
802e05db0fd tags/v1.5.0-rc1^0~23
803-------------------------------------------------
804
805The linkgit:git-describe[1] command does the opposite, naming the
806revision using a tag on which the given commit is based:
807
808-------------------------------------------------
809$ git describe e05db0fd
810v1.5.0-rc0-260-ge05db0f
811-------------------------------------------------
812
813but that may sometimes help you guess which tags might come after the
814given commit.
815
816If you just want to verify whether a given tagged version contains a
817given commit, you could use linkgit:git-merge-base[1]:
818
819-------------------------------------------------
820$ git merge-base e05db0fd v1.5.0-rc1
821e05db0fd4f31dde7005f075a84f96b360d05984b
822-------------------------------------------------
823
824The merge-base command finds a common ancestor of the given commits,
825and always returns one or the other in the case where one is a
826descendant of the other; so the above output shows that e05db0fd
827actually is an ancestor of v1.5.0-rc1.
828
829Alternatively, note that
830
831-------------------------------------------------
832$ git log v1.5.0-rc1..e05db0fd
833-------------------------------------------------
834
835will produce empty output if and only if v1.5.0-rc1 includes e05db0fd,
836because it outputs only commits that are not reachable from v1.5.0-rc1.
837
838As yet another alternative, the linkgit:git-show-branch[1] command lists
839the commits reachable from its arguments with a display on the left-hand
840side that indicates which arguments that commit is reachable from.
841So, if you run something like
842
843-------------------------------------------------
844$ git show-branch e05db0fd v1.5.0-rc0 v1.5.0-rc1 v1.5.0-rc2
845! [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
846available
847 ! [v1.5.0-rc0] GIT v1.5.0 preview
848 ! [v1.5.0-rc1] GIT v1.5.0-rc1
849 ! [v1.5.0-rc2] GIT v1.5.0-rc2
850...
851-------------------------------------------------
852
853then a line like
854
855-------------------------------------------------
856+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
857available
858-------------------------------------------------
859
860shows that e05db0fd is reachable from itself, from v1.5.0-rc1,
861and from v1.5.0-rc2, and not from v1.5.0-rc0.
862
863[[showing-commits-unique-to-a-branch]]
864==== Showing commits unique to a given branch
865
866Suppose you would like to see all the commits reachable from the branch
867head named `master` but not from any other head in your repository.
868
869We can list all the heads in this repository with
870linkgit:git-show-ref[1]:
871
872-------------------------------------------------
873$ git show-ref --heads
874bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
875db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
876a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
87724dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
8781e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes
879-------------------------------------------------
880
881We can get just the branch-head names, and remove `master`, with
882the help of the standard utilities cut and grep:
883
884-------------------------------------------------
885$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
886refs/heads/core-tutorial
887refs/heads/maint
888refs/heads/tutorial-2
889refs/heads/tutorial-fixes
890-------------------------------------------------
891
892And then we can ask to see all the commits reachable from master
893but not from these other heads:
894
895-------------------------------------------------
896$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
897 grep -v '^refs/heads/master' )
898-------------------------------------------------
899
900Obviously, endless variations are possible; for example, to see all
901commits reachable from some head but not from any tag in the repository:
902
903-------------------------------------------------
904$ gitk $( git show-ref --heads ) --not $( git show-ref --tags )
905-------------------------------------------------
906
907(See linkgit:gitrevisions[7] for explanations of commit-selecting
908syntax such as `--not`.)
909
910[[making-a-release]]
911==== Creating a changelog and tarball for a software release
912
913The linkgit:git-archive[1] command can create a tar or zip archive from
914any version of a project; for example:
915
916-------------------------------------------------
917$ git archive -o latest.tar.gz --prefix=project/ HEAD
918-------------------------------------------------
919
920will use HEAD to produce a gzipped tar archive in which each filename
921is preceded by `project/`. The output file format is inferred from
922the output file extension if possible, see linkgit:git-archive[1] for
923details.
924
925Versions of Git older than 1.7.7 don't know about the `tar.gz` format,
926you'll need to use gzip explicitly:
927
928-------------------------------------------------
929$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
930-------------------------------------------------
931
932If you're releasing a new version of a software project, you may want
933to simultaneously make a changelog to include in the release
934announcement.
935
936Linus Torvalds, for example, makes new kernel releases by tagging them,
937then running:
938
939-------------------------------------------------
940$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
941-------------------------------------------------
942
943where release-script is a shell script that looks like:
944
945-------------------------------------------------
946#!/bin/sh
947stable="$1"
948last="$2"
949new="$3"
950echo "# git tag v$new"
951echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
952echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
953echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
954echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
955echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
956-------------------------------------------------
957
958and then he just cut-and-pastes the output commands after verifying that
959they look OK.
960
961[[Finding-commits-With-given-Content]]
962==== Finding commits referencing a file with given content
963
964Somebody hands you a copy of a file, and asks which commits modified a
965file such that it contained the given content either before or after the
966commit. You can find out with this:
967
968-------------------------------------------------
969$ git log --raw --abbrev=40 --pretty=oneline |
970 grep -B 1 `git hash-object filename`
971-------------------------------------------------
972
973Figuring out why this works is left as an exercise to the (advanced)
974student. The linkgit:git-log[1], linkgit:git-diff-tree[1], and
975linkgit:git-hash-object[1] man pages may prove helpful.
976
977[[Developing-With-git]]
978== Developing with Git
979
980[[telling-git-your-name]]
981=== Telling Git your name
982
983Before creating any commits, you should introduce yourself to Git.
984The easiest way to do so is to use linkgit:git-config[1]:
985
986------------------------------------------------
987$ git config --global user.name 'Your Name Comes Here'
988$ git config --global user.email 'you@yourdomain.example.com'
989------------------------------------------------
990
991Which will add the following to a file named `.gitconfig` in your
992home directory:
993
994------------------------------------------------
995[user]
996 name = Your Name Comes Here
997 email = you@yourdomain.example.com
998------------------------------------------------
999
1000See the "CONFIGURATION FILE" section of linkgit:git-config[1] for
1001details on the configuration file. The file is plain text, so you can
1002also edit it with your favorite editor.
1003
1004
1005[[creating-a-new-repository]]
1006=== Creating a new repository
1007
1008Creating a new repository from scratch is very easy:
1009
1010-------------------------------------------------
1011$ mkdir project
1012$ cd project
1013$ git init
1014-------------------------------------------------
1015
1016If you have some initial content (say, a tarball):
1017
1018-------------------------------------------------
1019$ tar xzvf project.tar.gz
1020$ cd project
1021$ git init
1022$ git add . # include everything below ./ in the first commit:
1023$ git commit
1024-------------------------------------------------
1025
1026[[how-to-make-a-commit]]
1027=== How to make a commit
1028
1029Creating a new commit takes three steps:
1030
1031 1. Making some changes to the working directory using your
1032 favorite editor.
1033 2. Telling Git about your changes.
1034 3. Creating the commit using the content you told Git about
1035 in step 2.
1036
1037In practice, you can interleave and repeat steps 1 and 2 as many
1038times as you want: in order to keep track of what you want committed
1039at step 3, Git maintains a snapshot of the tree's contents in a
1040special staging area called "the index."
1041
1042At the beginning, the content of the index will be identical to
1043that of the HEAD. The command `git diff --cached`, which shows
1044the difference between the HEAD and the index, should therefore
1045produce no output at that point.
1046
1047Modifying the index is easy:
1048
1049To update the index with the contents of a new or modified file, use
1050
1051-------------------------------------------------
1052$ git add path/to/file
1053-------------------------------------------------
1054
1055To remove a file from the index and from the working tree, use
1056
1057-------------------------------------------------
1058$ git rm path/to/file
1059-------------------------------------------------
1060
1061After each step you can verify that
1062
1063-------------------------------------------------
1064$ git diff --cached
1065-------------------------------------------------
1066
1067always shows the difference between the HEAD and the index file--this
1068is what you'd commit if you created the commit now--and that
1069
1070-------------------------------------------------
1071$ git diff
1072-------------------------------------------------
1073
1074shows the difference between the working tree and the index file.
1075
1076Note that `git add` always adds just the current contents of a file
1077to the index; further changes to the same file will be ignored unless
1078you run `git add` on the file again.
1079
1080When you're ready, just run
1081
1082-------------------------------------------------
1083$ git commit
1084-------------------------------------------------
1085
1086and Git will prompt you for a commit message and then create the new
1087commit. Check to make sure it looks like what you expected with
1088
1089-------------------------------------------------
1090$ git show
1091-------------------------------------------------
1092
1093As a special shortcut,
1094
1095-------------------------------------------------
1096$ git commit -a
1097-------------------------------------------------
1098
1099will update the index with any files that you've modified or removed
1100and create a commit, all in one step.
1101
1102A number of commands are useful for keeping track of what you're
1103about to commit:
1104
1105-------------------------------------------------
1106$ git diff --cached # difference between HEAD and the index; what
1107 # would be committed if you ran "commit" now.
1108$ git diff # difference between the index file and your
1109 # working directory; changes that would not
1110 # be included if you ran "commit" now.
1111$ git diff HEAD # difference between HEAD and working tree; what
1112 # would be committed if you ran "commit -a" now.
1113$ git status # a brief per-file summary of the above.
1114-------------------------------------------------
1115
1116You can also use linkgit:git-gui[1] to create commits, view changes in
1117the index and the working tree files, and individually select diff hunks
1118for inclusion in the index (by right-clicking on the diff hunk and
1119choosing "Stage Hunk For Commit").
1120
1121[[creating-good-commit-messages]]
1122=== Creating good commit messages
1123
1124Though not required, it's a good idea to begin the commit message
1125with a single short (no more than 50 characters) line summarizing the
1126change, followed by a blank line and then a more thorough
1127description. The text up to the first blank line in a commit
1128message is treated as the commit title, and that title is used
1129throughout Git. For example, linkgit:git-format-patch[1] turns a
1130commit into email, and it uses the title on the Subject line and the
1131rest of the commit in the body.
1132
1133
1134[[ignoring-files]]
1135=== Ignoring files
1136
1137A project will often generate files that you do 'not' want to track with Git.
1138This typically includes files generated by a build process or temporary
1139backup files made by your editor. Of course, 'not' tracking files with Git
1140is just a matter of 'not' calling `git add` on them. But it quickly becomes
1141annoying to have these untracked files lying around; e.g. they make
1142`git add .` practically useless, and they keep showing up in the output of
1143`git status`.
1144
1145You can tell Git to ignore certain files by creating a file called
1146`.gitignore` in the top level of your working directory, with contents
1147such as:
1148
1149-------------------------------------------------
1150# Lines starting with '#' are considered comments.
1151# Ignore any file named foo.txt.
1152foo.txt
1153# Ignore (generated) html files,
1154*.html
1155# except foo.html which is maintained by hand.
1156!foo.html
1157# Ignore objects and archives.
1158*.[oa]
1159-------------------------------------------------
1160
1161See linkgit:gitignore[5] for a detailed explanation of the syntax. You can
1162also place .gitignore files in other directories in your working tree, and they
1163will apply to those directories and their subdirectories. The `.gitignore`
1164files can be added to your repository like any other files (just run `git add
1165.gitignore` and `git commit`, as usual), which is convenient when the exclude
1166patterns (such as patterns matching build output files) would also make sense
1167for other users who clone your repository.
1168
1169If you wish the exclude patterns to affect only certain repositories
1170(instead of every repository for a given project), you may instead put
1171them in a file in your repository named `.git/info/exclude`, or in any
1172file specified by the `core.excludesFile` configuration variable.
1173Some Git commands can also take exclude patterns directly on the
1174command line. See linkgit:gitignore[5] for the details.
1175
1176[[how-to-merge]]
1177=== How to merge
1178
1179You can rejoin two diverging branches of development using
1180linkgit:git-merge[1]:
1181
1182-------------------------------------------------
1183$ git merge branchname
1184-------------------------------------------------
1185
1186merges the development in the branch `branchname` into the current
1187branch.
1188
1189A merge is made by combining the changes made in `branchname` and the
1190changes made up to the latest commit in your current branch since
1191their histories forked. The work tree is overwritten by the result of
1192the merge when this combining is done cleanly, or overwritten by a
1193half-merged results when this combining results in conflicts.
1194Therefore, if you have uncommitted changes touching the same files as
1195the ones impacted by the merge, Git will refuse to proceed. Most of
1196the time, you will want to commit your changes before you can merge,
1197and if you don't, then linkgit:git-stash[1] can take these changes
1198away while you're doing the merge, and reapply them afterwards.
1199
1200If the changes are independent enough, Git will automatically complete
1201the merge and commit the result (or reuse an existing commit in case
1202of <<fast-forwards,fast-forward>>, see below). On the other hand,
1203if there are conflicts--for example, if the same file is
1204modified in two different ways in the remote branch and the local
1205branch--then you are warned; the output may look something like this:
1206
1207-------------------------------------------------
1208$ git merge next
1209 100% (4/4) done
1210Auto-merged file.txt
1211CONFLICT (content): Merge conflict in file.txt
1212Automatic merge failed; fix conflicts and then commit the result.
1213-------------------------------------------------
1214
1215Conflict markers are left in the problematic files, and after
1216you resolve the conflicts manually, you can update the index
1217with the contents and run Git commit, as you normally would when
1218creating a new file.
1219
1220If you examine the resulting commit using gitk, you will see that it
1221has two parents, one pointing to the top of the current branch, and
1222one to the top of the other branch.
1223
1224[[resolving-a-merge]]
1225=== Resolving a merge
1226
1227When a merge isn't resolved automatically, Git leaves the index and
1228the working tree in a special state that gives you all the
1229information you need to help resolve the merge.
1230
1231Files with conflicts are marked specially in the index, so until you
1232resolve the problem and update the index, linkgit:git-commit[1] will
1233fail:
1234
1235-------------------------------------------------
1236$ git commit
1237file.txt: needs merge
1238-------------------------------------------------
1239
1240Also, linkgit:git-status[1] will list those files as "unmerged", and the
1241files with conflicts will have conflict markers added, like this:
1242
1243-------------------------------------------------
1244<<<<<<< HEAD:file.txt
1245Hello world
1246=======
1247Goodbye
1248>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1249-------------------------------------------------
1250
1251All you need to do is edit the files to resolve the conflicts, and then
1252
1253-------------------------------------------------
1254$ git add file.txt
1255$ git commit
1256-------------------------------------------------
1257
1258Note that the commit message will already be filled in for you with
1259some information about the merge. Normally you can just use this
1260default message unchanged, but you may add additional commentary of
1261your own if desired.
1262
1263The above is all you need to know to resolve a simple merge. But Git
1264also provides more information to help resolve conflicts:
1265
1266[[conflict-resolution]]
1267==== Getting conflict-resolution help during a merge
1268
1269All of the changes that Git was able to merge automatically are
1270already added to the index file, so linkgit:git-diff[1] shows only
1271the conflicts. It uses an unusual syntax:
1272
1273-------------------------------------------------
1274$ git diff
1275diff --cc file.txt
1276index 802992c,2b60207..0000000
1277--- a/file.txt
1278+++ b/file.txt
1279@@@ -1,1 -1,1 +1,5 @@@
1280++<<<<<<< HEAD:file.txt
1281 +Hello world
1282++=======
1283+ Goodbye
1284++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1285-------------------------------------------------
1286
1287Recall that the commit which will be committed after we resolve this
1288conflict will have two parents instead of the usual one: one parent
1289will be HEAD, the tip of the current branch; the other will be the
1290tip of the other branch, which is stored temporarily in MERGE_HEAD.
1291
1292During the merge, the index holds three versions of each file. Each of
1293these three "file stages" represents a different version of the file:
1294
1295-------------------------------------------------
1296$ git show :1:file.txt # the file in a common ancestor of both branches
1297$ git show :2:file.txt # the version from HEAD.
1298$ git show :3:file.txt # the version from MERGE_HEAD.
1299-------------------------------------------------
1300
1301When you ask linkgit:git-diff[1] to show the conflicts, it runs a
1302three-way diff between the conflicted merge results in the work tree with
1303stages 2 and 3 to show only hunks whose contents come from both sides,
1304mixed (in other words, when a hunk's merge results come only from stage 2,
1305that part is not conflicting and is not shown. Same for stage 3).
1306
1307The diff above shows the differences between the working-tree version of
1308file.txt and the stage 2 and stage 3 versions. So instead of preceding
1309each line by a single `+` or `-`, it now uses two columns: the first
1310column is used for differences between the first parent and the working
1311directory copy, and the second for differences between the second parent
1312and the working directory copy. (See the "COMBINED DIFF FORMAT" section
1313of linkgit:git-diff-files[1] for a details of the format.)
1314
1315After resolving the conflict in the obvious way (but before updating the
1316index), the diff will look like:
1317
1318-------------------------------------------------
1319$ git diff
1320diff --cc file.txt
1321index 802992c,2b60207..0000000
1322--- a/file.txt
1323+++ b/file.txt
1324@@@ -1,1 -1,1 +1,1 @@@
1325- Hello world
1326 -Goodbye
1327++Goodbye world
1328-------------------------------------------------
1329
1330This shows that our resolved version deleted "Hello world" from the
1331first parent, deleted "Goodbye" from the second parent, and added
1332"Goodbye world", which was previously absent from both.
1333
1334Some special diff options allow diffing the working directory against
1335any of these stages:
1336
1337-------------------------------------------------
1338$ git diff -1 file.txt # diff against stage 1
1339$ git diff --base file.txt # same as the above
1340$ git diff -2 file.txt # diff against stage 2
1341$ git diff --ours file.txt # same as the above
1342$ git diff -3 file.txt # diff against stage 3
1343$ git diff --theirs file.txt # same as the above.
1344-------------------------------------------------
1345
1346When using the 'ort' merge strategy (the default), before updating the working
1347tree with the result of the merge, Git writes a ref named AUTO_MERGE
1348reflecting the state of the tree it is about to write. Conflicted paths with
1349textual conflicts that could not be automatically merged are written to this
1350tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
1351used with linkgit:git-diff[1] to show the changes you've made so far to resolve
1352conflicts. Using the same example as above, after resolving the conflict we
1353get:
1354
1355-------------------------------------------------
1356$ git diff AUTO_MERGE
1357diff --git a/file.txt b/file.txt
1358index cd10406..8bf5ae7 100644
1359--- a/file.txt
1360+++ b/file.txt
1361@@ -1,5 +1 @@
1362-<<<<<<< HEAD:file.txt
1363-Hello world
1364-=======
1365-Goodbye
1366->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1367+Goodbye world
1368-------------------------------------------------
1369
1370Notice that the diff shows we deleted the conflict markers and both versions of
1371the content line, and wrote "Goodbye world" instead.
1372
1373The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
1374for merges:
1375
1376-------------------------------------------------
1377$ git log --merge
1378$ gitk --merge
1379-------------------------------------------------
1380
1381These will display all commits which exist only on HEAD or on
1382MERGE_HEAD, and which touch an unmerged file.
1383
1384You may also use linkgit:git-mergetool[1], which lets you merge the
1385unmerged files using external tools such as Emacs or kdiff3.
1386
1387Each time you resolve the conflicts in a file and update the index:
1388
1389-------------------------------------------------
1390$ git add file.txt
1391-------------------------------------------------
1392
1393the different stages of that file will be "collapsed", after which
1394`git diff` will (by default) no longer show diffs for that file.
1395
1396[[undoing-a-merge]]
1397=== Undoing a merge
1398
1399If you get stuck and decide to just give up and throw the whole mess
1400away, you can always return to the pre-merge state with
1401
1402-------------------------------------------------
1403$ git merge --abort
1404-------------------------------------------------
1405
1406Or, if you've already committed the merge that you want to throw away,
1407
1408-------------------------------------------------
1409$ git reset --hard ORIG_HEAD
1410-------------------------------------------------
1411
1412However, this last command can be dangerous in some cases--never
1413throw away a commit you have already committed if that commit may
1414itself have been merged into another branch, as doing so may confuse
1415further merges.
1416
1417[[fast-forwards]]
1418=== Fast-forward merges
1419
1420There is one special case not mentioned above, which is treated
1421differently. Normally, a merge results in a merge commit, with two
1422parents, one pointing at each of the two lines of development that
1423were merged.
1424
1425However, if the current branch is an ancestor of the other--so every commit
1426present in the current branch is already contained in the other branch--then Git
1427just performs a "fast-forward"; the head of the current branch is moved forward
1428to point at the head of the merged-in branch, without any new commits being
1429created.
1430
1431[[fixing-mistakes]]
1432=== Fixing mistakes
1433
1434If you've messed up the working tree, but haven't yet committed your
1435mistake, you can return the entire working tree to the last committed
1436state with
1437
1438-------------------------------------------------
1439$ git restore --staged --worktree :/
1440-------------------------------------------------
1441
1442If you make a commit that you later wish you hadn't, there are two
1443fundamentally different ways to fix the problem:
1444
1445 1. You can create a new commit that undoes whatever was done
1446 by the old commit. This is the correct thing if your
1447 mistake has already been made public.
1448
1449 2. You can go back and modify the old commit. You should
1450 never do this if you have already made the history public;
1451 Git does not normally expect the "history" of a project to
1452 change, and cannot correctly perform repeated merges from
1453 a branch that has had its history changed.
1454
1455[[reverting-a-commit]]
1456==== Fixing a mistake with a new commit
1457
1458Creating a new commit that reverts an earlier change is very easy;
1459just pass the linkgit:git-revert[1] command a reference to the bad
1460commit; for example, to revert the most recent commit:
1461
1462-------------------------------------------------
1463$ git revert HEAD
1464-------------------------------------------------
1465
1466This will create a new commit which undoes the change in HEAD. You
1467will be given a chance to edit the commit message for the new commit.
1468
1469You can also revert an earlier change, for example, the next-to-last:
1470
1471-------------------------------------------------
1472$ git revert HEAD^
1473-------------------------------------------------
1474
1475In this case Git will attempt to undo the old change while leaving
1476intact any changes made since then. If more recent changes overlap
1477with the changes to be reverted, then you will be asked to fix
1478conflicts manually, just as in the case of <<resolving-a-merge,
1479resolving a merge>>.
1480
1481[[fixing-a-mistake-by-rewriting-history]]
1482==== Fixing a mistake by rewriting history
1483
1484If the problematic commit is the most recent commit, and you have not
1485yet made that commit public, then you may just
1486<<undoing-a-merge,destroy it using `git reset`>>.
1487
1488Alternatively, you
1489can edit the working directory and update the index to fix your
1490mistake, just as if you were going to <<how-to-make-a-commit,create a
1491new commit>>, then run
1492
1493-------------------------------------------------
1494$ git commit --amend
1495-------------------------------------------------
1496
1497which will replace the old commit by a new commit incorporating your
1498changes, giving you a chance to edit the old commit message first.
1499
1500Again, you should never do this to a commit that may already have
1501been merged into another branch; use linkgit:git-revert[1] instead in
1502that case.
1503
1504It is also possible to replace commits further back in the history, but
1505this is an advanced topic to be left for
1506<<cleaning-up-history,another chapter>>.
1507
1508[[checkout-of-path]]
1509==== Checking out an old version of a file
1510
1511In the process of undoing a previous bad change, you may find it
1512useful to check out an older version of a particular file using
1513linkgit:git-restore[1]. The command
1514
1515-------------------------------------------------
1516$ git restore --source=HEAD^ path/to/file
1517-------------------------------------------------
1518
1519replaces path/to/file by the contents it had in the commit HEAD^, and
1520also updates the index to match. It does not change branches.
1521
1522If you just want to look at an old version of the file, without
1523modifying the working directory, you can do that with
1524linkgit:git-show[1]:
1525
1526-------------------------------------------------
1527$ git show HEAD^:path/to/file
1528-------------------------------------------------
1529
1530which will display the given version of the file.
1531
1532[[interrupted-work]]
1533==== Temporarily setting aside work in progress
1534
1535While you are in the middle of working on something complicated, you
1536find an unrelated but obvious and trivial bug. You would like to fix it
1537before continuing. You can use linkgit:git-stash[1] to save the current
1538state of your work, and after fixing the bug (or, optionally after doing
1539so on a different branch and then coming back), unstash the
1540work-in-progress changes.
1541
1542------------------------------------------------
1543$ git stash push -m "work in progress for foo feature"
1544------------------------------------------------
1545
1546This command will save your changes away to the `stash`, and
1547reset your working tree and the index to match the tip of your
1548current branch. Then you can make your fix as usual.
1549
1550------------------------------------------------
1551... edit and test ...
1552$ git commit -a -m "blorpl: typofix"
1553------------------------------------------------
1554
1555After that, you can go back to what you were working on with
1556`git stash pop`:
1557
1558------------------------------------------------
1559$ git stash pop
1560------------------------------------------------
1561
1562
1563[[ensuring-good-performance]]
1564=== Ensuring good performance
1565
1566On large repositories, Git depends on compression to keep the history
1567information from taking up too much space on disk or in memory. Some
1568Git commands may automatically run linkgit:git-gc[1], so you don't
1569have to worry about running it manually. However, compressing a large
1570repository may take a while, so you may want to call `gc` explicitly
1571to avoid automatic compression kicking in when it is not convenient.
1572
1573
1574[[ensuring-reliability]]
1575=== Ensuring reliability
1576
1577[[checking-for-corruption]]
1578==== Checking the repository for corruption
1579
1580The linkgit:git-fsck[1] command runs a number of self-consistency checks
1581on the repository, and reports on any problems. This may take some
1582time.
1583
1584-------------------------------------------------
1585$ git fsck
1586dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1587dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1588dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1589dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
1590dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
1591dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
1592dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
1593dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
1594...
1595-------------------------------------------------
1596
1597You will see informational messages on dangling objects. They are objects
1598that still exist in the repository but are no longer referenced by any of
1599your branches, and can (and will) be removed after a while with `gc`.
1600You can run `git fsck --no-dangling` to suppress these messages, and still
1601view real errors.
1602
1603[[recovering-lost-changes]]
1604==== Recovering lost changes
1605
1606[[reflogs]]
1607===== Reflogs
1608
1609Say you modify a branch with <<fixing-mistakes,`git reset --hard`>>,
1610and then realize that the branch was the only reference you had to
1611that point in history.
1612
1613Fortunately, Git also keeps a log, called a "reflog", of all the
1614previous values of each branch. So in this case you can still find the
1615old history using, for example,
1616
1617-------------------------------------------------
1618$ git log master@{1}
1619-------------------------------------------------
1620
1621This lists the commits reachable from the previous version of the
1622`master` branch head. This syntax can be used with any Git command
1623that accepts a commit, not just with `git log`. Some other examples:
1624
1625-------------------------------------------------
1626$ git show master@{2} # See where the branch pointed 2,
1627$ git show master@{3} # 3, ... changes ago.
1628$ gitk master@{yesterday} # See where it pointed yesterday,
1629$ gitk master@{"1 week ago"} # ... or last week
1630$ git log --walk-reflogs master # show reflog entries for master
1631-------------------------------------------------
1632
1633A separate reflog is kept for the HEAD, so
1634
1635-------------------------------------------------
1636$ git show HEAD@{"1 week ago"}
1637-------------------------------------------------
1638
1639will show what HEAD pointed to one week ago, not what the current branch
1640pointed to one week ago. This allows you to see the history of what
1641you've checked out.
1642
1643The reflogs are kept by default for 30 days, after which they may be
1644pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
1645how to control this pruning, and see the "SPECIFYING REVISIONS"
1646section of linkgit:gitrevisions[7] for details.
1647
1648Note that the reflog history is very different from normal Git history.
1649While normal history is shared by every repository that works on the
1650same project, the reflog history is not shared: it tells you only about
1651how the branches in your local repository have changed over time.
1652
1653[[dangling-object-recovery]]
1654===== Examining dangling objects
1655
1656In some situations the reflog may not be able to save you. For example,
1657suppose you delete a branch, then realize you need the history it
1658contained. The reflog is also deleted; however, if you have not yet
1659pruned the repository, then you may still be able to find the lost
1660commits in the dangling objects that `git fsck` reports. See
1661<<dangling-objects>> for the details.
1662
1663-------------------------------------------------
1664$ git fsck
1665dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
1666dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
1667dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
1668...
1669-------------------------------------------------
1670
1671You can examine
1672one of those dangling commits with, for example,
1673
1674------------------------------------------------
1675$ gitk 7281251ddd --not --all
1676------------------------------------------------
1677
1678which does what it sounds like: it says that you want to see the commit
1679history that is described by the dangling commit(s), but not the
1680history that is described by all your existing branches and tags. Thus
1681you get exactly the history reachable from that commit that is lost.
1682(And notice that it might not be just one commit: we only report the
1683"tip of the line" as being dangling, but there might be a whole deep
1684and complex commit history that was dropped.)
1685
1686If you decide you want the history back, you can always create a new
1687reference pointing to it, for example, a new branch:
1688
1689------------------------------------------------
1690$ git branch recovered-branch 7281251ddd
1691------------------------------------------------
1692
1693Other types of dangling objects (blobs and trees) are also possible, and
1694dangling objects can arise in other situations.
1695
1696
1697[[sharing-development]]
1698== Sharing development with others
1699
1700[[getting-updates-With-git-pull]]
1701=== Getting updates with git pull
1702
1703After you clone a repository and commit a few changes of your own, you
1704may wish to check the original repository for updates and merge them
1705into your own work.
1706
1707We have already seen <<Updating-a-repository-With-git-fetch,how to
1708keep remote-tracking branches up to date>> with linkgit:git-fetch[1],
1709and how to merge two branches. So you can merge in changes from the
1710original repository's master branch with:
1711
1712-------------------------------------------------
1713$ git fetch
1714$ git merge origin/master
1715-------------------------------------------------
1716
1717However, the linkgit:git-pull[1] command provides a way to do this in
1718one step:
1719
1720-------------------------------------------------
1721$ git pull origin master
1722-------------------------------------------------
1723
1724In fact, if you have `master` checked out, then this branch has been
1725configured by `git clone` to get changes from the HEAD branch of the
1726origin repository. So often you can
1727accomplish the above with just a simple
1728
1729-------------------------------------------------
1730$ git pull
1731-------------------------------------------------
1732
1733This command will fetch changes from the remote branches to your
1734remote-tracking branches `origin/*`, and merge the default branch into
1735the current branch.
1736
1737More generally, a branch that is created from a remote-tracking branch
1738will pull
1739by default from that branch. See the descriptions of the
1740`branch.<name>.remote` and `branch.<name>.merge` options in
1741linkgit:git-config[1], and the discussion of the `--track` option in
1742linkgit:git-checkout[1], to learn how to control these defaults.
1743
1744In addition to saving you keystrokes, `git pull` also helps you by
1745producing a default commit message documenting the branch and
1746repository that you pulled from.
1747
1748(But note that no such commit will be created in the case of a
1749<<fast-forwards,fast-forward>>; instead, your branch will just be
1750updated to point to the latest commit from the upstream branch.)
1751
1752The `git pull` command can also be given `.` as the "remote" repository,
1753in which case it just merges in a branch from the current repository; so
1754the commands
1755
1756-------------------------------------------------
1757$ git pull . branch
1758$ git merge branch
1759-------------------------------------------------
1760
1761are roughly equivalent.
1762
1763[[submitting-patches]]
1764=== Submitting patches to a project
1765
1766If you just have a few changes, the simplest way to submit them may
1767just be to send them as patches in email:
1768
1769First, use linkgit:git-format-patch[1]; for example:
1770
1771-------------------------------------------------
1772$ git format-patch origin
1773-------------------------------------------------
1774
1775will produce a numbered series of files in the current directory, one
1776for each patch in the current branch but not in `origin/HEAD`.
1777
1778`git format-patch` can include an initial "cover letter". You can insert
1779commentary on individual patches after the three dash line which
1780`format-patch` places after the commit message but before the patch
1781itself. If you use `git notes` to track your cover letter material,
1782`git format-patch --notes` will include the commit's notes in a similar
1783manner.
1784
1785You can then import these into your mail client and send them by
1786hand. However, if you have a lot to send at once, you may prefer to
1787use the linkgit:git-send-email[1] script to automate the process.
1788Consult the mailing list for your project first to determine
1789their requirements for submitting patches.
1790
1791[[importing-patches]]
1792=== Importing patches to a project
1793
1794Git also provides a tool called linkgit:git-am[1] (am stands for
1795"apply mailbox"), for importing such an emailed series of patches.
1796Just save all of the patch-containing messages, in order, into a
1797single mailbox file, say `patches.mbox`, then run
1798
1799-------------------------------------------------
1800$ git am -3 patches.mbox
1801-------------------------------------------------
1802
1803Git will apply each patch in order; if any conflicts are found, it
1804will stop, and you can fix the conflicts as described in
1805"<<resolving-a-merge,Resolving a merge>>". (The `-3` option tells
1806Git to perform a merge; if you would prefer it just to abort and
1807leave your tree and index untouched, you may omit that option.)
1808
1809Once the index is updated with the results of the conflict
1810resolution, instead of creating a new commit, just run
1811
1812-------------------------------------------------
1813$ git am --continue
1814-------------------------------------------------
1815
1816and Git will create the commit for you and continue applying the
1817remaining patches from the mailbox.
1818
1819The final result will be a series of commits, one for each patch in
1820the original mailbox, with authorship and commit log message each
1821taken from the message containing each patch.
1822
1823[[public-repositories]]
1824=== Public Git repositories
1825
1826Another way to submit changes to a project is to tell the maintainer
1827of that project to pull the changes from your repository using
1828linkgit:git-pull[1]. In the section "<<getting-updates-With-git-pull,
1829Getting updates with `git pull`>>" we described this as a way to get
1830updates from the "main" repository, but it works just as well in the
1831other direction.
1832
1833If you and the maintainer both have accounts on the same machine, then
1834you can just pull changes from each other's repositories directly;
1835commands that accept repository URLs as arguments will also accept a
1836local directory name:
1837
1838-------------------------------------------------
1839$ git clone /path/to/repository
1840$ git pull /path/to/other/repository
1841-------------------------------------------------
1842
1843or an ssh URL:
1844
1845-------------------------------------------------
1846$ git clone ssh://yourhost/~you/repository
1847-------------------------------------------------
1848
1849For projects with few developers, or for synchronizing a few private
1850repositories, this may be all you need.
1851
1852However, the more common way to do this is to maintain a separate public
1853repository (usually on a different host) for others to pull changes
1854from. This is usually more convenient, and allows you to cleanly
1855separate private work in progress from publicly visible work.
1856
1857You will continue to do your day-to-day work in your personal
1858repository, but periodically "push" changes from your personal
1859repository into your public repository, allowing other developers to
1860pull from that repository. So the flow of changes, in a situation
1861where there is one other developer with a public repository, looks
1862like this:
1863
1864....
1865 you push
1866your personal repo ------------------> your public repo
1867 ^ |
1868 | |
1869 | you pull | they pull
1870 | |
1871 | |
1872 | they push V
1873their public repo <------------------- their repo
1874....
1875
1876We explain how to do this in the following sections.
1877
1878[[setting-up-a-public-repository]]
1879==== Setting up a public repository
1880
1881Assume your personal repository is in the directory `~/proj`. We
1882first create a new clone of the repository and tell `git daemon` that it
1883is meant to be public:
1884
1885-------------------------------------------------
1886$ git clone --bare ~/proj proj.git
1887$ touch proj.git/git-daemon-export-ok
1888-------------------------------------------------
1889
1890The resulting directory proj.git contains a "bare" git repository--it is
1891just the contents of the `.git` directory, without any files checked out
1892around it.
1893
1894Next, copy `proj.git` to the server where you plan to host the
1895public repository. You can use scp, rsync, or whatever is most
1896convenient.
1897
1898[[exporting-via-git]]
1899==== Exporting a Git repository via the Git protocol
1900
1901This is the preferred method.
1902
1903If someone else administers the server, they should tell you what
1904directory to put the repository in, and what `git://` URL it will
1905appear at. You can then skip to the section
1906"<<pushing-changes-to-a-public-repository,Pushing changes to a public
1907repository>>", below.
1908
1909Otherwise, all you need to do is start linkgit:git-daemon[1]; it will
1910listen on port 9418. By default, it will allow access to any directory
1911that looks like a Git directory and contains the magic file
1912git-daemon-export-ok. Passing some directory paths as `git daemon`
1913arguments will further restrict the exports to those paths.
1914
1915You can also run `git daemon` as an inetd service; see the
1916linkgit:git-daemon[1] man page for details. (See especially the
1917examples section.)
1918
1919[[exporting-via-http]]
1920==== Exporting a git repository via HTTP
1921
1922The Git protocol gives better performance and reliability, but on a
1923host with a web server set up, HTTP exports may be simpler to set up.
1924
1925All you need to do is place the newly created bare Git repository in
1926a directory that is exported by the web server, and make some
1927adjustments to give web clients some extra information they need:
1928
1929-------------------------------------------------
1930$ mv proj.git /home/you/public_html/proj.git
1931$ cd proj.git
1932$ git --bare update-server-info
1933$ mv hooks/post-update.sample hooks/post-update
1934-------------------------------------------------
1935
1936(For an explanation of the last two lines, see
1937linkgit:git-update-server-info[1] and linkgit:githooks[5].)
1938
1939Advertise the URL of `proj.git`. Anybody else should then be able to
1940clone or pull from that URL, for example with a command line like:
1941
1942-------------------------------------------------
1943$ git clone http://yourserver.com/~you/proj.git
1944-------------------------------------------------
1945
1946(See also
1947link:howto/setup-git-server-over-http.html[setup-git-server-over-http]
1948for a slightly more sophisticated setup using WebDAV which also
1949allows pushing over HTTP.)
1950
1951[[pushing-changes-to-a-public-repository]]
1952==== Pushing changes to a public repository
1953
1954Note that the two techniques outlined above (exporting via
1955<<exporting-via-http,http>> or <<exporting-via-git,git>>) allow other
1956maintainers to fetch your latest changes, but they do not allow write
1957access, which you will need to update the public repository with the
1958latest changes created in your private repository.
1959
1960The simplest way to do this is using linkgit:git-push[1] and ssh; to
1961update the remote branch named `master` with the latest state of your
1962branch named `master`, run
1963
1964-------------------------------------------------
1965$ git push ssh://yourserver.com/~you/proj.git master:master
1966-------------------------------------------------
1967
1968or just
1969
1970-------------------------------------------------
1971$ git push ssh://yourserver.com/~you/proj.git master
1972-------------------------------------------------
1973
1974As with `git fetch`, `git push` will complain if this does not result in a
1975<<fast-forwards,fast-forward>>; see the following section for details on
1976handling this case.
1977
1978Note that the target of a `push` is normally a
1979<<def_bare_repository,bare>> repository. You can also push to a
1980repository that has a checked-out working tree, but a push to update the
1981currently checked-out branch is denied by default to prevent confusion.
1982See the description of the receive.denyCurrentBranch option
1983in linkgit:git-config[1] for details.
1984
1985As with `git fetch`, you may also set up configuration options to
1986save typing; so, for example:
1987
1988-------------------------------------------------
1989$ git remote add public-repo ssh://yourserver.com/~you/proj.git
1990-------------------------------------------------
1991
1992adds the following to `.git/config`:
1993
1994-------------------------------------------------
1995[remote "public-repo"]
1996 url = yourserver.com:proj.git
1997 fetch = +refs/heads/*:refs/remotes/example/*
1998-------------------------------------------------
1999
2000which lets you do the same push with just
2001
2002-------------------------------------------------
2003$ git push public-repo master
2004-------------------------------------------------
2005
2006See the explanations of the `remote.<name>.url`,
2007`branch.<name>.remote`, and `remote.<name>.push` options in
2008linkgit:git-config[1] for details.
2009
2010[[forcing-push]]
2011==== What to do when a push fails
2012
2013If a push would not result in a <<fast-forwards,fast-forward>> of the
2014remote branch, then it will fail with an error like:
2015
2016-------------------------------------------------
2017 ! [rejected] master -> master (non-fast-forward)
2018error: failed to push some refs to '...'
2019hint: Updates were rejected because the tip of your current branch is behind
2020hint: its remote counterpart. Integrate the remote changes (e.g.
2021hint: 'git pull ...') before pushing again.
2022hint: See the 'Note about fast-forwards' in 'git push --help' for details.
2023-------------------------------------------------
2024
2025This can happen, for example, if you:
2026
2027 - use `git reset --hard` to remove already-published commits, or
2028 - use `git commit --amend` to replace already-published commits
2029 (as in <<fixing-a-mistake-by-rewriting-history>>), or
2030 - use `git rebase` to rebase any already-published commits (as
2031 in <<using-git-rebase>>).
2032
2033You may force `git push` to perform the update anyway by preceding the
2034branch name with a plus sign:
2035
2036-------------------------------------------------
2037$ git push ssh://yourserver.com/~you/proj.git +master
2038-------------------------------------------------
2039
2040Note the addition of the `+` sign. Alternatively, you can use the
2041`-f` flag to force the remote update, as in:
2042
2043-------------------------------------------------
2044$ git push -f ssh://yourserver.com/~you/proj.git master
2045-------------------------------------------------
2046
2047Normally whenever a branch head in a public repository is modified, it
2048is modified to point to a descendant of the commit that it pointed to
2049before. By forcing a push in this situation, you break that convention.
2050(See <<problems-With-rewriting-history>>.)
2051
2052Nevertheless, this is a common practice for people that need a simple
2053way to publish a work-in-progress patch series, and it is an acceptable
2054compromise as long as you warn other developers that this is how you
2055intend to manage the branch.
2056
2057It's also possible for a push to fail in this way when other people have
2058the right to push to the same repository. In that case, the correct
2059solution is to retry the push after first updating your work: either by a
2060pull, or by a fetch followed by a rebase; see the
2061<<setting-up-a-shared-repository,next section>> and
2062linkgit:gitcvs-migration[7] for more.
2063
2064[[setting-up-a-shared-repository]]
2065==== Setting up a shared repository
2066
2067Another way to collaborate is by using a model similar to that
2068commonly used in CVS, where several developers with special rights
2069all push to and pull from a single shared repository. See
2070linkgit:gitcvs-migration[7] for instructions on how to
2071set this up.
2072
2073However, while there is nothing wrong with Git's support for shared
2074repositories, this mode of operation is not generally recommended,
2075simply because the mode of collaboration that Git supports--by
2076exchanging patches and pulling from public repositories--has so many
2077advantages over the central shared repository:
2078
2079 - Git's ability to quickly import and merge patches allows a
2080 single maintainer to process incoming changes even at very
2081 high rates. And when that becomes too much, `git pull` provides
2082 an easy way for that maintainer to delegate this job to other
2083 maintainers while still allowing optional review of incoming
2084 changes.
2085 - Since every developer's repository has the same complete copy
2086 of the project history, no repository is special, and it is
2087 trivial for another developer to take over maintenance of a
2088 project, either by mutual agreement, or because a maintainer
2089 becomes unresponsive or difficult to work with.
2090 - The lack of a central group of "committers" means there is
2091 less need for formal decisions about who is "in" and who is
2092 "out".
2093
2094[[setting-up-gitweb]]
2095==== Allowing web browsing of a repository
2096
2097The gitweb cgi script provides users an easy way to browse your
2098project's revisions, file contents and logs without having to install
2099Git. Features like RSS/Atom feeds and blame/annotation details may
2100optionally be enabled.
2101
2102The linkgit:git-instaweb[1] command provides a simple way to start
2103browsing the repository using gitweb. The default server when using
2104instaweb is lighttpd.
2105
2106See the file gitweb/INSTALL in the Git source tree and
2107linkgit:gitweb[1] for instructions on details setting up a permanent
2108installation with a CGI or Perl capable server.
2109
2110[[how-to-get-a-git-repository-with-minimal-history]]
2111=== How to get a Git repository with minimal history
2112
2113A <<def_shallow_clone,shallow clone>>, with its truncated
2114history, is useful when one is interested only in recent history
2115of a project and getting full history from the upstream is
2116expensive.
2117
2118A <<def_shallow_clone,shallow clone>> is created by specifying
2119the linkgit:git-clone[1] `--depth` switch. The depth can later be
2120changed with the linkgit:git-fetch[1] `--depth` switch, or full
2121history restored with `--unshallow`.
2122
2123Merging inside a <<def_shallow_clone,shallow clone>> will work as long
2124as a merge base is in the recent history.
2125Otherwise, it will be like merging unrelated histories and may
2126have to result in huge conflicts. This limitation may make such
2127a repository unsuitable to be used in merge based workflows.
2128
2129[[sharing-development-examples]]
2130=== Examples
2131
2132[[maintaining-topic-branches]]
2133==== Maintaining topic branches for a Linux subsystem maintainer
2134
2135This describes how Tony Luck uses Git in his role as maintainer of the
2136IA64 architecture for the Linux kernel.
2137
2138He uses two public branches:
2139
2140 - A "test" tree into which patches are initially placed so that they
2141 can get some exposure when integrated with other ongoing development.
2142 This tree is available to Andrew for pulling into -mm whenever he
2143 wants.
2144
2145 - A "release" tree into which tested patches are moved for final sanity
2146 checking, and as a vehicle to send them upstream to Linus (by sending
2147 him a "please pull" request.)
2148
2149He also uses a set of temporary branches ("topic branches"), each
2150containing a logical grouping of patches.
2151
2152To set this up, first create your work tree by cloning Linus's public
2153tree:
2154
2155-------------------------------------------------
2156$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work
2157$ cd work
2158-------------------------------------------------
2159
2160Linus's tree will be stored in the remote-tracking branch named origin/master,
2161and can be updated using linkgit:git-fetch[1]; you can track other
2162public trees using linkgit:git-remote[1] to set up a "remote" and
2163linkgit:git-fetch[1] to keep them up to date; see
2164<<repositories-and-branches>>.
2165
2166Now create the branches in which you are going to work; these start out
2167at the current tip of origin/master branch, and should be set up (using
2168the `--track` option to linkgit:git-branch[1]) to merge changes in from
2169Linus by default.
2170
2171-------------------------------------------------
2172$ git branch --track test origin/master
2173$ git branch --track release origin/master
2174-------------------------------------------------
2175
2176These can be easily kept up to date using linkgit:git-pull[1].
2177
2178-------------------------------------------------
2179$ git switch test && git pull
2180$ git switch release && git pull
2181-------------------------------------------------
2182
2183Important note! If you have any local changes in these branches, then
2184this merge will create a commit object in the history (with no local
2185changes Git will simply do a "fast-forward" merge). Many people dislike
2186the "noise" that this creates in the Linux history, so you should avoid
2187doing this capriciously in the `release` branch, as these noisy commits
2188will become part of the permanent history when you ask Linus to pull
2189from the release branch.
2190
2191A few configuration variables (see linkgit:git-config[1]) can
2192make it easy to push both branches to your public tree. (See
2193<<setting-up-a-public-repository>>.)
2194
2195-------------------------------------------------
2196$ cat >> .git/config <<EOF
2197[remote "mytree"]
2198 url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git
2199 push = release
2200 push = test
2201EOF
2202-------------------------------------------------
2203
2204Then you can push both the test and release trees using
2205linkgit:git-push[1]:
2206
2207-------------------------------------------------
2208$ git push mytree
2209-------------------------------------------------
2210
2211or push just one of the test and release branches using:
2212
2213-------------------------------------------------
2214$ git push mytree test
2215-------------------------------------------------
2216
2217or
2218
2219-------------------------------------------------
2220$ git push mytree release
2221-------------------------------------------------
2222
2223Now to apply some patches from the community. Think of a short
2224snappy name for a branch to hold this patch (or related group of
2225patches), and create a new branch from a recent stable tag of
2226Linus's branch. Picking a stable base for your branch will:
22271) help you: by avoiding inclusion of unrelated and perhaps lightly
2228tested changes
22292) help future bug hunters that use `git bisect` to find problems
2230
2231-------------------------------------------------
2232$ git switch -c speed-up-spinlocks v2.6.35
2233-------------------------------------------------
2234
2235Now you apply the patch(es), run some tests, and commit the change(s). If
2236the patch is a multi-part series, then you should apply each as a separate
2237commit to this branch.
2238
2239-------------------------------------------------
2240$ ... patch ... test ... commit [ ... patch ... test ... commit ]*
2241-------------------------------------------------
2242
2243When you are happy with the state of this change, you can merge it into the
2244"test" branch in preparation to make it public:
2245
2246-------------------------------------------------
2247$ git switch test && git merge speed-up-spinlocks
2248-------------------------------------------------
2249
2250It is unlikely that you would have any conflicts here ... but you might if you
2251spent a while on this step and had also pulled new versions from upstream.
2252
2253Sometime later when enough time has passed and testing done, you can pull the
2254same branch into the `release` tree ready to go upstream. This is where you
2255see the value of keeping each patch (or patch series) in its own branch. It
2256means that the patches can be moved into the `release` tree in any order.
2257
2258-------------------------------------------------
2259$ git switch release && git merge speed-up-spinlocks
2260-------------------------------------------------
2261
2262After a while, you will have a number of branches, and despite the
2263well chosen names you picked for each of them, you may forget what
2264they are for, or what status they are in. To get a reminder of what
2265changes are in a specific branch, use:
2266
2267-------------------------------------------------
2268$ git log linux..branchname | git shortlog
2269-------------------------------------------------
2270
2271To see whether it has already been merged into the test or release branches,
2272use:
2273
2274-------------------------------------------------
2275$ git log test..branchname
2276-------------------------------------------------
2277
2278or
2279
2280-------------------------------------------------
2281$ git log release..branchname
2282-------------------------------------------------
2283
2284(If this branch has not yet been merged, you will see some log entries.
2285If it has been merged, then there will be no output.)
2286
2287Once a patch completes the great cycle (moving from test to release,
2288then pulled by Linus, and finally coming back into your local
2289`origin/master` branch), the branch for this change is no longer needed.
2290You detect this when the output from:
2291
2292-------------------------------------------------
2293$ git log origin..branchname
2294-------------------------------------------------
2295
2296is empty. At this point the branch can be deleted:
2297
2298-------------------------------------------------
2299$ git branch -d branchname
2300-------------------------------------------------
2301
2302Some changes are so trivial that it is not necessary to create a separate
2303branch and then merge into each of the test and release branches. For
2304these changes, just apply directly to the `release` branch, and then
2305merge that into the `test` branch.
2306
2307After pushing your work to `mytree`, you can use
2308linkgit:git-request-pull[1] to prepare a "please pull" request message
2309to send to Linus:
2310
2311-------------------------------------------------
2312$ git push mytree
2313$ git request-pull origin mytree release
2314-------------------------------------------------
2315
2316Here are some of the scripts that simplify all this even further.
2317
2318-------------------------------------------------
2319==== update script ====
2320# Update a branch in my Git tree. If the branch to be updated
2321# is origin, then pull from kernel.org. Otherwise merge
2322# origin/master branch into test|release branch
2323
2324case "$1" in
2325test|release)
2326 git checkout $1 && git pull . origin
2327 ;;
2328origin)
2329 before=$(git rev-parse refs/remotes/origin/master)
2330 git fetch origin
2331 after=$(git rev-parse refs/remotes/origin/master)
2332 if [ $before != $after ]
2333 then
2334 git log $before..$after | git shortlog
2335 fi
2336 ;;
2337*)
2338 echo "usage: $0 origin|test|release" 1>&2
2339 exit 1
2340 ;;
2341esac
2342-------------------------------------------------
2343
2344-------------------------------------------------
2345==== merge script ====
2346# Merge a branch into either the test or release branch
2347
2348pname=$0
2349
2350usage()
2351{
2352 echo "usage: $pname branch test|release" 1>&2
2353 exit 1
2354}
2355
2356git show-ref -q --verify -- refs/heads/"$1" || {
2357 echo "Can't see branch <$1>" 1>&2
2358 usage
2359}
2360
2361case "$2" in
2362test|release)
2363 if [ $(git log $2..$1 | wc -c) -eq 0 ]
2364 then
2365 echo $1 already merged into $2 1>&2
2366 exit 1
2367 fi
2368 git checkout $2 && git pull . $1
2369 ;;
2370*)
2371 usage
2372 ;;
2373esac
2374-------------------------------------------------
2375
2376-------------------------------------------------
2377==== status script ====
2378# report on status of my ia64 Git tree
2379
2380gb=$(tput setab 2)
2381rb=$(tput setab 1)
2382restore=$(tput setab 9)
2383
2384if [ `git rev-list test..release | wc -c` -gt 0 ]
2385then
2386 echo $rb Warning: commits in release that are not in test $restore
2387 git log test..release
2388fi
2389
2390for branch in `git show-ref --heads | sed 's|^.*/||'`
2391do
2392 if [ $branch = test -o $branch = release ]
2393 then
2394 continue
2395 fi
2396
2397 echo -n $gb ======= $branch ====== $restore " "
2398 status=
2399 for ref in test release origin/master
2400 do
2401 if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
2402 then
2403 status=$status${ref:0:1}
2404 fi
2405 done
2406 case $status in
2407 trl)
2408 echo $rb Need to pull into test $restore
2409 ;;
2410 rl)
2411 echo "In test"
2412 ;;
2413 l)
2414 echo "Waiting for linus"
2415 ;;
2416 "")
2417 echo $rb All done $restore
2418 ;;
2419 *)
2420 echo $rb "<$status>" $restore
2421 ;;
2422 esac
2423 git log origin/master..$branch | git shortlog
2424done
2425-------------------------------------------------
2426
2427
2428[[cleaning-up-history]]
2429== Rewriting history and maintaining patch series
2430
2431Normally commits are only added to a project, never taken away or
2432replaced. Git is designed with this assumption, and violating it will
2433cause Git's merge machinery (for example) to do the wrong thing.
2434
2435However, there is a situation in which it can be useful to violate this
2436assumption.
2437
2438[[patch-series]]
2439=== Creating the perfect patch series
2440
2441Suppose you are a contributor to a large project, and you want to add a
2442complicated feature, and to present it to the other developers in a way
2443that makes it easy for them to read your changes, verify that they are
2444correct, and understand why you made each change.
2445
2446If you present all of your changes as a single patch (or commit), they
2447may find that it is too much to digest all at once.
2448
2449If you present them with the entire history of your work, complete with
2450mistakes, corrections, and dead ends, they may be overwhelmed.
2451
2452So the ideal is usually to produce a series of patches such that:
2453
2454 1. Each patch can be applied in order.
2455
2456 2. Each patch includes a single logical change, together with a
2457 message explaining the change.
2458
2459 3. No patch introduces a regression: after applying any initial
2460 part of the series, the resulting project still compiles and
2461 works, and has no bugs that it didn't have before.
2462
2463 4. The complete series produces the same end result as your own
2464 (probably much messier!) development process did.
2465
2466We will introduce some tools that can help you do this, explain how to
2467use them, and then explain some of the problems that can arise because
2468you are rewriting history.
2469
2470[[using-git-rebase]]
2471=== Keeping a patch series up to date using git rebase
2472
2473Suppose that you create a branch `mywork` on a remote-tracking branch
2474`origin`, and create some commits on top of it:
2475
2476-------------------------------------------------
2477$ git switch -c mywork origin
2478$ vi file.txt
2479$ git commit
2480$ vi otherfile.txt
2481$ git commit
2482...
2483-------------------------------------------------
2484
2485You have performed no merges into mywork, so it is just a simple linear
2486sequence of patches on top of `origin`:
2487
2488................................................
2489 o--o--O <-- origin
2490 \
2491 a--b--c <-- mywork
2492................................................
2493
2494Some more interesting work has been done in the upstream project, and
2495`origin` has advanced:
2496
2497................................................
2498 o--o--O--o--o--o <-- origin
2499 \
2500 a--b--c <-- mywork
2501................................................
2502
2503At this point, you could use `pull` to merge your changes back in;
2504the result would create a new merge commit, like this:
2505
2506................................................
2507 o--o--O--o--o--o <-- origin
2508 \ \
2509 a--b--c--m <-- mywork
2510................................................
2511
2512However, if you prefer to keep the history in mywork a simple series of
2513commits without any merges, you may instead choose to use
2514linkgit:git-rebase[1]:
2515
2516-------------------------------------------------
2517$ git switch mywork
2518$ git rebase origin
2519-------------------------------------------------
2520
2521This will remove each of your commits from mywork, temporarily saving
2522them as patches (in a directory named `.git/rebase-apply`), update mywork to
2523point at the latest version of origin, then apply each of the saved
2524patches to the new mywork. The result will look like:
2525
2526
2527................................................
2528 o--o--O--o--o--o <-- origin
2529 \
2530 a'--b'--c' <-- mywork
2531................................................
2532
2533In the process, it may discover conflicts. In that case it will stop
2534and allow you to fix the conflicts; after fixing conflicts, use `git add`
2535to update the index with those contents, and then, instead of
2536running `git commit`, just run
2537
2538-------------------------------------------------
2539$ git rebase --continue
2540-------------------------------------------------
2541
2542and Git will continue applying the rest of the patches.
2543
2544At any point you may use the `--abort` option to abort this process and
2545return mywork to the state it had before you started the rebase:
2546
2547-------------------------------------------------
2548$ git rebase --abort
2549-------------------------------------------------
2550
2551If you need to reorder or edit a number of commits in a branch, it may
2552be easier to use `git rebase -i`, which allows you to reorder and
2553squash commits, as well as marking them for individual editing during
2554the rebase. See <<interactive-rebase>> for details, and
2555<<reordering-patch-series>> for alternatives.
2556
2557[[rewriting-one-commit]]
2558=== Rewriting a single commit
2559
2560We saw in <<fixing-a-mistake-by-rewriting-history>> that you can replace the
2561most recent commit using
2562
2563-------------------------------------------------
2564$ git commit --amend
2565-------------------------------------------------
2566
2567which will replace the old commit by a new commit incorporating your
2568changes, giving you a chance to edit the old commit message first.
2569This is useful for fixing typos in your last commit, or for adjusting
2570the patch contents of a poorly staged commit.
2571
2572If you need to amend commits from deeper in your history, you can
2573use <<interactive-rebase,interactive rebase's `edit` instruction>>.
2574
2575[[reordering-patch-series]]
2576=== Reordering or selecting from a patch series
2577
2578Sometimes you want to edit a commit deeper in your history. One
2579approach is to use `git format-patch` to create a series of patches
2580and then reset the state to before the patches:
2581
2582-------------------------------------------------
2583$ git format-patch origin
2584$ git reset --hard origin
2585-------------------------------------------------
2586
2587Then modify, reorder, or eliminate patches as needed before applying
2588them again with linkgit:git-am[1]:
2589
2590-------------------------------------------------
2591$ git am *.patch
2592-------------------------------------------------
2593
2594[[interactive-rebase]]
2595=== Using interactive rebases
2596
2597You can also edit a patch series with an interactive rebase. This is
2598the same as <<reordering-patch-series,reordering a patch series using
2599`format-patch`>>, so use whichever interface you like best.
2600
2601Rebase your current HEAD on the last commit you want to retain as-is.
2602For example, if you want to reorder the last 5 commits, use:
2603
2604-------------------------------------------------
2605$ git rebase -i HEAD~5
2606-------------------------------------------------
2607
2608This will open your editor with a list of steps to be taken to perform
2609your rebase.
2610
2611-------------------------------------------------
2612pick deadbee The oneline of this commit
2613pick fa1afe1 The oneline of the next commit
2614...
2615
2616# Rebase c0ffeee..deadbee onto c0ffeee
2617#
2618# Commands:
2619# p, pick = use commit
2620# r, reword = use commit, but edit the commit message
2621# e, edit = use commit, but stop for amending
2622# s, squash = use commit, but meld into previous commit
2623# f, fixup = like "squash", but discard this commit's log message
2624# x, exec = run command (the rest of the line) using shell
2625#
2626# These lines can be re-ordered; they are executed from top to bottom.
2627#
2628# If you remove a line here THAT COMMIT WILL BE LOST.
2629#
2630# However, if you remove everything, the rebase will be aborted.
2631#
2632# Note that empty commits are commented out
2633-------------------------------------------------
2634
2635As explained in the comments, you can reorder commits, squash them
2636together, edit commit messages, etc. by editing the list. Once you
2637are satisfied, save the list and close your editor, and the rebase
2638will begin.
2639
2640The rebase will stop where `pick` has been replaced with `edit` or
2641when a step in the list fails to mechanically resolve conflicts and
2642needs your help. When you are done editing and/or resolving conflicts
2643you can continue with `git rebase --continue`. If you decide that
2644things are getting too hairy, you can always bail out with `git rebase
2645--abort`. Even after the rebase is complete, you can still recover
2646the original branch by using the <<reflogs,reflog>>.
2647
2648For a more detailed discussion of the procedure and additional tips,
2649see the "INTERACTIVE MODE" section of linkgit:git-rebase[1].
2650
2651[[patch-series-tools]]
2652=== Other tools
2653
2654There are numerous other tools, such as StGit, which exist for the
2655purpose of maintaining a patch series. These are outside of the scope of
2656this manual.
2657
2658[[problems-With-rewriting-history]]
2659=== Problems with rewriting history
2660
2661The primary problem with rewriting the history of a branch has to do
2662with merging. Suppose somebody fetches your branch and merges it into
2663their branch, with a result something like this:
2664
2665................................................
2666 o--o--O--o--o--o <-- origin
2667 \ \
2668 t--t--t--m <-- their branch:
2669................................................
2670
2671Then suppose you modify the last three commits:
2672
2673................................................
2674 o--o--o <-- new head of origin
2675 /
2676 o--o--O--o--o--o <-- old head of origin
2677................................................
2678
2679If we examined all this history together in one repository, it will
2680look like:
2681
2682................................................
2683 o--o--o <-- new head of origin
2684 /
2685 o--o--O--o--o--o <-- old head of origin
2686 \ \
2687 t--t--t--m <-- their branch:
2688................................................
2689
2690Git has no way of knowing that the new head is an updated version of
2691the old head; it treats this situation exactly the same as it would if
2692two developers had independently done the work on the old and new heads
2693in parallel. At this point, if someone attempts to merge the new head
2694in to their branch, Git will attempt to merge together the two (old and
2695new) lines of development, instead of trying to replace the old by the
2696new. The results are likely to be unexpected.
2697
2698You may still choose to publish branches whose history is rewritten,
2699and it may be useful for others to be able to fetch those branches in
2700order to examine or test them, but they should not attempt to pull such
2701branches into their own work.
2702
2703For true distributed development that supports proper merging,
2704published branches should never be rewritten.
2705
2706[[bisect-merges]]
2707=== Why bisecting merge commits can be harder than bisecting linear history
2708
2709The linkgit:git-bisect[1] command correctly handles history that
2710includes merge commits. However, when the commit that it finds is a
2711merge commit, the user may need to work harder than usual to figure out
2712why that commit introduced a problem.
2713
2714Imagine this history:
2715
2716................................................
2717 ---Z---o---X---...---o---A---C---D
2718 \ /
2719 o---o---Y---...---o---B
2720................................................
2721
2722Suppose that on the upper line of development, the meaning of one
2723of the functions that exists at Z is changed at commit X. The
2724commits from Z leading to A change both the function's
2725implementation and all calling sites that exist at Z, as well
2726as new calling sites they add, to be consistent. There is no
2727bug at A.
2728
2729Suppose that in the meantime on the lower line of development somebody
2730adds a new calling site for that function at commit Y. The
2731commits from Z leading to B all assume the old semantics of that
2732function and the callers and the callee are consistent with each
2733other. There is no bug at B, either.
2734
2735Suppose further that the two development lines merge cleanly at C,
2736so no conflict resolution is required.
2737
2738Nevertheless, the code at C is broken, because the callers added
2739on the lower line of development have not been converted to the new
2740semantics introduced on the upper line of development. So if all
2741you know is that D is bad, that Z is good, and that
2742linkgit:git-bisect[1] identifies C as the culprit, how will you
2743figure out that the problem is due to this change in semantics?
2744
2745When the result of a `git bisect` is a non-merge commit, you should
2746normally be able to discover the problem by examining just that commit.
2747Developers can make this easy by breaking their changes into small
2748self-contained commits. That won't help in the case above, however,
2749because the problem isn't obvious from examination of any single
2750commit; instead, a global view of the development is required. To
2751make matters worse, the change in semantics in the problematic
2752function may be just one small part of the changes in the upper
2753line of development.
2754
2755On the other hand, if instead of merging at C you had rebased the
2756history between Z to B on top of A, you would have gotten this
2757linear history:
2758
2759................................................................
2760 ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
2761................................................................
2762
2763Bisecting between Z and D* would hit a single culprit commit Y*,
2764and understanding why Y* was broken would probably be easier.
2765
2766Partly for this reason, many experienced Git users, even when
2767working on an otherwise merge-heavy project, keep the history
2768linear by rebasing against the latest upstream version before
2769publishing.
2770
2771[[advanced-branch-management]]
2772== Advanced branch management
2773
2774[[fetching-individual-branches]]
2775=== Fetching individual branches
2776
2777Instead of using linkgit:git-remote[1], you can also choose just
2778to update one branch at a time, and to store it locally under an
2779arbitrary name:
2780
2781-------------------------------------------------
2782$ git fetch origin todo:my-todo-work
2783-------------------------------------------------
2784
2785The first argument, `origin`, just tells Git to fetch from the
2786repository you originally cloned from. The second argument tells Git
2787to fetch the branch named `todo` from the remote repository, and to
2788store it locally under the name `refs/heads/my-todo-work`.
2789
2790You can also fetch branches from other repositories; so
2791
2792-------------------------------------------------
2793$ git fetch git://example.com/proj.git master:example-master
2794-------------------------------------------------
2795
2796will create a new branch named `example-master` and store in it the
2797branch named `master` from the repository at the given URL. If you
2798already have a branch named example-master, it will attempt to
2799<<fast-forwards,fast-forward>> to the commit given by example.com's
2800master branch. In more detail:
2801
2802[[fetch-fast-forwards]]
2803=== git fetch and fast-forwards
2804
2805In the previous example, when updating an existing branch, `git fetch`
2806checks to make sure that the most recent commit on the remote
2807branch is a descendant of the most recent commit on your copy of the
2808branch before updating your copy of the branch to point at the new
2809commit. Git calls this process a <<fast-forwards,fast-forward>>.
2810
2811A fast-forward looks something like this:
2812
2813................................................
2814 o--o--o--o <-- old head of the branch
2815 \
2816 o--o--o <-- new head of the branch
2817................................................
2818
2819
2820In some cases it is possible that the new head will *not* actually be
2821a descendant of the old head. For example, the developer may have
2822realized a serious mistake was made and decided to backtrack,
2823resulting in a situation like:
2824
2825................................................
2826 o--o--o--o--a--b <-- old head of the branch
2827 \
2828 o--o--o <-- new head of the branch
2829................................................
2830
2831In this case, `git fetch` will fail, and print out a warning.
2832
2833In that case, you can still force Git to update to the new head, as
2834described in the following section. However, note that in the
2835situation above this may mean losing the commits labeled `a` and `b`,
2836unless you've already created a reference of your own pointing to
2837them.
2838
2839[[forcing-fetch]]
2840=== Forcing git fetch to do non-fast-forward updates
2841
2842If git fetch fails because the new head of a branch is not a
2843descendant of the old head, you may force the update with:
2844
2845-------------------------------------------------
2846$ git fetch git://example.com/proj.git +master:refs/remotes/example/master
2847-------------------------------------------------
2848
2849Note the addition of the `+` sign. Alternatively, you can use the `-f`
2850flag to force updates of all the fetched branches, as in:
2851
2852-------------------------------------------------
2853$ git fetch -f origin
2854-------------------------------------------------
2855
2856Be aware that commits that the old version of example/master pointed at
2857may be lost, as we saw in the previous section.
2858
2859[[remote-branch-configuration]]
2860=== Configuring remote-tracking branches
2861
2862We saw above that `origin` is just a shortcut to refer to the
2863repository that you originally cloned from. This information is
2864stored in Git configuration variables, which you can see using
2865linkgit:git-config[1]:
2866
2867-------------------------------------------------
2868$ git config -l
2869core.repositoryformatversion=0
2870core.filemode=true
2871core.logallrefupdates=true
2872remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
2873remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
2874branch.master.remote=origin
2875branch.master.merge=refs/heads/master
2876-------------------------------------------------
2877
2878If there are other repositories that you also use frequently, you can
2879create similar configuration options to save typing; for example,
2880
2881-------------------------------------------------
2882$ git remote add example git://example.com/proj.git
2883-------------------------------------------------
2884
2885adds the following to `.git/config`:
2886
2887-------------------------------------------------
2888[remote "example"]
2889 url = git://example.com/proj.git
2890 fetch = +refs/heads/*:refs/remotes/example/*
2891-------------------------------------------------
2892
2893Also note that the above configuration can be performed by directly
2894editing the file `.git/config` instead of using linkgit:git-remote[1].
2895
2896After configuring the remote, the following three commands will do the
2897same thing:
2898
2899-------------------------------------------------
2900$ git fetch git://example.com/proj.git +refs/heads/*:refs/remotes/example/*
2901$ git fetch example +refs/heads/*:refs/remotes/example/*
2902$ git fetch example
2903-------------------------------------------------
2904
2905See linkgit:git-config[1] for more details on the configuration
2906options mentioned above and linkgit:git-fetch[1] for more details on
2907the refspec syntax.
2908
2909
2910[[git-concepts]]
2911== Git concepts
2912
2913Git is built on a small number of simple but powerful ideas. While it
2914is possible to get things done without understanding them, you will find
2915Git much more intuitive if you do.
2916
2917We start with the most important, the <<def_object_database,object
2918database>> and the <<def_index,index>>.
2919
2920[[the-object-database]]
2921=== The Object Database
2922
2923
2924We already saw in <<understanding-commits>> that all commits are stored
2925under a 40-digit "object name". In fact, all the information needed to
2926represent the history of a project is stored in objects with such names.
2927In each case the name is calculated by taking the SHA-1 hash of the
2928contents of the object. The SHA-1 hash is a cryptographic hash function.
2929What that means to us is that it is impossible to find two different
2930objects with the same name. This has a number of advantages; among
2931others:
2932
2933- Git can quickly determine whether two objects are identical or not,
2934 just by comparing names.
2935- Since object names are computed the same way in every repository, the
2936 same content stored in two repositories will always be stored under
2937 the same name.
2938- Git can detect errors when it reads an object, by checking that the
2939 object's name is still the SHA-1 hash of its contents.
2940
2941(See <<object-details>> for the details of the object formatting and
2942SHA-1 calculation.)
2943
2944There are four different types of objects: "blob", "tree", "commit", and
2945"tag".
2946
2947- A <<def_blob_object,"blob" object>> is used to store file data.
2948- A <<def_tree_object,"tree" object>> ties one or more
2949 "blob" objects into a directory structure. In addition, a tree object
2950 can refer to other tree objects, thus creating a directory hierarchy.
2951- A <<def_commit_object,"commit" object>> ties such directory hierarchies
2952 together into a <<def_DAG,directed acyclic graph>> of revisions--each
2953 commit contains the object name of exactly one tree designating the
2954 directory hierarchy at the time of the commit. In addition, a commit
2955 refers to "parent" commit objects that describe the history of how we
2956 arrived at that directory hierarchy.
2957- A <<def_tag_object,"tag" object>> symbolically identifies and can be
2958 used to sign other objects. It contains the object name and type of
2959 another object, a symbolic name (of course!) and, optionally, a
2960 signature.
2961
2962The object types in some more detail:
2963
2964[[commit-object]]
2965==== Commit Object
2966
2967The "commit" object links a physical state of a tree with a description
2968of how we got there and why. Use the `--pretty=raw` option to
2969linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
2970commit:
2971
2972------------------------------------------------
2973$ git show -s --pretty=raw 2be7fcb476
2974commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
2975tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
2976parent 257a84d9d02e90447b149af58b271c19405edb6a
2977author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
2978committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
2979
2980 Fix misspelling of 'suppress' in docs
2981
2982 Signed-off-by: Junio C Hamano <gitster@pobox.com>
2983------------------------------------------------
2984
2985As you can see, a commit is defined by:
2986
2987- a tree: The SHA-1 name of a tree object (as defined below), representing
2988 the contents of a directory at a certain point in time.
2989- parent(s): The SHA-1 name(s) of some number of commits which represent the
2990 immediately previous step(s) in the history of the project. The
2991 example above has one parent; merge commits may have more than
2992 one. A commit with no parents is called a "root" commit, and
2993 represents the initial revision of a project. Each project must have
2994 at least one root. A project can also have multiple roots, though
2995 that isn't common (or necessarily a good idea).
2996- an author: The name of the person responsible for this change, together
2997 with its date.
2998- a committer: The name of the person who actually created the commit,
2999 with the date it was done. This may be different from the author, for
3000 example, if the author was someone who wrote a patch and emailed it
3001 to the person who used it to create the commit.
3002- a comment describing this commit.
3003
3004Note that a commit does not itself contain any information about what
3005actually changed; all changes are calculated by comparing the contents
3006of the tree referred to by this commit with the trees associated with
3007its parents. In particular, Git does not attempt to record file renames
3008explicitly, though it can identify cases where the existence of the same
3009file data at changing paths suggests a rename. (See, for example, the
3010`-M` option to linkgit:git-diff[1]).
3011
3012A commit is usually created by linkgit:git-commit[1], which creates a
3013commit whose parent is normally the current HEAD, and whose tree is
3014taken from the content currently stored in the index.
3015
3016[[tree-object]]
3017==== Tree Object
3018
3019The ever-versatile linkgit:git-show[1] command can also be used to
3020examine tree objects, but linkgit:git-ls-tree[1] will give you more
3021details:
3022
3023------------------------------------------------
3024$ git ls-tree fb3a8bdd0ce
3025100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
3026100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
3027100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
3028040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
3029100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
3030100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
3031100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
3032100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
3033...
3034------------------------------------------------
3035
3036As you can see, a tree object contains a list of entries, each with a
3037mode, object type, SHA-1 name, and name, sorted by name. It represents
3038the contents of a single directory tree.
3039
3040The object type may be a blob, representing the contents of a file, or
3041another tree, representing the contents of a subdirectory. Since trees
3042and blobs, like all other objects, are named by the SHA-1 hash of their
3043contents, two trees have the same SHA-1 name if and only if their
3044contents (including, recursively, the contents of all subdirectories)
3045are identical. This allows Git to quickly determine the differences
3046between two related tree objects, since it can ignore any entries with
3047identical object names.
3048
3049(Note: in the presence of submodules, trees may also have commits as
3050entries. See <<submodules>> for documentation.)
3051
3052Note that the files all have mode 644 or 755: Git actually only pays
3053attention to the executable bit.
3054
3055[[blob-object]]
3056==== Blob Object
3057
3058You can use linkgit:git-show[1] to examine the contents of a blob; take,
3059for example, the blob in the entry for `COPYING` from the tree above:
3060
3061------------------------------------------------
3062$ git show 6ff87c4664
3063
3064 Note that the only valid version of the GPL as far as this project
3065 is concerned is _this_ particular version of the license (ie v2, not
3066 v2.2 or v3.x or whatever), unless explicitly otherwise stated.
3067...
3068------------------------------------------------
3069
3070A "blob" object is nothing but a binary blob of data. It doesn't refer
3071to anything else or have attributes of any kind.
3072
3073Since the blob is entirely defined by its data, if two files in a
3074directory tree (or in multiple different versions of the repository)
3075have the same contents, they will share the same blob object. The object
3076is totally independent of its location in the directory tree, and
3077renaming a file does not change the object that file is associated with.
3078
3079Note that any tree or blob object can be examined using
3080linkgit:git-show[1] with the <revision>:<path> syntax. This can
3081sometimes be useful for browsing the contents of a tree that is not
3082currently checked out.
3083
3084[[trust]]
3085==== Trust
3086
3087If you receive the SHA-1 name of a blob from one source, and its contents
3088from another (possibly untrusted) source, you can still trust that those
3089contents are correct as long as the SHA-1 name agrees. This is because
3090the SHA-1 is designed so that it is infeasible to find different contents
3091that produce the same hash.
3092
3093Similarly, you need only trust the SHA-1 name of a top-level tree object
3094to trust the contents of the entire directory that it refers to, and if
3095you receive the SHA-1 name of a commit from a trusted source, then you
3096can easily verify the entire history of commits reachable through
3097parents of that commit, and all of those contents of the trees referred
3098to by those commits.
3099
3100So to introduce some real trust in the system, the only thing you need
3101to do is to digitally sign just 'one' special note, which includes the
3102name of a top-level commit. Your digital signature shows others
3103that you trust that commit, and the immutability of the history of
3104commits tells others that they can trust the whole history.
3105
3106In other words, you can easily validate a whole archive by just
3107sending out a single email that tells the people the name (SHA-1 hash)
3108of the top commit, and digitally sign that email using something
3109like GPG/PGP.
3110
3111To assist in this, Git also provides the tag object...
3112
3113[[tag-object]]
3114==== Tag Object
3115
3116A tag object contains an object, object type, tag name, the name of the
3117person ("tagger") who created the tag, and a message, which may contain
3118a signature, as can be seen using linkgit:git-cat-file[1]:
3119
3120------------------------------------------------
3121$ git cat-file tag v1.5.0
3122object 437b1b20df4b356c9342dac8d38849f24ef44f27
3123type commit
3124tag v1.5.0
3125tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000
3126
3127GIT 1.5.0
3128-----BEGIN PGP SIGNATURE-----
3129Version: GnuPG v1.4.6 (GNU/Linux)
3130
3131iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui
3132nLE/L9aUXdWeTFPron96DLA=
3133=2E+0
3134-----END PGP SIGNATURE-----
3135------------------------------------------------
3136
3137See the linkgit:git-tag[1] command to learn how to create and verify tag
3138objects. (Note that linkgit:git-tag[1] can also be used to create
3139"lightweight tags", which are not tag objects at all, but just simple
3140references whose names begin with `refs/tags/`).
3141
3142[[pack-files]]
3143==== How Git stores objects efficiently: pack files
3144
3145Newly created objects are initially created in a file named after the
3146object's SHA-1 hash (stored in `.git/objects`).
3147
3148Unfortunately this system becomes inefficient once a project has a
3149lot of objects. Try this on an old project:
3150
3151------------------------------------------------
3152$ git count-objects
31536930 objects, 47620 kilobytes
3154------------------------------------------------
3155
3156The first number is the number of objects which are kept in
3157individual files. The second is the amount of space taken up by
3158those "loose" objects.
3159
3160You can save space and make Git faster by moving these loose objects in
3161to a "pack file", which stores a group of objects in an efficient
3162compressed format; the details of how pack files are formatted can be
3163found in linkgit:gitformat-pack[5].
3164
3165To put the loose objects into a pack, just run git repack:
3166
3167------------------------------------------------
3168$ git repack
3169Counting objects: 6020, done.
3170Delta compression using up to 4 threads.
3171Compressing objects: 100% (6020/6020), done.
3172Writing objects: 100% (6020/6020), done.
3173Total 6020 (delta 4070), reused 0 (delta 0)
3174------------------------------------------------
3175
3176This creates a single "pack file" in .git/objects/pack/
3177containing all currently unpacked objects. You can then run
3178
3179------------------------------------------------
3180$ git prune
3181------------------------------------------------
3182
3183to remove any of the "loose" objects that are now contained in the
3184pack. This will also remove any unreferenced objects (which may be
3185created when, for example, you use `git reset` to remove a commit).
3186You can verify that the loose objects are gone by looking at the
3187`.git/objects` directory or by running
3188
3189------------------------------------------------
3190$ git count-objects
31910 objects, 0 kilobytes
3192------------------------------------------------
3193
3194Although the object files are gone, any commands that refer to those
3195objects will work exactly as they did before.
3196
3197The linkgit:git-gc[1] command performs packing, pruning, and more for
3198you, so is normally the only high-level command you need.
3199
3200[[dangling-objects]]
3201==== Dangling objects
3202
3203The linkgit:git-fsck[1] command will sometimes complain about dangling
3204objects. They are not a problem.
3205
3206The most common cause of dangling objects is that you've rebased a
3207branch, or you have pulled from somebody else who rebased a branch--see
3208<<cleaning-up-history>>. In that case, the old head of the original
3209branch still exists, as does everything it pointed to. The branch
3210pointer itself just doesn't, since you replaced it with another one.
3211
3212There are also other situations that cause dangling objects. For
3213example, a "dangling blob" may arise because you did a `git add` of a
3214file, but then, before you actually committed it and made it part of the
3215bigger picture, you changed something else in that file and committed
3216that *updated* thing--the old state that you added originally ends up
3217not being pointed to by any commit or tree, so it's now a dangling blob
3218object.
3219
3220Similarly, when the "ort" merge strategy runs, and finds that
3221there are criss-cross merges and thus more than one merge base (which is
3222fairly unusual, but it does happen), it will generate one temporary
3223midway tree (or possibly even more, if you had lots of criss-crossing
3224merges and more than two merge bases) as a temporary internal merge
3225base, and again, those are real objects, but the end result will not end
3226up pointing to them, so they end up "dangling" in your repository.
3227
3228Generally, dangling objects aren't anything to worry about. They can
3229even be very useful: if you screw something up, the dangling objects can
3230be how you recover your old tree (say, you did a rebase, and realized
3231that you really didn't want to--you can look at what dangling objects
3232you have, and decide to reset your head to some old dangling state).
3233
3234For commits, you can just use:
3235
3236------------------------------------------------
3237$ gitk <dangling-commit-sha-goes-here> --not --all
3238------------------------------------------------
3239
3240This asks for all the history reachable from the given commit but not
3241from any branch, tag, or other reference. If you decide it's something
3242you want, you can always create a new reference to it, e.g.,
3243
3244------------------------------------------------
3245$ git branch recovered-branch <dangling-commit-sha-goes-here>
3246------------------------------------------------
3247
3248For blobs and trees, you can't do the same, but you can still examine
3249them. You can just do
3250
3251------------------------------------------------
3252$ git show <dangling-blob/tree-sha-goes-here>
3253------------------------------------------------
3254
3255to show what the contents of the blob were (or, for a tree, basically
3256what the `ls` for that directory was), and that may give you some idea
3257of what the operation was that left that dangling object.
3258
3259Usually, dangling blobs and trees aren't very interesting. They're
3260almost always the result of either being a half-way mergebase (the blob
3261will often even have the conflict markers from a merge in it, if you
3262have had conflicting merges that you fixed up by hand), or simply
3263because you interrupted a `git fetch` with ^C or something like that,
3264leaving _some_ of the new objects in the object database, but just
3265dangling and useless.
3266
3267Anyway, once you are sure that you're not interested in any dangling
3268state, you can just prune all unreachable objects:
3269
3270------------------------------------------------
3271$ git prune
3272------------------------------------------------
3273
3274and they'll be gone. (You should only run `git prune` on a quiescent
3275repository--it's kind of like doing a filesystem fsck recovery: you
3276don't want to do that while the filesystem is mounted.
3277`git prune` is designed not to cause any harm in such cases of concurrent
3278accesses to a repository but you might receive confusing or scary messages.)
3279
3280[[recovering-from-repository-corruption]]
3281==== Recovering from repository corruption
3282
3283By design, Git treats data trusted to it with caution. However, even in
3284the absence of bugs in Git itself, it is still possible that hardware or
3285operating system errors could corrupt data.
3286
3287The first defense against such problems is backups. You can back up a
3288Git directory using clone, or just using cp, tar, or any other backup
3289mechanism.
3290
3291As a last resort, you can search for the corrupted objects and attempt
3292to replace them by hand. Back up your repository before attempting this
3293in case you corrupt things even more in the process.
3294
3295We'll assume that the problem is a single missing or corrupted blob,
3296which is sometimes a solvable problem. (Recovering missing trees and
3297especially commits is *much* harder).
3298
3299Before starting, verify that there is corruption, and figure out where
3300it is with linkgit:git-fsck[1]; this may be time-consuming.
3301
3302Assume the output looks like this:
3303
3304------------------------------------------------
3305$ git fsck --full --no-dangling
3306broken link from tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
3307 to blob 4b9458b3786228369c63936db65827de3cc06200
3308missing blob 4b9458b3786228369c63936db65827de3cc06200
3309------------------------------------------------
3310
3311Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6
3312points to it. If you could find just one copy of that missing blob
3313object, possibly in some other repository, you could move it into
3314`.git/objects/4b/9458b3...` and be done. Suppose you can't. You can
3315still examine the tree that pointed to it with linkgit:git-ls-tree[1],
3316which might output something like:
3317
3318------------------------------------------------
3319$ git ls-tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
3320100644 blob 8d14531846b95bfa3564b58ccfb7913a034323b8 .gitignore
3321100644 blob ebf9bf84da0aab5ed944264a5db2a65fe3a3e883 .mailmap
3322100644 blob ca442d313d86dc67e0a2e5d584b465bd382cbf5c COPYING
3323...
3324100644 blob 4b9458b3786228369c63936db65827de3cc06200 myfile
3325...
3326------------------------------------------------
3327
3328So now you know that the missing blob was the data for a file named
3329`myfile`. And chances are you can also identify the directory--let's
3330say it's in `somedirectory`. If you're lucky the missing copy might be
3331the same as the copy you have checked out in your working tree at
3332`somedirectory/myfile`; you can test whether that's right with
3333linkgit:git-hash-object[1]:
3334
3335------------------------------------------------
3336$ git hash-object -w somedirectory/myfile
3337------------------------------------------------
3338
3339which will create and store a blob object with the contents of
3340somedirectory/myfile, and output the SHA-1 of that object. if you're
3341extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in
3342which case you've guessed right, and the corruption is fixed!
3343
3344Otherwise, you need more information. How do you tell which version of
3345the file has been lost?
3346
3347The easiest way to do this is with:
3348
3349------------------------------------------------
3350$ git log --raw --all --full-history -- somedirectory/myfile
3351------------------------------------------------
3352
3353Because you're asking for raw output, you'll now get something like
3354
3355------------------------------------------------
3356commit abc
3357Author:
3358Date:
3359...
3360:100644 100644 4b9458b newsha M somedirectory/myfile
3361
3362
3363commit xyz
3364Author:
3365Date:
3366
3367...
3368:100644 100644 oldsha 4b9458b M somedirectory/myfile
3369------------------------------------------------
3370
3371This tells you that the immediately following version of the file was
3372"newsha", and that the immediately preceding version was "oldsha".
3373You also know the commit messages that went with the change from oldsha
3374to 4b9458b and with the change from 4b9458b to newsha.
3375
3376If you've been committing small enough changes, you may now have a good
3377shot at reconstructing the contents of the in-between state 4b9458b.
3378
3379If you can do that, you can now recreate the missing object with
3380
3381------------------------------------------------
3382$ git hash-object -w <recreated-file>
3383------------------------------------------------
3384
3385and your repository is good again!
3386
3387(Btw, you could have ignored the `fsck`, and started with doing a
3388
3389------------------------------------------------
3390$ git log --raw --all
3391------------------------------------------------
3392
3393and just looked for the sha of the missing object (4b9458b) in that
3394whole thing. It's up to you--Git does *have* a lot of information, it is
3395just missing one particular blob version.
3396
3397[[the-index]]
3398=== The index
3399
3400The index is a binary file (generally kept in `.git/index`) containing a
3401sorted list of path names, each with permissions and the SHA-1 of a blob
3402object; linkgit:git-ls-files[1] can show you the contents of the index:
3403
3404-------------------------------------------------
3405$ git ls-files --stage
3406100644 63c918c667fa005ff12ad89437f2fdc80926e21c 0 .gitignore
3407100644 5529b198e8d14decbe4ad99db3f7fb632de0439d 0 .mailmap
3408100644 6ff87c4664981e4397625791c8ea3bbb5f2279a3 0 COPYING
3409100644 a37b2152bd26be2c2289e1f57a292534a51a93c7 0 Documentation/.gitignore
3410100644 fbefe9a45b00a54b58d94d06eca48b03d40a50e0 0 Documentation/Makefile
3411...
3412100644 2511aef8d89ab52be5ec6a5e46236b4b6bcd07ea 0 xdiff/xtypes.h
3413100644 2ade97b2574a9f77e7ae4002a4e07a6a38e46d07 0 xdiff/xutils.c
3414100644 d5de8292e05e7c36c4b68857c1cf9855e3d2f70a 0 xdiff/xutils.h
3415-------------------------------------------------
3416
3417Note that in older documentation you may see the index called the
3418"current directory cache" or just the "cache". It has three important
3419properties:
3420
34211. The index contains all the information necessary to generate a single
3422(uniquely determined) tree object.
3423+
3424For example, running linkgit:git-commit[1] generates this tree object
3425from the index, stores it in the object database, and uses it as the
3426tree object associated with the new commit.
3427
34282. The index enables fast comparisons between the tree object it defines
3429and the working tree.
3430+
3431It does this by storing some additional data for each entry (such as
3432the last modified time). This data is not displayed above, and is not
3433stored in the created tree object, but it can be used to determine
3434quickly which files in the working directory differ from what was
3435stored in the index, and thus save Git from having to read all of the
3436data from such files to look for changes.
3437
34383. It can efficiently represent information about merge conflicts
3439between different tree objects, allowing each pathname to be
3440associated with sufficient information about the trees involved that
3441you can create a three-way merge between them.
3442+
3443We saw in <<conflict-resolution>> that during a merge the index can
3444store multiple versions of a single file (called "stages"). The third
3445column in the linkgit:git-ls-files[1] output above is the stage
3446number, and will take on values other than 0 for files with merge
3447conflicts.
3448
3449The index is thus a sort of temporary staging area, which is filled with
3450a tree which you are in the process of working on.
3451
3452If you blow the index away entirely, you generally haven't lost any
3453information as long as you have the name of the tree that it described.
3454
3455[[submodules]]
3456== Submodules
3457
3458Large projects are often composed of smaller, self-contained modules. For
3459example, an embedded Linux distribution's source tree would include every
3460piece of software in the distribution with some local modifications; a movie
3461player might need to build against a specific, known-working version of a
3462decompression library; several independent programs might all share the same
3463build scripts.
3464
3465With centralized revision control systems this is often accomplished by
3466including every module in one single repository. Developers can check out
3467all modules or only the modules they need to work with. They can even modify
3468files across several modules in a single commit while moving things around
3469or updating APIs and translations.
3470
3471Git does not allow partial checkouts, so duplicating this approach in Git
3472would force developers to keep a local copy of modules they are not
3473interested in touching. Commits in an enormous checkout would be slower
3474than you'd expect as Git would have to scan every directory for changes.
3475If modules have a lot of local history, clones would take forever.
3476
3477On the plus side, distributed revision control systems can much better
3478integrate with external sources. In a centralized model, a single arbitrary
3479snapshot of the external project is exported from its own revision control
3480and then imported into the local revision control on a vendor branch. All
3481the history is hidden. With distributed revision control you can clone the
3482entire external history and much more easily follow development and re-merge
3483local changes.
3484
3485Git's submodule support allows a repository to contain, as a subdirectory, a
3486checkout of an external project. Submodules maintain their own identity;
3487the submodule support just stores the submodule repository location and
3488commit ID, so other developers who clone the containing project
3489("superproject") can easily clone all the submodules at the same revision.
3490Partial checkouts of the superproject are possible: you can tell Git to
3491clone none, some or all of the submodules.
3492
3493The linkgit:git-submodule[1] command is available since Git 1.5.3. Users
3494with Git 1.5.2 can look up the submodule commits in the repository and
3495manually check them out; earlier versions won't recognize the submodules at
3496all.
3497
3498To see how submodule support works, create four example
3499repositories that can be used later as a submodule:
3500
3501-------------------------------------------------
3502$ mkdir ~/git
3503$ cd ~/git
3504$ for i in a b c d
3505do
3506 mkdir $i
3507 cd $i
3508 git init
3509 echo "module $i" > $i.txt
3510 git add $i.txt
3511 git commit -m "Initial commit, submodule $i"
3512 cd ..
3513done
3514-------------------------------------------------
3515
3516Now create the superproject and add all the submodules:
3517
3518-------------------------------------------------
3519$ mkdir super
3520$ cd super
3521$ git init
3522$ for i in a b c d
3523do
3524 git submodule add ~/git/$i $i
3525done
3526-------------------------------------------------
3527
3528NOTE: Do not use local URLs here if you plan to publish your superproject!
3529
3530See what files `git submodule` created:
3531
3532-------------------------------------------------
3533$ ls -a
3534. .. .git .gitmodules a b c d
3535-------------------------------------------------
3536
3537The `git submodule add <repo> <path>` command does a couple of things:
3538
3539- It clones the submodule from `<repo>` to the given `<path>` under the
3540 current directory and by default checks out the master branch.
3541- It adds the submodule's clone path to the linkgit:gitmodules[5] file and
3542 adds this file to the index, ready to be committed.
3543- It adds the submodule's current commit ID to the index, ready to be
3544 committed.
3545
3546Commit the superproject:
3547
3548-------------------------------------------------
3549$ git commit -m "Add submodules a, b, c and d."
3550-------------------------------------------------
3551
3552Now clone the superproject:
3553
3554-------------------------------------------------
3555$ cd ..
3556$ git clone super cloned
3557$ cd cloned
3558-------------------------------------------------
3559
3560The submodule directories are there, but they're empty:
3561
3562-------------------------------------------------
3563$ ls -a a
3564. ..
3565$ git submodule status
3566-d266b9873ad50488163457f025db7cdd9683d88b a
3567-e81d457da15309b4fef4249aba9b50187999670d b
3568-c1536a972b9affea0f16e0680ba87332dc059146 c
3569-d96249ff5d57de5de093e6baff9e0aafa5276a74 d
3570-------------------------------------------------
3571
3572NOTE: The commit object names shown above would be different for you, but they
3573should match the HEAD commit object names of your repositories. You can check
3574it by running `git ls-remote ../a`.
3575
3576Pulling down the submodules is a two-step process. First run `git submodule
3577init` to add the submodule repository URLs to `.git/config`:
3578
3579-------------------------------------------------
3580$ git submodule init
3581-------------------------------------------------
3582
3583Now use `git submodule update` to clone the repositories and check out the
3584commits specified in the superproject:
3585
3586-------------------------------------------------
3587$ git submodule update
3588$ cd a
3589$ ls -a
3590. .. .git a.txt
3591-------------------------------------------------
3592
3593One major difference between `git submodule update` and `git submodule add` is
3594that `git submodule update` checks out a specific commit, rather than the tip
3595of a branch. It's like checking out a tag: the head is detached, so you're not
3596working on a branch.
3597
3598-------------------------------------------------
3599$ git branch
3600* (detached from d266b98)
3601 master
3602-------------------------------------------------
3603
3604If you want to make a change within a submodule and you have a detached head,
3605then you should create or checkout a branch, make your changes, publish the
3606change within the submodule, and then update the superproject to reference the
3607new commit:
3608
3609-------------------------------------------------
3610$ git switch master
3611-------------------------------------------------
3612
3613or
3614
3615-------------------------------------------------
3616$ git switch -c fix-up
3617-------------------------------------------------
3618
3619then
3620
3621-------------------------------------------------
3622$ echo "adding a line again" >> a.txt
3623$ git commit -a -m "Updated the submodule from within the superproject."
3624$ git push
3625$ cd ..
3626$ git diff
3627diff --git a/a b/a
3628index d266b98..261dfac 160000
3629--- a/a
3630+++ b/a
3631@@ -1 +1 @@
3632-Subproject commit d266b9873ad50488163457f025db7cdd9683d88b
3633+Subproject commit 261dfac35cb99d380eb966e102c1197139f7fa24
3634$ git add a
3635$ git commit -m "Updated submodule a."
3636$ git push
3637-------------------------------------------------
3638
3639You have to run `git submodule update` after `git pull` if you want to update
3640submodules, too.
3641
3642[[pitfalls-with-submodules]]
3643=== Pitfalls with submodules
3644
3645Always publish the submodule change before publishing the change to the
3646superproject that references it. If you forget to publish the submodule change,
3647others won't be able to clone the repository:
3648
3649-------------------------------------------------
3650$ cd ~/git/super/a
3651$ echo i added another line to this file >> a.txt
3652$ git commit -a -m "doing it wrong this time"
3653$ cd ..
3654$ git add a
3655$ git commit -m "Updated submodule a again."
3656$ git push
3657$ cd ~/git/cloned
3658$ git pull
3659$ git submodule update
3660error: pathspec '261dfac35cb99d380eb966e102c1197139f7fa24' did not match any file(s) known to git.
3661Did you forget to 'git add'?
3662Unable to checkout '261dfac35cb99d380eb966e102c1197139f7fa24' in submodule path 'a'
3663-------------------------------------------------
3664
3665In older Git versions it could be easily forgotten to commit new or modified
3666files in a submodule, which silently leads to similar problems as not pushing
3667the submodule changes. Starting with Git 1.7.0 both `git status` and `git diff`
3668in the superproject show submodules as modified when they contain new or
3669modified files to protect against accidentally committing such a state. `git
3670diff` will also add a `-dirty` to the work tree side when generating patch
3671output or used with the `--submodule` option:
3672
3673-------------------------------------------------
3674$ git diff
3675diff --git a/sub b/sub
3676--- a/sub
3677+++ b/sub
3678@@ -1 +1 @@
3679-Subproject commit 3f356705649b5d566d97ff843cf193359229a453
3680+Subproject commit 3f356705649b5d566d97ff843cf193359229a453-dirty
3681$ git diff --submodule
3682Submodule sub 3f35670..3f35670-dirty:
3683-------------------------------------------------
3684
3685You also should not rewind branches in a submodule beyond commits that were
3686ever recorded in any superproject.
3687
3688It's not safe to run `git submodule update` if you've made and committed
3689changes within a submodule without checking out a branch first. They will be
3690silently overwritten:
3691
3692-------------------------------------------------
3693$ cat a.txt
3694module a
3695$ echo line added from private2 >> a.txt
3696$ git commit -a -m "line added inside private2"
3697$ cd ..
3698$ git submodule update
3699Submodule path 'a': checked out 'd266b9873ad50488163457f025db7cdd9683d88b'
3700$ cd a
3701$ cat a.txt
3702module a
3703-------------------------------------------------
3704
3705NOTE: The changes are still visible in the submodule's reflog.
3706
3707If you have uncommitted changes in your submodule working tree, `git
3708submodule update` will not overwrite them. Instead, you get the usual
3709warning about not being able switch from a dirty branch.
3710
3711[[low-level-operations]]
3712== Low-level Git operations
3713
3714Many of the higher-level commands were originally implemented as shell
3715scripts using a smaller core of low-level Git commands. These can still
3716be useful when doing unusual things with Git, or just as a way to
3717understand its inner workings.
3718
3719[[object-manipulation]]
3720=== Object access and manipulation
3721
3722The linkgit:git-cat-file[1] command can show the contents of any object,
3723though the higher-level linkgit:git-show[1] is usually more useful.
3724
3725The linkgit:git-commit-tree[1] command allows constructing commits with
3726arbitrary parents and trees.
3727
3728A tree can be created with linkgit:git-write-tree[1] and its data can be
3729accessed by linkgit:git-ls-tree[1]. Two trees can be compared with
3730linkgit:git-diff-tree[1].
3731
3732A tag is created with linkgit:git-mktag[1], and the signature can be
3733verified by linkgit:git-verify-tag[1], though it is normally simpler to
3734use linkgit:git-tag[1] for both.
3735
3736[[the-workflow]]
3737=== The Workflow
3738
3739High-level operations such as linkgit:git-commit[1] and
3740linkgit:git-restore[1] work by moving data
3741between the working tree, the index, and the object database. Git
3742provides low-level operations which perform each of these steps
3743individually.
3744
3745Generally, all Git operations work on the index file. Some operations
3746work *purely* on the index file (showing the current state of the
3747index), but most operations move data between the index file and either
3748the database or the working directory. Thus there are four main
3749combinations:
3750
3751[[working-directory-to-index]]
3752==== working directory -> index
3753
3754The linkgit:git-update-index[1] command updates the index with
3755information from the working directory. You generally update the
3756index information by just specifying the filename you want to update,
3757like so:
3758
3759-------------------------------------------------
3760$ git update-index filename
3761-------------------------------------------------
3762
3763but to avoid common mistakes with filename globbing etc., the command
3764will not normally add totally new entries or remove old entries,
3765i.e. it will normally just update existing cache entries.
3766
3767To tell Git that yes, you really do realize that certain files no
3768longer exist, or that new files should be added, you
3769should use the `--remove` and `--add` flags respectively.
3770
3771NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
3772necessarily be removed: if the files still exist in your directory
3773structure, the index will be updated with their new status, not
3774removed. The only thing `--remove` means is that update-index will be
3775considering a removed file to be a valid thing, and if the file really
3776does not exist any more, it will update the index accordingly.
3777
3778As a special case, you can also do `git update-index --refresh`, which
3779will refresh the "stat" information of each index to match the current
3780stat information. It will 'not' update the object status itself, and
3781it will only update the fields that are used to quickly test whether
3782an object still matches its old backing store object.
3783
3784The previously introduced linkgit:git-add[1] is just a wrapper for
3785linkgit:git-update-index[1].
3786
3787[[index-to-object-database]]
3788==== index -> object database
3789
3790You write your current index file to a "tree" object with the program
3791
3792-------------------------------------------------
3793$ git write-tree
3794-------------------------------------------------
3795
3796that doesn't come with any options--it will just write out the
3797current index into the set of tree objects that describe that state,
3798and it will return the name of the resulting top-level tree. You can
3799use that tree to re-generate the index at any time by going in the
3800other direction:
3801
3802[[object-database-to-index]]
3803==== object database -> index
3804
3805You read a "tree" file from the object database, and use that to
3806populate (and overwrite--don't do this if your index contains any
3807unsaved state that you might want to restore later!) your current
3808index. Normal operation is just
3809
3810-------------------------------------------------
3811$ git read-tree <SHA-1 of tree>
3812-------------------------------------------------
3813
3814and your index file will now be equivalent to the tree that you saved
3815earlier. However, that is only your 'index' file: your working
3816directory contents have not been modified.
3817
3818[[index-to-working-directory]]
3819==== index -> working directory
3820
3821You update your working directory from the index by "checking out"
3822files. This is not a very common operation, since normally you'd just
3823keep your files updated, and rather than write to your working
3824directory, you'd tell the index files about the changes in your
3825working directory (i.e. `git update-index`).
3826
3827However, if you decide to jump to a new version, or check out somebody
3828else's version, or just restore a previous tree, you'd populate your
3829index file with read-tree, and then you need to check out the result
3830with
3831
3832-------------------------------------------------
3833$ git checkout-index filename
3834-------------------------------------------------
3835
3836or, if you want to check out all of the index, use `-a`.
3837
3838NOTE! `git checkout-index` normally refuses to overwrite old files, so
3839if you have an old version of the tree already checked out, you will
3840need to use the `-f` flag ('before' the `-a` flag or the filename) to
3841'force' the checkout.
3842
3843
3844Finally, there are a few odds and ends which are not purely moving
3845from one representation to the other:
3846
3847[[tying-it-all-together]]
3848==== Tying it all together
3849
3850To commit a tree you have instantiated with `git write-tree`, you'd
3851create a "commit" object that refers to that tree and the history
3852behind it--most notably the "parent" commits that preceded it in
3853history.
3854
3855Normally a "commit" has one parent: the previous state of the tree
3856before a certain change was made. However, sometimes it can have two
3857or more parent commits, in which case we call it a "merge", due to the
3858fact that such a commit brings together ("merges") two or more
3859previous states represented by other commits.
3860
3861In other words, while a "tree" represents a particular directory state
3862of a working directory, a "commit" represents that state in time,
3863and explains how we got there.
3864
3865You create a commit object by giving it the tree that describes the
3866state at the time of the commit, and a list of parents:
3867
3868-------------------------------------------------
3869$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
3870-------------------------------------------------
3871
3872and then giving the reason for the commit on stdin (either through
3873redirection from a pipe or file, or by just typing it at the tty).
3874
3875`git commit-tree` will return the name of the object that represents
3876that commit, and you should save it away for later use. Normally,
3877you'd commit a new `HEAD` state, and while Git doesn't care where you
3878save the note about that state, in practice we tend to just write the
3879result to the file pointed at by `.git/HEAD`, so that we can always see
3880what the last committed state was.
3881
3882Here is a picture that illustrates how various pieces fit together:
3883
3884------------
3885
3886 commit-tree
3887 commit obj
3888 +----+
3889 | |
3890 | |
3891 V V
3892 +-----------+
3893 | Object DB |
3894 | Backing |
3895 | Store |
3896 +-----------+
3897 ^
3898 write-tree | |
3899 tree obj | |
3900 | | read-tree
3901 | | tree obj
3902 V
3903 +-----------+
3904 | Index |
3905 | "cache" |
3906 +-----------+
3907 update-index ^
3908 blob obj | |
3909 | |
3910 checkout-index -u | | checkout-index
3911 stat | | blob obj
3912 V
3913 +-----------+
3914 | Working |
3915 | Directory |
3916 +-----------+
3917
3918------------
3919
3920
3921[[examining-the-data]]
3922=== Examining the data
3923
3924You can examine the data represented in the object database and the
3925index with various helper tools. For every object, you can use
3926linkgit:git-cat-file[1] to examine details about the
3927object:
3928
3929-------------------------------------------------
3930$ git cat-file -t <objectname>
3931-------------------------------------------------
3932
3933shows the type of the object, and once you have the type (which is
3934usually implicit in where you find the object), you can use
3935
3936-------------------------------------------------
3937$ git cat-file blob|tree|commit|tag <objectname>
3938-------------------------------------------------
3939
3940to show its contents. NOTE! Trees have binary content, and as a result
3941there is a special helper for showing that content, called
3942`git ls-tree`, which turns the binary content into a more easily
3943readable form.
3944
3945It's especially instructive to look at "commit" objects, since those
3946tend to be small and fairly self-explanatory. In particular, if you
3947follow the convention of having the top commit name in `.git/HEAD`,
3948you can do
3949
3950-------------------------------------------------
3951$ git cat-file commit HEAD
3952-------------------------------------------------
3953
3954to see what the top commit was.
3955
3956[[merging-multiple-trees]]
3957=== Merging multiple trees
3958
3959Git can help you perform a three-way merge, which can in turn be
3960used for a many-way merge by repeating the merge procedure several
3961times. The usual situation is that you only do one three-way merge
3962(reconciling two lines of history) and commit the result, but if
3963you like to, you can merge several branches in one go.
3964
3965To perform a three-way merge, you start with the two commits you
3966want to merge, find their closest common parent (a third commit),
3967and compare the trees corresponding to these three commits.
3968
3969To get the "base" for the merge, look up the common parent of two
3970commits:
3971
3972-------------------------------------------------
3973$ git merge-base <commit1> <commit2>
3974-------------------------------------------------
3975
3976This prints the name of a commit they are both based on. You should
3977now look up the tree objects of those commits, which you can easily
3978do with
3979
3980-------------------------------------------------
3981$ git cat-file commit <commitname> | head -1
3982-------------------------------------------------
3983
3984since the tree object information is always the first line in a commit
3985object.
3986
3987Once you know the three trees you are going to merge (the one "original"
3988tree, aka the common tree, and the two "result" trees, aka the branches
3989you want to merge), you do a "merge" read into the index. This will
3990complain if it has to throw away your old index contents, so you should
3991make sure that you've committed those--in fact you would normally
3992always do a merge against your last commit (which should thus match what
3993you have in your current index anyway).
3994
3995To do the merge, do
3996
3997-------------------------------------------------
3998$ git read-tree -m -u <origtree> <yourtree> <targettree>
3999-------------------------------------------------
4000
4001which will do all trivial merge operations for you directly in the
4002index file, and you can just write the result out with
4003`git write-tree`.
4004
4005
4006[[merging-multiple-trees-2]]
4007=== Merging multiple trees, continued
4008
4009Sadly, many merges aren't trivial. If there are files that have
4010been added, moved or removed, or if both branches have modified the
4011same file, you will be left with an index tree that contains "merge
4012entries" in it. Such an index tree can 'NOT' be written out to a tree
4013object, and you will have to resolve any such merge clashes using
4014other tools before you can write out the result.
4015
4016You can examine such index state with `git ls-files --unmerged`
4017command. An example:
4018
4019------------------------------------------------
4020$ git read-tree -m $orig HEAD $target
4021$ git ls-files --unmerged
4022100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
4023100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
4024100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
4025------------------------------------------------
4026
4027Each line of the `git ls-files --unmerged` output begins with
4028the blob mode bits, blob SHA-1, 'stage number', and the
4029filename. The 'stage number' is Git's way to say which tree it
4030came from: stage 1 corresponds to the `$orig` tree, stage 2 to
4031the `HEAD` tree, and stage 3 to the `$target` tree.
4032
4033Earlier we said that trivial merges are done inside
4034`git read-tree -m`. For example, if the file did not change
4035from `$orig` to `HEAD` or `$target`, or if the file changed
4036from `$orig` to `HEAD` and `$orig` to `$target` the same way,
4037obviously the final outcome is what is in `HEAD`. What the
4038above example shows is that file `hello.c` was changed from
4039`$orig` to `HEAD` and `$orig` to `$target` in a different way.
4040You could resolve this by running your favorite 3-way merge
4041program, e.g. `diff3`, `merge`, or Git's own merge-file, on
4042the blob objects from these three stages yourself, like this:
4043
4044------------------------------------------------
4045$ git cat-file blob 263414f >hello.c~1
4046$ git cat-file blob 06fa6a2 >hello.c~2
4047$ git cat-file blob cc44c73 >hello.c~3
4048$ git merge-file hello.c~2 hello.c~1 hello.c~3
4049------------------------------------------------
4050
4051This would leave the merge result in `hello.c~2` file, along
4052with conflict markers if there are conflicts. After verifying
4053the merge result makes sense, you can tell Git what the final
4054merge result for this file is by:
4055
4056-------------------------------------------------
4057$ mv -f hello.c~2 hello.c
4058$ git update-index hello.c
4059-------------------------------------------------
4060
4061When a path is in the "unmerged" state, running `git update-index` for
4062that path tells Git to mark the path resolved.
4063
4064The above is the description of a Git merge at the lowest level,
4065to help you understand what conceptually happens under the hood.
4066In practice, nobody, not even Git itself, runs `git cat-file` three times
4067for this. There is a `git merge-index` program that extracts the
4068stages to temporary files and calls a "merge" script on it:
4069
4070-------------------------------------------------
4071$ git merge-index git-merge-one-file hello.c
4072-------------------------------------------------
4073
4074and that is what higher level `git merge -s resolve` is implemented with.
4075
4076[[hacking-git]]
4077== Hacking Git
4078
4079This chapter covers internal details of the Git implementation which
4080probably only Git developers need to understand.
4081
4082[[object-details]]
4083=== Object storage format
4084
4085All objects have a statically determined "type" which identifies the
4086format of the object (i.e. how it is used, and how it can refer to other
4087objects). There are currently four different object types: "blob",
4088"tree", "commit", and "tag".
4089
4090Regardless of object type, all objects share the following
4091characteristics: they are all deflated with zlib, and have a header
4092that not only specifies their type, but also provides size information
4093about the data in the object. It's worth noting that the SHA-1 hash
4094that is used to name the object is the hash of the original data
4095plus this header, so `sha1sum` 'file' does not match the object name
4096for 'file' (the earliest versions of Git hashed slightly differently
4097but the conclusion is still the same).
4098
4099The following is a short example that demonstrates how these hashes
4100can be generated manually:
4101
4102Let's assume a small text file with some simple content:
4103
4104-------------------------------------------------
4105$ echo "Hello world" >hello.txt
4106-------------------------------------------------
4107
4108We can now manually generate the hash Git would use for this file:
4109
4110- The object we want the hash for is of type "blob" and its size is
4111 12 bytes.
4112
4113- Prepend the object header to the file content and feed this to
4114 `sha1sum`:
4115
4116-------------------------------------------------
4117$ { printf "blob 12\0"; cat hello.txt; } | sha1sum
4118802992c4220de19a90767f3000a79a31b98d0df7 -
4119-------------------------------------------------
4120
4121This manually constructed hash can be verified using `git hash-object`
4122which of course hides the addition of the header:
4123
4124-------------------------------------------------
4125$ git hash-object hello.txt
4126802992c4220de19a90767f3000a79a31b98d0df7
4127-------------------------------------------------
4128
4129As a result, the general consistency of an object can always be tested
4130independently of the contents or the type of the object: all objects can
4131be validated by verifying that (a) their hashes match the content of the
4132file and (b) the object successfully inflates to a stream of bytes that
4133forms a sequence of
4134`<ascii-type-without-space> + <space> + <ascii-decimal-size> +
4135<byte\0> + <binary-object-data>`.
4136
4137The structured objects can further have their structure and
4138connectivity to other objects verified. This is generally done with
4139the `git fsck` program, which generates a full dependency graph
4140of all objects, and verifies their internal consistency (in addition
4141to just verifying their superficial consistency through the hash).
4142
4143[[birdview-on-the-source-code]]
4144=== A birds-eye view of Git's source code
4145
4146It is not always easy for new developers to find their way through Git's
4147source code. This section gives you a little guidance to show where to
4148start.
4149
4150A good place to start is with the contents of the initial commit, with:
4151
4152----------------------------------------------------
4153$ git switch --detach e83c5163
4154----------------------------------------------------
4155
4156The initial revision lays the foundation for almost everything Git has
4157today (even though details may differ in a few places), but is small
4158enough to read in one sitting.
4159
4160Note that terminology has changed since that revision. For example, the
4161README in that revision uses the word "changeset" to describe what we
4162now call a <<def_commit_object,commit>>.
4163
4164Also, we do not call it "cache" any more, but rather "index"; however,
4165the file is still called `read-cache.h`.
4166
4167If you grasp the ideas in that initial commit, you should check out a
4168more recent version and skim `read-cache-ll.h`, `object.h` and `commit.h`.
4169
4170In the early days, Git (in the tradition of UNIX) was a bunch of programs
4171which were extremely simple, and which you used in scripts, piping the
4172output of one into another. This turned out to be good for initial
4173development, since it was easier to test new things. However, recently
4174many of these parts have become builtins, and some of the core has been
4175"libified", i.e. put into libgit.a for performance, portability reasons,
4176and to avoid code duplication.
4177
4178By now, you know what the index is (and find the corresponding data
4179structures in `read-cache-ll.h`), and that there are just a couple of
4180object types (blobs, trees, commits and tags) which inherit their
4181common structure from `struct object`, which is their first member
4182(and thus, you can cast e.g. `(struct object *)commit` to achieve the
4183_same_ as `&commit->object`, i.e. get at the object name and flags).
4184
4185Now is a good point to take a break to let this information sink in.
4186
4187Next step: get familiar with the object naming. Read <<naming-commits>>.
4188There are quite a few ways to name an object (and not only revisions!).
4189All of these are handled in `sha1_name.c`. Just have a quick look at
4190the function `get_sha1()`. A lot of the special handling is done by
4191functions like `get_sha1_basic()` or the likes.
4192
4193This is just to get you into the groove for the most libified part of Git:
4194the revision walker.
4195
4196Basically, the initial version of `git log` was a shell script:
4197
4198----------------------------------------------------------------
4199$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
4200 LESS=-S ${PAGER:-less}
4201----------------------------------------------------------------
4202
4203What does this mean?
4204
4205`git rev-list` is the original version of the revision walker, which
4206_always_ printed a list of revisions to stdout. It is still functional,
4207and needs to, since most new Git commands start out as scripts using
4208`git rev-list`.
4209
4210`git rev-parse` is not as important any more; it was only used to filter out
4211options that were relevant for the different plumbing commands that were
4212called by the script.
4213
4214Most of what `git rev-list` did is contained in `revision.c` and
4215`revision.h`. It wraps the options in a struct named `rev_info`, which
4216controls how and what revisions are walked, and more.
4217
4218The original job of `git rev-parse` is now taken by the function
4219`setup_revisions()`, which parses the revisions and the common command-line
4220options for the revision walker. This information is stored in the struct
4221`rev_info` for later consumption. You can do your own command-line option
4222parsing after calling `setup_revisions()`. After that, you have to call
4223`prepare_revision_walk()` for initialization, and then you can get the
4224commits one by one with the function `get_revision()`.
4225
4226If you are interested in more details of the revision walking process,
4227just have a look at the first implementation of `cmd_log()`; call
4228`git show v1.3.0~155^2~4` and scroll down to that function (note that you
4229no longer need to call `setup_pager()` directly).
4230
4231Nowadays, `git log` is a builtin, which means that it is _contained_ in the
4232command `git`. The source side of a builtin is
4233
4234- a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>`
4235 (note that older versions of Git used to have it in `builtin-<bla>.c`
4236 instead), and declared in `builtin.h`.
4237
4238- an entry in the `commands[]` array in `git.c`, and
4239
4240- an entry in `BUILTIN_OBJECTS` in the `Makefile`.
4241
4242Sometimes, more than one builtin is contained in one source file. For
4243example, `cmd_show()` and `cmd_log()` both reside in `builtin/log.c`,
4244since they share quite a bit of code. In that case, the commands which are
4245_not_ named like the `.c` file in which they live have to be listed in
4246`BUILT_INS` in the `Makefile`.
4247
4248`git log` looks more complicated in C than it does in the original script,
4249but that allows for a much greater flexibility and performance.
4250
4251Here again it is a good point to take a pause.
4252
4253Lesson three is: study the code. Really, it is the best way to learn about
4254the organization of Git (after you know the basic concepts).
4255
4256So, think about something which you are interested in, say, "how can I
4257access a blob just knowing the object name of it?". The first step is to
4258find a Git command with which you can do it. In this example, it is either
4259`git show` or `git cat-file`.
4260
4261For the sake of clarity, let's stay with `git cat-file`, because it
4262
4263- is plumbing, and
4264
4265- was around even in the initial commit (it literally went only through
4266 some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c`
4267 when made a builtin, and then saw less than 10 versions).
4268
4269So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what
4270it does.
4271
4272------------------------------------------------------------------
4273 repo_config(the_repository, git_default_config);
4274 if (argc != 3)
4275 usage("git cat-file [-t|-s|-e|-p|<type>] <sha1>");
4276 if (get_sha1(argv[2], sha1))
4277 die("Not a valid object name %s", argv[2]);
4278------------------------------------------------------------------
4279
4280Let's skip over the obvious details; the only really interesting part
4281here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an
4282object name, and if it refers to an object which is present in the current
4283repository, it writes the resulting SHA-1 into the variable `sha1`.
4284
4285Two things are interesting here:
4286
4287- `get_sha1()` returns 0 on _success_. This might surprise some new
4288 Git hackers, but there is a long tradition in UNIX to return different
4289 negative numbers in case of different errors--and 0 on success.
4290
4291- the variable `sha1` in the function signature of `get_sha1()` is `unsigned
4292 char *`, but is actually expected to be a pointer to `unsigned
4293 char[20]`. This variable will contain the 160-bit SHA-1 of the given
4294 commit. Note that whenever a SHA-1 is passed as `unsigned char *`, it
4295 is the binary representation, as opposed to the ASCII representation in
4296 hex characters, which is passed as `char *`.
4297
4298You will see both of these things throughout the code.
4299
4300Now, for the meat:
4301
4302-----------------------------------------------------------------------------
4303 case 0:
4304 buf = odb_read_object_peeled(r->objects, sha1, argv[1], &size, NULL);
4305-----------------------------------------------------------------------------
4306
4307This is how you read a blob (actually, not only a blob, but any type of
4308object). To know how the function `odb_read_object_peeled()` actually
4309works, find the source code for it (something like `git grep
4310read_object_with | grep ":[a-z]"` in the Git repository), and read
4311the source.
4312
4313To find out how the result can be used, just read on in `cmd_cat_file()`:
4314
4315-----------------------------------
4316 write_or_die(1, buf, size);
4317-----------------------------------
4318
4319Sometimes, you do not know where to look for a feature. In many such cases,
4320it helps to search through the output of `git log`, and then `git show` the
4321corresponding commit.
4322
4323Example: If you know that there was some test case for `git bundle`, but
4324do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
4325does not illustrate the point!):
4326
4327------------------------
4328$ git log --no-merges t/
4329------------------------
4330
4331In the pager (`less`), just search for "bundle", go a few lines back,
4332and see that it is in commit 18449ab0. Now just copy this object name,
4333and paste it into the command line
4334
4335-------------------
4336$ git show 18449ab0
4337-------------------
4338
4339Voila.
4340
4341Another example: Find out what to do in order to make some script a
4342builtin:
4343
4344-------------------------------------------------
4345$ git log --no-merges --diff-filter=A builtin/*.c
4346-------------------------------------------------
4347
4348You see, Git is actually the best tool to find out about the source of Git
4349itself!
4350
4351[[glossary]]
4352== Git Glossary
4353
4354[[git-explained]]
4355=== Git explained
4356
4357include::glossary-content.adoc[]
4358
4359[[git-quick-start]]
4360[appendix]
4361== Git Quick Reference
4362
4363This is a quick summary of the major commands; the previous chapters
4364explain how these work in more detail.
4365
4366[[quick-creating-a-new-repository]]
4367=== Creating a new repository
4368
4369From a tarball:
4370
4371-----------------------------------------------
4372$ tar xzf project.tar.gz
4373$ cd project
4374$ git init
4375Initialized empty Git repository in .git/
4376$ git add .
4377$ git commit
4378-----------------------------------------------
4379
4380From a remote repository:
4381
4382-----------------------------------------------
4383$ git clone git://example.com/pub/project.git
4384$ cd project
4385-----------------------------------------------
4386
4387[[managing-branches]]
4388=== Managing branches
4389
4390-----------------------------------------------
4391$ git branch # list all local branches in this repo
4392$ git switch test # switch working directory to branch "test"
4393$ git branch new # create branch "new" starting at current HEAD
4394$ git branch -d new # delete branch "new"
4395-----------------------------------------------
4396
4397Instead of basing a new branch on current HEAD (the default), use:
4398
4399-----------------------------------------------
4400$ git branch new test # branch named "test"
4401$ git branch new v2.6.15 # tag named v2.6.15
4402$ git branch new HEAD^ # commit before the most recent
4403$ git branch new HEAD^^ # commit before that
4404$ git branch new test~10 # ten commits before tip of branch "test"
4405-----------------------------------------------
4406
4407Create and switch to a new branch at the same time:
4408
4409-----------------------------------------------
4410$ git switch -c new v2.6.15
4411-----------------------------------------------
4412
4413Update and examine branches from the repository you cloned from:
4414
4415-----------------------------------------------
4416$ git fetch # update
4417$ git branch -r # list
4418 origin/master
4419 origin/next
4420 ...
4421$ git switch -c masterwork origin/master
4422-----------------------------------------------
4423
4424Fetch a branch from a different repository, and give it a new
4425name in your repository:
4426
4427-----------------------------------------------
4428$ git fetch git://example.com/project.git theirbranch:mybranch
4429$ git fetch git://example.com/project.git v2.6.15:mybranch
4430-----------------------------------------------
4431
4432Keep a list of repositories you work with regularly:
4433
4434-----------------------------------------------
4435$ git remote add example git://example.com/project.git
4436$ git remote # list remote repositories
4437example
4438origin
4439$ git remote show example # get details
4440* remote example
4441 URL: git://example.com/project.git
4442 Tracked remote branches
4443 master
4444 next
4445 ...
4446$ git fetch example # update branches from example
4447$ git branch -r # list all remote branches
4448-----------------------------------------------
4449
4450
4451[[exploring-history]]
4452=== Exploring history
4453
4454-----------------------------------------------
4455$ gitk # visualize and browse history
4456$ git log # list all commits
4457$ git log src/ # ...modifying src/
4458$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15
4459$ git log master..test # ...in branch test, not in branch master
4460$ git log test..master # ...in branch master, but not in test
4461$ git log test...master # ...in one branch, not in both
4462$ git log -S'foo()' # ...where difference contain "foo()"
4463$ git log --since="2 weeks ago"
4464$ git log -p # show patches as well
4465$ git show # most recent commit
4466$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
4467$ git diff v2.6.15..HEAD # diff with current head
4468$ git grep "foo()" # search working directory for "foo()"
4469$ git grep v2.6.15 "foo()" # search old tree for "foo()"
4470$ git show v2.6.15:a.txt # look at old version of a.txt
4471-----------------------------------------------
4472
4473Search for regressions:
4474
4475-----------------------------------------------
4476$ git bisect start
4477$ git bisect bad # current version is bad
4478$ git bisect good v2.6.13-rc2 # last known good revision
4479Bisecting: 675 revisions left to test after this
4480 # test here, then:
4481$ git bisect good # if this revision is good, or
4482$ git bisect bad # if this revision is bad.
4483 # repeat until done.
4484-----------------------------------------------
4485
4486[[making-changes]]
4487=== Making changes
4488
4489Make sure Git knows who to blame:
4490
4491------------------------------------------------
4492$ cat >>~/.gitconfig <<\EOF
4493[user]
4494 name = Your Name Comes Here
4495 email = you@yourdomain.example.com
4496EOF
4497------------------------------------------------
4498
4499Select file contents to include in the next commit, then make the
4500commit:
4501
4502-----------------------------------------------
4503$ git add a.txt # updated file
4504$ git add b.txt # new file
4505$ git rm c.txt # old file
4506$ git commit
4507-----------------------------------------------
4508
4509Or, prepare and create the commit in one step:
4510
4511-----------------------------------------------
4512$ git commit d.txt # use latest content only of d.txt
4513$ git commit -a # use latest content of all tracked files
4514-----------------------------------------------
4515
4516[[merging]]
4517=== Merging
4518
4519-----------------------------------------------
4520$ git merge test # merge branch "test" into the current branch
4521$ git pull git://example.com/project.git master
4522 # fetch and merge in remote branch
4523$ git pull . test # equivalent to git merge test
4524-----------------------------------------------
4525
4526[[sharing-your-changes]]
4527=== Sharing your changes
4528
4529Importing or exporting patches:
4530
4531-----------------------------------------------
4532$ git format-patch origin..HEAD # format a patch for each commit
4533 # in HEAD but not in origin
4534$ git am mbox # import patches from the mailbox "mbox"
4535-----------------------------------------------
4536
4537Fetch a branch in a different Git repository, then merge into the
4538current branch:
4539
4540-----------------------------------------------
4541$ git pull git://example.com/project.git theirbranch
4542-----------------------------------------------
4543
4544Store the fetched branch into a local branch before merging into the
4545current branch:
4546
4547-----------------------------------------------
4548$ git pull git://example.com/project.git theirbranch:mybranch
4549-----------------------------------------------
4550
4551After creating commits on a local branch, update the remote
4552branch with your commits:
4553
4554-----------------------------------------------
4555$ git push ssh://example.com/project.git mybranch:theirbranch
4556-----------------------------------------------
4557
4558When remote and local branch are both named "test":
4559
4560-----------------------------------------------
4561$ git push ssh://example.com/project.git test
4562-----------------------------------------------
4563
4564Shortcut version for a frequently used remote repository:
4565
4566-----------------------------------------------
4567$ git remote add example ssh://example.com/project.git
4568$ git push example test
4569-----------------------------------------------
4570
4571[[repository-maintenance]]
4572=== Repository maintenance
4573
4574Check for corruption:
4575
4576-----------------------------------------------
4577$ git fsck
4578-----------------------------------------------
4579
4580Recompress, remove unused cruft:
4581
4582-----------------------------------------------
4583$ git gc
4584-----------------------------------------------
4585
4586
4587[[todo]]
4588[appendix]
4589== Notes and todo list for this manual
4590
4591[[todo-list]]
4592=== Todo list
4593
4594This is a work in progress.
4595
4596The basic requirements:
4597
4598- It must be readable in order, from beginning to end, by someone
4599 intelligent with a basic grasp of the UNIX command line, but without
4600 any special knowledge of Git. If necessary, any other prerequisites
4601 should be specifically mentioned as they arise.
4602- Whenever possible, section headings should clearly describe the task
4603 they explain how to do, in language that requires no more knowledge
4604 than necessary: for example, "importing patches into a project" rather
4605 than "the `git am` command"
4606
4607Think about how to create a clear chapter dependency graph that will
4608allow people to get to important topics without necessarily reading
4609everything in between.
4610
4611Scan `Documentation/` for other stuff left out; in particular:
4612
4613- howto's
4614- some of `technical/`?
4615- hooks
4616- list of commands in linkgit:git[1]
4617
4618Scan email archives for other stuff left out
4619
4620Scan man pages to see if any assume more background than this manual
4621provides.
4622
4623Add more good examples. Entire sections of just cookbook examples
4624might be a good idea; maybe make an "advanced examples" section a
4625standard end-of-chapter section?
4626
4627Include cross-references to the glossary, where appropriate.
4628
4629Add a section on working with other version control systems, including
4630CVS, Subversion, and just imports of series of release tarballs.
4631
4632Write a chapter on using plumbing and writing scripts.
4633
4634Alternates, clone -reference, etc.
4635
4636More on recovery from repository corruption. See:
4637 https://lore.kernel.org/git/Pine.LNX.4.64.0702272039540.12485@woody.linux-foundation.org/
4638 https://lore.kernel.org/git/Pine.LNX.4.64.0702141033400.3604@woody.linux-foundation.org/