5 ////////////////////////
6 Please note that this document is in asciidoc format.
7 http://www.methods.co.nz/asciidoc/index.html
9 You should be able to read it but be aware that there is some minor
10 typographical bludgeoning to allow the production of clean man and
13 (eg in some synopsis lines the '*' character is preceded by a '\' and
14 there are one or two '+' characters)
16 ////////////////////////
20 git - the stupid content tracker
24 'git-<command>' <args>
29 This is reference information for the core git commands.
31 The link:README[] contains much useful definition and clarification
32 info - read that first. And of the commands, I suggest reading
33 'git-update-cache' and 'git-read-tree' first - I wish I had!
35 David Greaves <david@dgreaves.com>
38 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
39 reflect recent changes.
43 The git commands can helpfully be split into those that manipulate
44 the repository, the cache and the working fileset and those that
45 interrogate and compare them.
49 link:git-apply-patch-script.html[git-apply-patch-script]::
50 Sample script to apply the diffs from git-diff-*
52 link:git-checkout-cache.html[git-checkout-cache]::
53 Copy files from the cache to the working directory
55 link:git-commit-tree.html[git-commit-tree]::
56 Creates a new commit object
58 link:git-convert-cache.html[git-convert-cache]::
59 Converts old-style GIT repository
61 link:git-http-pull.html[git-http-pull]::
62 Downloads a remote GIT repository via HTTP
64 link:git-init-db.html[git-init-db]::
65 Creates an empty git object database
67 link:git-local-pull.html[git-local-pull]::
68 Duplicates another GIT repository on a local system
70 link:git-merge-base.html[git-merge-base]::
71 Finds as good a common ancestor as possible for a merge
73 link:git-merge-one-file-script.html[git-merge-one-file-script]::
74 The standard helper program to use with "git-merge-cache"
76 link:git-mktag.html[git-mktag]::
79 link:git-prune-script.html[git-prune-script]::
80 Prunes all unreachable objects from the object database
82 link:git-pull-script.html[git-pull-script]::
83 Script used by Linus to pull and merge a remote repository
85 link:git-read-tree.html[git-read-tree]::
86 Reads tree information into the directory cache
88 link:git-resolve-script.html[git-resolve-script]::
89 Script used to merge two trees
91 link:git-rpull.html[git-rpull]::
92 Pulls from a remote repository over ssh connection
94 link:git-tag-script.html[git-tag-script]::
95 An example script to create a tag object signed with GPG
97 link:git-update-cache.html[git-update-cache]::
98 Modifies the index or directory cache
100 link:git-write-blob.html[git-write-blob]::
101 Creates a blob from a file
103 link:git-write-tree.html[git-write-tree]::
104 Creates a tree from the current cache
106 Interrogation commands
107 ~~~~~~~~~~~~~~~~~~~~~~
108 link:git-cat-file.html[git-cat-file]::
109 Provide content or type information for repository objects
111 link:git-check-files.html[git-check-files]::
112 Verify a list of files are up-to-date
114 link:git-diff-cache.html[git-diff-cache]::
115 Compares content and mode of blobs between the cache and repository
117 link:git-diff-files.html[git-diff-files]::
118 Compares files in the working tree and the cache
120 link:git-diff-tree.html[git-diff-tree]::
121 Compares the content and mode of blobs found via two tree objects
123 link:git-diff-tree-helper.html[git-diff-tree-helper]::
124 Generates patch format output for git-diff-*
126 link:git-export.html[git-export]::
127 Exports each commit and a diff against each of its parents
129 link:git-fsck-cache.html[git-fsck-cache]::
130 Verifies the connectivity and validity of the objects in the database
132 link:git-ls-files.html[git-ls-files]::
133 Information about files in the cache/working directory
135 link:git-ls-tree.html[git-ls-tree]::
136 Displays a tree object in human readable form
138 link:git-merge-cache.html[git-merge-cache]::
139 Runs a merge for files needing merging
141 link:git-rev-list.html[git-rev-list]::
142 Lists commit objects in reverse chronological order
144 link:git-rev-tree.html[git-rev-tree]::
145 Provides the revision tree for one or more commits
147 link:git-rpush.html[git-rpush]::
148 Helper "server-side" program used by git-rpull
150 link:git-tar-tree.html[git-tar-tree]::
151 Creates a tar archive of the files in the named tree
153 link:git-unpack-file.html[git-unpack-file]::
154 Creates a temporary file with a blob's contents
156 The interrogate commands may create files - and you can force them to
157 touch the working file set - but in general they don't
162 see README for description
164 Identifier terminology
165 ----------------------
167 Indicates any object sha1 identifier
170 Indicates a blob object sha1 identifier
173 Indicates a tree object sha1 identifier
176 Indicates a commit object sha1 identifier
179 Indicates a tree, commit or tag object sha1 identifier.
180 A command that takes a <tree-ish> argument ultimately
181 wants to operate on a <tree> object but automatically
182 dereferences <commit> and <tag> that points at a
186 Indicates that an object type is required.
187 Currently one of: blob/tree/commit/tag
190 Indicates a filename - always relative to the root of
191 the tree structure GIT_INDEX_FILE describes.
195 Each line contains terms used interchangeably
197 object database, .git directory
198 directory cache, index
199 id, sha1, sha1-id, sha1 hash
203 commit, commit object
209 Environment Variables
210 ---------------------
211 Various git commands use the following environment variables:
216 - 'COMMIT_AUTHOR_NAME'
217 - 'COMMIT_AUTHOR_EMAIL'
219 - 'GIT_EXTERNAL_DIFF'
221 - 'SHA1_FILE_DIRECTORY'
226 git-apply-patch-script - Sample script to apply the diffs from git-diff-*
230 'git-apply-patch-script'
234 This is a sample script to be used via the 'GIT_EXTERNAL_DIFF'
235 environment variable to apply the differences that the "git-diff-*"
236 family of commands report to the current work tree.
241 git-cat-file - Provide content or type information for repository objects
245 'git-cat-file' (-t | <type>) <object>
249 Provides content or type of objects in the repository. The type
250 is required if '-t' is not being used to find the object type.
255 The sha1 identifier of the object.
258 Instead of the content, show the object type identified by
262 Typically this matches the real type of <object> but asking
263 for a type that can trivially dereferenced from the given
264 <object> is also permitted. An example is to ask for a
265 "tree" with <object> being a commit object that contains it,
266 or to ask for a "blob" with <object> being a tag object that
271 If '-t' is specified, one of the <type>.
273 Otherwise the raw (though uncompressed) contents of the <object> will
279 git-check-files - Verify a list of files are up-to-date
284 'git-check-files' <file>...
288 Check that a list of files are up-to-date between the filesystem and
289 the cache. Used to verify a patch target before doing a patch.
291 Files that do not exist on the filesystem are considered up-to-date
292 (whether or not they are in the cache).
294 Emits an error message on failure:
296 preparing to update existing file <file> not in cache::
297 <file> exists but is not in the cache
299 preparing to update file <file> not uptodate in cache::
300 <file> on disk is not up-to-date with the cache
302 Exits with a status code indicating success if all files are
305 see also: link:git-update-cache.html[git-update-cache]
310 git-checkout-cache - Copy files from the cache to the working directory
314 'git-checkout-cache' [-q] [-a] [-f] [-n] [--prefix=<string>]
319 Will copy all files listed from the cache to the working directory
320 (not overwriting existing files).
325 be quiet if files exist or are not in the cache
328 forces overwrite of existing files
331 checks out all files in the cache (will then continue to
332 process listed files).
335 Don't checkout new files, only refresh files already checked
339 When creating files, prepend <string> (usually a directory
340 including a trailing /)
343 Do not interpret any more arguments as options.
345 Note that the order of the flags matters:
347 git-checkout-cache -a -f file.c
349 will first check out all files listed in the cache (but not overwrite
350 any old ones), and then force-checkout `file.c` a second time (ie that
351 one *will* overwrite any old contents with the same filename).
353 Also, just doing "git-checkout-cache" does nothing. You probably meant
354 "git-checkout-cache -a". And if you want to force it, you want
355 "git-checkout-cache -f -a".
357 Intuitiveness is not the goal here. Repeatability is. The reason for
358 the "no arguments means no work" thing is that from scripts you are
359 supposed to be able to do things like:
361 find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f --
363 which will force all existing `*.h` files to be replaced with their
364 cached copies. If an empty command line implied "all", then this would
365 force-refresh everything in the cache, which was not the point.
367 To update and refresh only the files already checked out:
369 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
371 Oh, and the "--" is just a good idea when you know the rest will be
372 filenames. Just so that you wouldn't have a filename of "-a" causing
373 problems (not possible in the above example, but get used to it in
376 The prefix ability basically makes it trivial to use
377 git-checkout-cache as an "export as tree" function. Just read the
378 desired tree into the index, and do a
380 git-checkout-cache --prefix=git-export-dir/ -a
382 and git-checkout-cache will "export" the cache into the specified
385 NOTE The final "/" is important. The exported name is literally just
386 prefixed with the specified string, so you can also do something like
388 git-checkout-cache --prefix=.merged- Makefile
390 to check out the currently cached copy of `Makefile` into the file
395 git-commit-tree - Creates a new commit object
399 'git-commit-tree' <tree> [-p <parent commit>]\ < changelog
403 Creates a new commit object based on the provided tree object and
404 emits the new commit object id on stdout. If no parent is given then
405 it is considered to be an initial tree.
407 A commit object usually has 1 parent (a commit after a change) or up
408 to 16 parents. More than one parent represents a merge of branches
411 While a tree represents a particular directory state of a working
412 directory, a commit represents that state in "time", and explains how
415 Normally a commit would identify a new "HEAD" state, and while git
416 doesn't care where you save the note about that state, in practice we
417 tend to just write the result to the file `.git/HEAD`, so that we can
418 always see what the last committed state was.
423 An existing tree object
426 Each '-p' indicates a the id of a parent commit object.
432 A commit encapsulates:
434 - all parent object ids
435 - author name, email and date
436 - committer name and email and the commit time.
438 If not provided, "git-commit-tree" uses your name, hostname and domain to
439 provide author and committer info. This can be overridden using the
440 following environment variables.
448 (nb <,> and '\n's are stripped)
450 A commit comment is read from stdin (max 999 chars). If a changelog
451 entry is not provided via '<' redirection, "git-commit-tree" will just wait
452 for one to be entered and terminated with ^D
454 see also: link:git-write-tree.html[git-write-tree]
459 git-convert-cache - Converts old-style GIT repository
467 Converts old-style GIT repository to the latest format
472 git-diff-cache - Compares content and mode of blobs between the cache and repository
476 'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish>
480 Compares the content and mode of the blobs found via a tree object
481 with the content of the current cache and, optionally ignoring the
482 stat state of the file on disk.
487 The id of a tree object to diff against.
490 Generate patch (see section on generating patches)
493 This flag does not mean anything. It is there only to match
494 "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache"
495 always looks at all the subdirectories.
498 \0 line termination on output
501 do not consider the on-disk file at all
504 By default, files recorded in the index but not checked
505 out are reported as deleted. This flag makes
506 "git-diff-cache" say that all non-checked-out files are up
511 include::diff-format.txt[]
515 You can choose whether you want to trust the index file entirely
516 (using the '--cached' flag) or ask the diff logic to show any files
517 that don't match the stat state as being "tentatively changed". Both
518 of these operations are very useful indeed.
522 If '--cached' is specified, it allows you to ask:
524 show me the differences between HEAD and the current index
525 contents (the ones I'd write with a "git-write-tree")
527 For example, let's say that you have worked on your index file, and are
528 ready to commit. You want to see eactly *what* you are going to commit is
529 without having to write a new tree object and compare it that way, and to
532 git-diff-cache --cached $(cat .git/HEAD)
534 Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
535 done an "git-update-cache" to make that effective in the index file.
536 "git-diff-files" wouldn't show anything at all, since the index file
537 matches my working directory. But doing a "git-diff-cache" does:
539 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)
540 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c
541 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c
543 You can trivially see that the above is a rename.
545 In fact, "git-diff-cache --cached" *should* always be entirely equivalent to
546 actually doing a "git-write-tree" and comparing that. Except this one is much
547 nicer for the case where you just want to check where you are.
549 So doing a "git-diff-cache --cached" is basically very useful when you are
550 asking yourself "what have I already marked for being committed, and
551 what's the difference to a previous tree".
555 The "non-cached" mode takes a different approach, and is potentially
556 the more useful of the two in that what it does can't be emulated with
557 a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
558 The non-cached version asks the question:
560 show me the differences between HEAD and the currently checked out
561 tree - index contents _and_ files that aren't up-to-date
563 which is obviously a very useful question too, since that tells you what
564 you *could* commit. Again, the output matches the "git-diff-tree -r"
565 output to a tee, but with a twist.
567 The twist is that if some file doesn't match the cache, we don't have
568 a backing store thing for it, and we use the magic "all-zero" sha1 to
569 show that. So let's say that you have edited `kernel/sched.c`, but
570 have not actually done a "git-update-cache" on it yet - there is no
571 "object" associated with the new state, and you get:
573 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )
574 *100644->100664 blob 7476bb......->000000...... kernel/sched.c
576 ie it shows that the tree has changed, and that `kernel/sched.c` has is
577 not up-to-date and may contain new stuff. The all-zero sha1 means that to
578 get the real diff, you need to look at the object in the working directory
579 directly rather than do an object-to-object diff.
581 NOTE! As with other commands of this type, "git-diff-cache" does not
582 actually look at the contents of the file at all. So maybe
583 `kernel/sched.c` hasn't actually changed, and it's just that you
584 touched it. In either case, it's a note that you need to
585 "git-upate-cache" it to make the cache be in sync.
587 NOTE 2! You can have a mixture of files show up as "has been updated"
588 and "is still dirty in the working directory" together. You can always
589 tell which file is in which state, since the "has been updated" ones
590 show a valid sha1, and the "not in sync with the index" ones will
591 always have the special all-zero sha1.
596 git-diff-files - Compares files in the working tree and the cache
600 'git-diff-files' [-p] [-q] [-r] [-z] [<pattern>...]
604 Compares the files in the working tree and the cache. When paths
605 are specified, compares only those named paths. Otherwise all
606 entries in the cache are compared. The output format is the
607 same as "git-diff-cache" and "git-diff-tree".
612 generate patch (see section on generating patches).
615 Remain silent even on nonexisting files
618 This flag does not mean anything. It is there only to match
619 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks
620 at all the subdirectories.
625 include::diff-format.txt[]
630 git-diff-tree - Compares the content and mode of blobs found via two tree objects
634 'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]\*
638 Compares the content and mode of the blobs found via two tree objects.
640 Note that "git-diff-tree" can use the tree encapsulated in a commit object.
645 The id of a tree object.
648 If provided, the results are limited to a subset of files
649 matching one of these prefix strings.
650 ie file matches `/^<pattern1>|<pattern2>|.../`
651 Note that pattern does not provide any wildcard or regexp
655 generate patch (see section on generating patches). For
656 git-diff-tree, this flag implies '-r' as well.
662 \0 line termination on output
665 When '--stdin' is specified, the command does not take
666 <tree-ish> arguments from the command line. Instead, it
667 reads either one <commit> or a pair of <tree-ish>
668 separated with a single space from its standard input.
670 When a single commit is given on one line of such input, it compares
671 the commit with its parents. The following flags further affects its
672 behaviour. This does not apply to the case where two <tree-ish>
673 separated with a single space are given.
676 By default, "git-diff-tree --stdin" does not show
677 differences for merge commits. With this flag, it shows
678 differences to that commit from all of its parents.
681 By default, "git-diff-tree --stdin" shows differences,
682 either in machine-readable form (without '-p') or in patch
683 form (with '-p'). This output can be supressed. It is
684 only useful with '-v' flag.
687 This flag causes "git-diff-tree --stdin" to also show
688 the commit message before the differences.
693 If you're only interested in differences in a subset of files, for
694 example some architecture-specific files, you might do:
696 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
698 and it will only show you what changed in those two directories.
700 Or if you are searching for what changed in just `kernel/sched.c`, just do
702 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
704 and it will ignore all differences to other files.
706 The pattern is always the prefix, and is matched exactly. There are no
707 wildcards. Even stricter, it has to match complete path comonent.
708 I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h`
709 so it can be used to name subdirectories.
711 An example of normal usage is:
713 torvalds@ppc970:~/git> git-diff-tree 5319e4......
714 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c
716 which tells you that the last commit changed just one file (it's from
719 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
720 tree 5319e4d609cdd282069cc4dce33c1db559539b03
721 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
722 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
723 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
725 Make "git-fsck-cache" print out all the root commits it finds.
727 Once I do the reference tracking, I'll also make it print out all the
728 HEAD commits it finds, which is even more interesting.
734 include::diff-format.txt[]
739 git-diff-tree-helper - Generates patch format output for git-diff-*
743 'git-diff-tree-helper' [-z] [-R]
747 Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and
748 generates patch format output.
753 \0 line termination on input
756 Output diff in reverse. This is useful for displaying output from
757 "git-diff-cache" which always compares tree with cache or working
760 git-diff-cache <tree> | git-diff-tree-helper -R file.c
762 would show a diff to bring the working file back to what is in the <tree>.
764 See also the section on generating patches in link:git-diff-cache.html[git-diff-cache]
769 git-export - Exports each commit and a diff against each of its parents
773 'git-export' top [base]
777 Exports each commit and diff against each of its parents, between
778 top and base. If base is not specified it exports everything.
783 git-fsck-cache - Verifies the connectivity and validity of the objects in the database
787 'git-fsck-cache' [--tags] [--root] [[--unreachable] [--cache] <object>\*]
791 Verifies the connectivity and validity of the objects in the database.
796 An object to treat as the head of an unreachability trace.
799 Print out objects that exist but that aren't readable from any
800 of the specified head nodes.
809 Consider any object recorded in the cache also as a head node for
810 an unreachability trace.
812 It tests SHA1 and general object sanity, and it does full tracking of
813 the resulting reachability and everything else. It prints out any
814 corruption it finds (missing or bad objects), and if you use the
815 '--unreachable' flag it will also print out objects that exist but
816 that aren't readable from any of the specified head nodes.
820 git-fsck-cache --unreachable $(cat .git/HEAD)
822 or, for Cogito users:
824 git-fsck-cache --unreachable $(cat .git/refs/heads/*)
826 will do quite a _lot_ of verification on the tree. There are a few
827 extra validity tests to be added (make sure that tree objects are
828 sorted properly etc), but on the whole if "git-fsck-cache" is happy, you
829 do have a valid tree.
831 Any corrupt objects you will have to find in backups or other archives
832 (ie you can just remove them and do an "rsync" with some other site in
833 the hopes that somebody else has the object you have corrupted).
835 Of course, "valid tree" doesn't mean that it wasn't generated by some
836 evil person, and the end result might be crap. Git is a revision
837 tracking system, not a quality assurance system ;)
839 Extracted Diagnostics
840 ---------------------
842 expect dangling commits - potential heads - due to lack of head information::
843 You haven't specified any nodes as heads so it won't be
844 possible to differentiate between un-parented commits and
847 missing sha1 directory '<dir>'::
848 The directory holding the sha1 objects is missing.
850 unreachable <type> <object>::
851 The <type> object <object>, isn't actually referred to directly
852 or indirectly in any of the trees or commits seen. This can
853 mean that there's another root node that you're not specifying
854 or that the tree is corrupt. If you haven't missed a root node
855 then you might as well delete unreachable nodes since they
858 missing <type> <object>::
859 The <type> object <object>, is referred to but isn't present in
862 dangling <type> <object>::
863 The <type> object <object>, is present in the database but never
864 'directly' used. A dangling commit could be a root node.
866 warning: git-fsck-cache: tree <tree> has full pathnames in it::
869 sha1 mismatch <object>::
870 The database has an object who's sha1 doesn't match the
872 This indicates a serious data integrity problem.
873 (note: this error occured during early git development when
874 the database format changed.)
876 Environment Variables
877 ---------------------
879 SHA1_FILE_DIRECTORY::
880 used to specify the object database root (usually .git/objects)
883 used to specify the cache
888 git-http-pull - Downloads a remote GIT repository via HTTP
892 'git-http-pull' [-c] [-t] [-a] [-v] commit-id url
896 Downloads a remote GIT repository via HTTP.
899 Get the commit objects.
901 Get trees associated with the commit objects.
905 Report what is downloaded.
910 git-init-db - Creates an empty git object database
918 This simply creates an empty git object database - basically a `.git`
919 directory and `.git/object/??/` directories.
921 If the object storage directory is specified via the 'SHA1_FILE_DIRECTORY'
922 environment variable then the sha1 directories are created underneath -
923 otherwise the default `.git/objects` directory is used.
925 "git-init-db" won't hurt an existing repository.
930 git-local-pull - Duplicates another GIT repository on a local system
934 'git-local-pull' [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path
938 Duplicates another GIT repository on a local system.
943 Get the commit objects.
945 Get trees associated with the commit objects.
949 Report what is downloaded.
953 git-ls-files - Information about files in the cache/working directory
957 'git-ls-files' [-z] [-t]
958 (--[cached|deleted|others|ignored|stage|unmerged])\*
960 [-x <pattern>|--exclude=<pattern>]
961 [-X <file>|--exclude-from=<file>]
965 This merges the file listing in the directory cache index with the
966 actual working directory list, and shows different combinations of the
969 One or more of the options below may be used to determine the files
975 Show cached files in the output (default)
978 Show deleted files in the output
981 Show other files in the output
984 Show ignored files in the output
985 Note the this also reverses any exclude list present.
988 Show stage files in the output
991 Show unmerged files in the output (forces --stage)
994 \0 line termination on output
996 -x|--exclude=<pattern>::
997 Skips files matching pattern.
998 Note that pattern is a shell wildcard pattern.
1000 -X|--exclude-from=<file>::
1001 exclude patterns are read from <file>; 1 per line.
1002 Allows the use of the famous dontdiff file as follows to find
1003 out about uncommitted files just as dontdiff is used with
1005 git-ls-files --others --exclude-from=dontdiff
1008 Identify the file status with the following tags (followed by
1009 a space) at the start of each line:
1017 show files just outputs the filename unless '--stage' is specified in
1018 which case it outputs:
1020 [<tag> ]<mode> <object> <stage> <file>
1022 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
1023 detailed information on unmerged paths.
1025 For an unmerged path, instead of recording a single mode/SHA1 pair,
1026 the dircache records up to three such pairs; one from tree O in stage
1027 1, A in stage 2, and B in stage 3. This information can be used by
1028 the user (or Cogito) to see what should eventually be recorded at the
1029 path. (see read-cache for more information on state)
1031 see also: link:read-cache.html[read-cache]
1036 git-ls-tree - Displays a tree object in human readable form
1040 'git-ls-tree' [-r] [-z] <tree-ish>
1044 Converts the tree object to a human readable (and script processable)
1053 recurse into sub-trees
1056 \0 line termination on output
1060 <mode>\t <type>\t <object>\t <file>
1065 git-merge-base - Finds as good a common ancestor as possible for a merge
1069 'git-merge-base' <commit> <commit>
1073 "git-merge-base" finds as good a common ancestor as possible. Given a
1074 selection of equally good common ancestors it should not be relied on
1075 to decide in any particular way.
1077 The "git-merge-base" algorithm is still in flux - use the source...
1082 git-merge-cache - Runs a merge for files needing merging
1086 'git-merge-cache' <merge-program> (-a | -- | <file>\*)
1090 This looks up the <file>(s) in the cache and, if there are any merge
1091 entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
1092 argument if no file), and <file> as argument 4. File modes for the three
1093 files are passed as arguments 5, 6 and 7.
1098 Interpret all future arguments as filenames.
1101 Run merge against all files in the cache that need merging.
1103 If "git-merge-cache" is called with multiple <file>s (or -a) then it
1104 processes them in turn only stopping if merge returns a non-zero exit
1107 Typically this is run with the a script calling the merge command from
1110 A sample script called "git-merge-one-file-script" is included in the
1113 ALERT ALERT ALERT! The git "merge object order" is different from the
1114 RCS "merge" program merge object order. In the above ordering, the
1115 original is first. But the argument order to the 3-way merge program
1116 "merge" is to have the original in the middle. Don't ask me why.
1120 torvalds@ppc970:~/merge-test> git-merge-cache cat MM
1121 This is MM from the original tree. # original
1122 This is modified MM in the branch A. # merge1
1123 This is modified MM in the branch B. # merge2
1124 This is modified MM in the branch B. # current contents
1128 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM
1129 cat: : No such file or directory
1130 This is added AA in the branch A.
1131 This is added AA in the branch B.
1132 This is added AA in the branch B.
1133 fatal: merge program failed
1135 where the latter example shows how "git-merge-cache" will stop trying to
1136 merge once anything has returned an error (ie "cat" returned an error
1137 for the AA file, because it didn't exist in the original, and thus
1138 "git-merge-cache" didn't even try to merge the MM thing).
1142 git-merge-one-file-script - The standard helper program to use with "git-merge-cache"
1146 'git-merge-one-file-script'
1150 This is the standard helper program to use with "git-merge-cache"
1151 to resolve a merge after the trivial merge done with "git-read-tree -m".
1155 git-mktag - Creates a tag object
1163 Reads a tag contents from its standard input and creates a tag object.
1164 The input must be a well formed tag object.
1169 git-prune-script - Prunes all unreachable objects from the object database
1177 This runs "git-fsck-cache --unreachable" program using the heads specified
1178 on the command line (or `.git/refs/heads/\*` and `.git/refs/tags/\*` if none is
1179 specified), and prunes all unreachable objects from the object database.
1184 git-pull-script - Script used by Linus to pull and merge a remote repository
1192 This script is used by Linus to pull from a remote repository and perform
1198 git-read-tree - Reads tree information into the directory cache
1202 'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"
1206 Reads the tree information given by <tree> into the directory cache,
1207 but does not actually _update_ any of the files it "caches". (see:
1210 Optionally, it can merge a tree into the cache or perform a 3-way
1213 Trivial merges are done by "git-read-tree" itself. Only conflicting paths
1214 will be in unmerged state when "git-read-tree" returns.
1219 Perform a merge, not just a read
1222 The id of the tree object(s) to be read/merged.
1227 If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree
1228 merge if only 1 tree is given or a 3-way merge if 3 trees are
1233 If only 1 tree is specified, git-read-tree operates as if the user did not
1234 specify '-m', except that if the original cache has an entry for a
1235 given pathname; and the contents of the path matches with the tree
1236 being read, the stat info from the cache is used. (In other words, the
1237 cache's stat()s take precedence over the merged tree's)
1239 That means that if you do a "git-read-tree -m <newtree>" followed by a
1240 "git-checkout-cache -f -a", the "git-checkout-cache" only checks out
1241 the stuff that really changed.
1243 This is used to avoid unnecessary false hits when "git-diff-files" is
1244 run after git-read-tree.
1248 Each "index" entry has two bits worth of "stage" state. stage 0 is the
1249 normal one, and is the only one you'd see in any kind of normal use.
1251 However, when you do "git-read-tree" with three trees, the "stage"
1254 This means that you can do
1256 git-read-tree -m <tree1> <tree2> <tree3>
1258 and you will end up with an index with all of the <tree1> entries in
1259 "stage1", all of the <tree2> entries in "stage2" and all of the
1260 <tree3> entries in "stage3".
1262 Furthermore, "git-read-tree" has special-case logic that says: if you see
1263 a file that matches in all respects in the following states, it
1264 "collapses" back to "stage0":
1266 - stage 2 and 3 are the same; take one or the other (it makes no
1267 difference - the same work has been done on stage 2 and 3)
1269 - stage 1 and stage 2 are the same and stage 3 is different; take
1270 stage 3 (some work has been done on stage 3)
1272 - stage 1 and stage 3 are the same and stage 2 is different take
1273 stage 2 (some work has been done on stage 2)
1275 The "git-write-tree" command refuses to write a nonsensical tree, and it
1276 will complain about unmerged entries if it sees a single entry that is not
1279 Ok, this all sounds like a collection of totally nonsensical rules,
1280 but it's actually exactly what you want in order to do a fast
1281 merge. The different stages represent the "result tree" (stage 0, aka
1282 "merged"), the original tree (stage 1, aka "orig"), and the two trees
1283 you are trying to merge (stage 2 and 3 respectively).
1285 In fact, the way "git-read-tree" works, it's entirely agnostic about how
1286 you assign the stages, and you could really assign them any which way,
1287 and the above is just a suggested way to do it (except since
1288 "git-write-tree" refuses to write anything but stage0 entries, it makes
1289 sense to always consider stage 0 to be the "full merge" state).
1291 So what happens? Try it out. Select the original tree, and two trees
1292 to merge, and look how it works:
1294 - if a file exists in identical format in all three trees, it will
1295 automatically collapse to "merged" state by the new git-read-tree.
1297 - a file that has _any_ difference what-so-ever in the three trees
1298 will stay as separate entries in the index. It's up to "script
1299 policy" to determine how to remove the non-0 stages, and insert a
1300 merged version. But since the index is always sorted, they're easy
1301 to find: they'll be clustered together.
1303 - the index file saves and restores with all this information, so you
1304 can merge things incrementally, but as long as it has entries in
1305 stages 1/2/3 (ie "unmerged entries") you can't write the result. So
1306 now the merge algorithm ends up being really simple:
1308 * you walk the index in order, and ignore all entries of stage 0,
1309 since they've already been done.
1311 * if you find a "stage1", but no matching "stage2" or "stage3", you
1312 know it's been removed from both trees (it only existed in the
1313 original tree), and you remove that entry.
1315 * if you find a matching "stage2" and "stage3" tree, you remove one
1316 of them, and turn the other into a "stage0" entry. Remove any
1317 matching "stage1" entry if it exists too. .. all the normal
1320 Incidentally - it also means that you don't even have to have a
1321 separate subdirectory for this. All the information literally is in
1322 the index file, which is a temporary thing anyway. There is no need to
1323 worry about what is in the working directory, since it is never shown
1326 see also: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files]
1331 git-resolve-script - Script used to merge two trees
1335 'git-resolve-script'
1339 This script is used by Linus to merge two trees.
1344 git-rev-list - Lists commit objects in reverse chronological order
1348 'git-rev-list' <commit>
1352 Lists commit objects in reverse chronological order starting at the
1353 given commit, taking ancestry relationship into account. This is
1354 useful to produce human-readable log output.
1359 git-rev-tree - Provides the revision tree for one or more commits
1363 'git-rev-tree' [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]
1367 Provides the revision tree for one or more commits.
1372 Show edges (ie places where the marking changes between parent
1375 --cache <cache-file>::
1376 Use the specified file as a cache from a previous git-rev-list run
1377 to speed things up. Note that this "cache" is totally different
1378 concept from the directory index. Also this option is not
1382 The commit id to trace (a leading caret means to ignore this
1383 commit-id and below)
1388 <date> <commit>:<flags> [<parent-commit>:<flags> ]\*
1391 Date in 'seconds since epoch'
1397 id of each parent commit object (>1 indicates a merge)
1401 The flags are read as a bitmask representing each commit
1402 provided on the commandline. eg: given the command:
1404 $ git-rev-tree <com1> <com2> <com3>
1410 means that <commit> is reachable from <com1>(1) and <com3>(4)
1412 A revtree can get quite large. "git-rev-tree" will eventually allow
1413 you to cache previous state so that you don't have to follow the whole
1416 So the change difference between two commits is literally
1418 git-rev-tree [commit-id1] > commit1-revtree
1419 git-rev-tree [commit-id2] > commit2-revtree
1420 join -t : commit1-revtree commit2-revtree > common-revisions
1422 (this is also how to find the most common parent - you'd look at just
1423 the head revisions - the ones that aren't referred to by other
1424 revisions - in "common-revision", and figure out the best one. I
1430 git-rpull - Pulls from a remote repository over ssh connection
1435 'git-rpull' [-c] [-t] [-a] [-v] commit-id url
1439 Pulls from a remote repository over ssh connection, invoking git-rpush on
1445 Get the commit objects.
1447 Get trees associated with the commit objects.
1449 Get all the objects.
1451 Report what is downloaded.
1456 git-rpush - Helper "server-side" program used by git-rpull
1464 Helper "server-side" program used by git-rpull.
1469 git-tag-script - An example script to create a tag object signed with GPG
1478 This is an example script that uses "git-mktag" to create a tag object
1484 git-tar-tree - Creates a tar archive of the files in the named tree
1488 'git-tar-tree' <tree-ish> [ <base> ]
1492 Creates a tar archive containing the tree structure for the named tree.
1493 When <base> is specified it is added as a leading path as the files in the
1494 generated tar archive.
1499 git-unpack-file - Creates a temporary file with a blob's contents
1504 'git-unpack-file' <blob>
1508 Creates a file holding the contents of the blob specified by sha1. It
1509 returns the name of the temporary file in the following format:
1519 git-update-cache - Modifies the index or directory cache
1524 [--add] [--remove] [--refresh] [--replace]
1526 [--force-remove <file>]
1527 [--cacheinfo <mode> <object> <file>]\*
1532 Modifies the index or directory cache. Each file mentioned is updated
1533 into the cache and any 'unmerged' or 'needs updating' state is
1536 The way "git-update-cache" handles files it is told about can be modified
1537 using the various options:
1542 If a specified file isn't in the cache already then it's
1544 Default behaviour is to ignore new files.
1547 If a specified file is in the cache but is missing then it's
1549 Default behaviour is to ignore removed file.
1552 Looks at the current cache and checks to see if merges or
1553 updates are needed by checking stat() information.
1556 Ignores missing files during a --refresh
1558 --cacheinfo <mode> <object> <path>::
1559 Directly insert the specified info into the cache.
1562 Remove the file from the index even when the working directory
1563 still has such a file.
1566 By default, when a file `path` exists in the index,
1567 git-update-cache refuses an attempt to add `path/file`.
1568 Similarly if a file `path/file` exists, a file `path`
1569 cannot be added. With --replace flag, existing entries
1570 that conflicts with the entry being added are
1571 automatically removed with warning messages.
1574 Do not interpret any more arguments as options.
1578 Note that files begining with '.' are discarded. This includes
1579 `./file` and `dir/./file`. If you don't want this, then use
1581 The same applies to directories ending '/' and paths with '//'
1585 '--refresh' does not calculate a new sha1 file or bring the cache
1586 up-to-date for mode/content changes. But what it *does* do is to
1587 "re-match" the stat information of a file with the cache, so that you
1588 can refresh the cache for a file that hasn't been changed but where
1589 the stat entry is out of date.
1591 For example, you'd want to do this after doing a "git-read-tree", to link
1592 up the stat cache details with the proper files.
1596 '--cacheinfo' is used to register a file that is not in the current
1597 working directory. This is useful for minimum-checkout merging.
1599 To pretend you have a file with mode and sha1 at path, say:
1601 $ git-update-cache --cacheinfo mode sha1 path
1603 To update and refresh only the files already checked out:
1605 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
1610 git-write-blob - Creates a blob from a file
1614 'git-write-blob' <any-file-on-the-filesystem>
1618 Writes the contents of the named file (which can be outside of the work
1619 tree) as a blob into the object database, and reports its object ID to its
1620 standard output. This is used by "git-merge-one-file-script" to update the
1621 cache without modifying files in the work tree.
1626 git-write-tree - Creates a tree from the current cache
1634 Creates a tree object using the current cache.
1636 The cache must be merged.
1638 Conceptually, "git-write-tree" sync()s the current directory cache contents
1639 into a set of tree files.
1640 In order to have that match what is actually in your directory right
1641 now, you need to have done a "git-update-cache" phase before you did the
1647 ////////////////////////////////////////////////////////////////
1649 Producing man pages and html
1651 To create a set of html pages run:
1652 perl split-docs.pl -html < core-git.txt
1654 To create a set of man pages run:
1655 perl split-docs.pl -man < core-git.txt
1658 ////////////////////////////////////////////////////////////////