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 - 'GIT_COMMITTER_NAME'
217 - 'GIT_COMMITTER_EMAIL'
219 - 'GIT_EXTERNAL_DIFF'
221 - 'GIT_OBJECT_DIRECTORY'
222 - 'GIT_ALTERNATE_OBJECT_DIRECTORIES'
227 git-apply-patch-script - Sample script to apply the diffs from git-diff-*
231 'git-apply-patch-script'
235 This is a sample script to be used via the 'GIT_EXTERNAL_DIFF'
236 environment variable to apply the differences that the "git-diff-*"
237 family of commands report to the current work tree.
242 git-cat-file - Provide content or type information for repository objects
246 'git-cat-file' (-t | <type>) <object>
250 Provides content or type of objects in the repository. The type
251 is required if '-t' is not being used to find the object type.
256 The sha1 identifier of the object.
259 Instead of the content, show the object type identified by
263 Typically this matches the real type of <object> but asking
264 for a type that can trivially dereferenced from the given
265 <object> is also permitted. An example is to ask for a
266 "tree" with <object> being a commit object that contains it,
267 or to ask for a "blob" with <object> being a tag object that
272 If '-t' is specified, one of the <type>.
274 Otherwise the raw (though uncompressed) contents of the <object> will
280 git-check-files - Verify a list of files are up-to-date
285 'git-check-files' <file>...
289 Check that a list of files are up-to-date between the filesystem and
290 the cache. Used to verify a patch target before doing a patch.
292 Files that do not exist on the filesystem are considered up-to-date
293 (whether or not they are in the cache).
295 Emits an error message on failure:
297 preparing to update existing file <file> not in cache::
298 <file> exists but is not in the cache
300 preparing to update file <file> not uptodate in cache::
301 <file> on disk is not up-to-date with the cache
303 Exits with a status code indicating success if all files are
306 see also: link:git-update-cache.html[git-update-cache]
311 git-checkout-cache - Copy files from the cache to the working directory
315 'git-checkout-cache' [-q] [-a] [-f] [-n] [--prefix=<string>]
320 Will copy all files listed from the cache to the working directory
321 (not overwriting existing files).
326 be quiet if files exist or are not in the cache
329 forces overwrite of existing files
332 checks out all files in the cache (will then continue to
333 process listed files).
336 Don't checkout new files, only refresh files already checked
340 When creating files, prepend <string> (usually a directory
341 including a trailing /)
344 Do not interpret any more arguments as options.
346 Note that the order of the flags matters:
348 git-checkout-cache -a -f file.c
350 will first check out all files listed in the cache (but not overwrite
351 any old ones), and then force-checkout `file.c` a second time (ie that
352 one *will* overwrite any old contents with the same filename).
354 Also, just doing "git-checkout-cache" does nothing. You probably meant
355 "git-checkout-cache -a". And if you want to force it, you want
356 "git-checkout-cache -f -a".
358 Intuitiveness is not the goal here. Repeatability is. The reason for
359 the "no arguments means no work" thing is that from scripts you are
360 supposed to be able to do things like:
362 find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f --
364 which will force all existing `*.h` files to be replaced with their
365 cached copies. If an empty command line implied "all", then this would
366 force-refresh everything in the cache, which was not the point.
368 To update and refresh only the files already checked out:
370 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
372 Oh, and the "--" is just a good idea when you know the rest will be
373 filenames. Just so that you wouldn't have a filename of "-a" causing
374 problems (not possible in the above example, but get used to it in
377 The prefix ability basically makes it trivial to use
378 git-checkout-cache as an "export as tree" function. Just read the
379 desired tree into the index, and do a
381 git-checkout-cache --prefix=git-export-dir/ -a
383 and git-checkout-cache will "export" the cache into the specified
386 NOTE The final "/" is important. The exported name is literally just
387 prefixed with the specified string, so you can also do something like
389 git-checkout-cache --prefix=.merged- Makefile
391 to check out the currently cached copy of `Makefile` into the file
396 git-commit-tree - Creates a new commit object
400 'git-commit-tree' <tree> [-p <parent commit>]\ < changelog
404 Creates a new commit object based on the provided tree object and
405 emits the new commit object id on stdout. If no parent is given then
406 it is considered to be an initial tree.
408 A commit object usually has 1 parent (a commit after a change) or up
409 to 16 parents. More than one parent represents a merge of branches
412 While a tree represents a particular directory state of a working
413 directory, a commit represents that state in "time", and explains how
416 Normally a commit would identify a new "HEAD" state, and while git
417 doesn't care where you save the note about that state, in practice we
418 tend to just write the result to the file `.git/HEAD`, so that we can
419 always see what the last committed state was.
424 An existing tree object
427 Each '-p' indicates a the id of a parent commit object.
433 A commit encapsulates:
435 - all parent object ids
436 - author name, email and date
437 - committer name and email and the commit time.
439 If not provided, "git-commit-tree" uses your name, hostname and domain to
440 provide author and committer info. This can be overridden using the
441 following environment variables.
449 (nb <,> and '\n's are stripped)
451 A commit comment is read from stdin (max 999 chars). If a changelog
452 entry is not provided via '<' redirection, "git-commit-tree" will just wait
453 for one to be entered and terminated with ^D
455 see also: link:git-write-tree.html[git-write-tree]
460 git-convert-cache - Converts old-style GIT repository
468 Converts old-style GIT repository to the latest format
473 git-diff-cache - Compares content and mode of blobs between the cache and repository
477 'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish>
481 Compares the content and mode of the blobs found via a tree object
482 with the content of the current cache and, optionally ignoring the
483 stat state of the file on disk.
488 The id of a tree object to diff against.
491 Generate patch (see section on generating patches)
494 This flag does not mean anything. It is there only to match
495 "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache"
496 always looks at all the subdirectories.
499 \0 line termination on output
502 do not consider the on-disk file at all
505 By default, files recorded in the index but not checked
506 out are reported as deleted. This flag makes
507 "git-diff-cache" say that all non-checked-out files are up
512 include::diff-format.txt[]
516 You can choose whether you want to trust the index file entirely
517 (using the '--cached' flag) or ask the diff logic to show any files
518 that don't match the stat state as being "tentatively changed". Both
519 of these operations are very useful indeed.
523 If '--cached' is specified, it allows you to ask:
525 show me the differences between HEAD and the current index
526 contents (the ones I'd write with a "git-write-tree")
528 For example, let's say that you have worked on your index file, and are
529 ready to commit. You want to see eactly *what* you are going to commit is
530 without having to write a new tree object and compare it that way, and to
533 git-diff-cache --cached $(cat .git/HEAD)
535 Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
536 done an "git-update-cache" to make that effective in the index file.
537 "git-diff-files" wouldn't show anything at all, since the index file
538 matches my working directory. But doing a "git-diff-cache" does:
540 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)
541 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c
542 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c
544 You can trivially see that the above is a rename.
546 In fact, "git-diff-cache --cached" *should* always be entirely equivalent to
547 actually doing a "git-write-tree" and comparing that. Except this one is much
548 nicer for the case where you just want to check where you are.
550 So doing a "git-diff-cache --cached" is basically very useful when you are
551 asking yourself "what have I already marked for being committed, and
552 what's the difference to a previous tree".
556 The "non-cached" mode takes a different approach, and is potentially
557 the more useful of the two in that what it does can't be emulated with
558 a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
559 The non-cached version asks the question:
561 show me the differences between HEAD and the currently checked out
562 tree - index contents _and_ files that aren't up-to-date
564 which is obviously a very useful question too, since that tells you what
565 you *could* commit. Again, the output matches the "git-diff-tree -r"
566 output to a tee, but with a twist.
568 The twist is that if some file doesn't match the cache, we don't have
569 a backing store thing for it, and we use the magic "all-zero" sha1 to
570 show that. So let's say that you have edited `kernel/sched.c`, but
571 have not actually done a "git-update-cache" on it yet - there is no
572 "object" associated with the new state, and you get:
574 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )
575 *100644->100664 blob 7476bb......->000000...... kernel/sched.c
577 ie it shows that the tree has changed, and that `kernel/sched.c` has is
578 not up-to-date and may contain new stuff. The all-zero sha1 means that to
579 get the real diff, you need to look at the object in the working directory
580 directly rather than do an object-to-object diff.
582 NOTE! As with other commands of this type, "git-diff-cache" does not
583 actually look at the contents of the file at all. So maybe
584 `kernel/sched.c` hasn't actually changed, and it's just that you
585 touched it. In either case, it's a note that you need to
586 "git-upate-cache" it to make the cache be in sync.
588 NOTE 2! You can have a mixture of files show up as "has been updated"
589 and "is still dirty in the working directory" together. You can always
590 tell which file is in which state, since the "has been updated" ones
591 show a valid sha1, and the "not in sync with the index" ones will
592 always have the special all-zero sha1.
597 git-diff-files - Compares files in the working tree and the cache
601 'git-diff-files' [-p] [-q] [-r] [-z] [<pattern>...]
605 Compares the files in the working tree and the cache. When paths
606 are specified, compares only those named paths. Otherwise all
607 entries in the cache are compared. The output format is the
608 same as "git-diff-cache" and "git-diff-tree".
613 generate patch (see section on generating patches).
616 Remain silent even on nonexisting files
619 This flag does not mean anything. It is there only to match
620 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks
621 at all the subdirectories.
626 include::diff-format.txt[]
631 git-diff-tree - Compares the content and mode of blobs found via two tree objects
635 'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]\*
639 Compares the content and mode of the blobs found via two tree objects.
641 Note that "git-diff-tree" can use the tree encapsulated in a commit object.
646 The id of a tree object.
649 If provided, the results are limited to a subset of files
650 matching one of these prefix strings.
651 ie file matches `/^<pattern1>|<pattern2>|.../`
652 Note that pattern does not provide any wildcard or regexp
656 generate patch (see section on generating patches). For
657 git-diff-tree, this flag implies '-r' as well.
663 \0 line termination on output
666 When '--stdin' is specified, the command does not take
667 <tree-ish> arguments from the command line. Instead, it
668 reads either one <commit> or a pair of <tree-ish>
669 separated with a single space from its standard input.
671 When a single commit is given on one line of such input, it compares
672 the commit with its parents. The following flags further affects its
673 behaviour. This does not apply to the case where two <tree-ish>
674 separated with a single space are given.
677 By default, "git-diff-tree --stdin" does not show
678 differences for merge commits. With this flag, it shows
679 differences to that commit from all of its parents.
682 By default, "git-diff-tree --stdin" shows differences,
683 either in machine-readable form (without '-p') or in patch
684 form (with '-p'). This output can be supressed. It is
685 only useful with '-v' flag.
688 This flag causes "git-diff-tree --stdin" to also show
689 the commit message before the differences.
694 If you're only interested in differences in a subset of files, for
695 example some architecture-specific files, you might do:
697 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
699 and it will only show you what changed in those two directories.
701 Or if you are searching for what changed in just `kernel/sched.c`, just do
703 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
705 and it will ignore all differences to other files.
707 The pattern is always the prefix, and is matched exactly. There are no
708 wildcards. Even stricter, it has to match complete path comonent.
709 I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h`
710 so it can be used to name subdirectories.
712 An example of normal usage is:
714 torvalds@ppc970:~/git> git-diff-tree 5319e4......
715 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c
717 which tells you that the last commit changed just one file (it's from
720 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
721 tree 5319e4d609cdd282069cc4dce33c1db559539b03
722 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
723 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
724 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
726 Make "git-fsck-cache" print out all the root commits it finds.
728 Once I do the reference tracking, I'll also make it print out all the
729 HEAD commits it finds, which is even more interesting.
735 include::diff-format.txt[]
740 git-diff-tree-helper - Generates patch format output for git-diff-*
744 'git-diff-tree-helper' [-z] [-R]
748 Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and
749 generates patch format output.
754 \0 line termination on input
757 Output diff in reverse. This is useful for displaying output from
758 "git-diff-cache" which always compares tree with cache or working
761 git-diff-cache <tree> | git-diff-tree-helper -R file.c
763 would show a diff to bring the working file back to what is in the <tree>.
765 See also the section on generating patches in link:git-diff-cache.html[git-diff-cache]
770 git-export - Exports each commit and a diff against each of its parents
774 'git-export' top [base]
778 Exports each commit and diff against each of its parents, between
779 top and base. If base is not specified it exports everything.
784 git-fsck-cache - Verifies the connectivity and validity of the objects in the database
788 'git-fsck-cache' [--tags] [--root] [[--unreachable] [--cache] <object>\*]
792 Verifies the connectivity and validity of the objects in the database.
797 An object to treat as the head of an unreachability trace.
800 Print out objects that exist but that aren't readable from any
801 of the specified head nodes.
810 Consider any object recorded in the cache also as a head node for
811 an unreachability trace.
813 It tests SHA1 and general object sanity, and it does full tracking of
814 the resulting reachability and everything else. It prints out any
815 corruption it finds (missing or bad objects), and if you use the
816 '--unreachable' flag it will also print out objects that exist but
817 that aren't readable from any of the specified head nodes.
821 git-fsck-cache --unreachable $(cat .git/HEAD)
823 or, for Cogito users:
825 git-fsck-cache --unreachable $(cat .git/refs/heads/*)
827 will do quite a _lot_ of verification on the tree. There are a few
828 extra validity tests to be added (make sure that tree objects are
829 sorted properly etc), but on the whole if "git-fsck-cache" is happy, you
830 do have a valid tree.
832 Any corrupt objects you will have to find in backups or other archives
833 (ie you can just remove them and do an "rsync" with some other site in
834 the hopes that somebody else has the object you have corrupted).
836 Of course, "valid tree" doesn't mean that it wasn't generated by some
837 evil person, and the end result might be crap. Git is a revision
838 tracking system, not a quality assurance system ;)
840 Extracted Diagnostics
841 ---------------------
843 expect dangling commits - potential heads - due to lack of head information::
844 You haven't specified any nodes as heads so it won't be
845 possible to differentiate between un-parented commits and
848 missing sha1 directory '<dir>'::
849 The directory holding the sha1 objects is missing.
851 unreachable <type> <object>::
852 The <type> object <object>, isn't actually referred to directly
853 or indirectly in any of the trees or commits seen. This can
854 mean that there's another root node that you're not specifying
855 or that the tree is corrupt. If you haven't missed a root node
856 then you might as well delete unreachable nodes since they
859 missing <type> <object>::
860 The <type> object <object>, is referred to but isn't present in
863 dangling <type> <object>::
864 The <type> object <object>, is present in the database but never
865 'directly' used. A dangling commit could be a root node.
867 warning: git-fsck-cache: tree <tree> has full pathnames in it::
870 sha1 mismatch <object>::
871 The database has an object who's sha1 doesn't match the
873 This indicates a serious data integrity problem.
874 (note: this error occured during early git development when
875 the database format changed.)
877 Environment Variables
878 ---------------------
880 GIT_OBJECT_DIRECTORY::
881 used to specify the object database root (usually .git/objects)
884 used to specify the cache
889 git-http-pull - Downloads a remote GIT repository via HTTP
893 'git-http-pull' [-c] [-t] [-a] [-v] commit-id url
897 Downloads a remote GIT repository via HTTP.
900 Get the commit objects.
902 Get trees associated with the commit objects.
906 Report what is downloaded.
911 git-init-db - Creates an empty git object database
919 This simply creates an empty git object database - basically a `.git`
920 directory and `.git/object/??/` directories.
922 If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY'
923 environment variable then the sha1 directories are created underneath -
924 otherwise the default `.git/objects` directory is used.
926 "git-init-db" won't hurt an existing repository.
931 git-local-pull - Duplicates another GIT repository on a local system
935 'git-local-pull' [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path
939 Duplicates another GIT repository on a local system.
944 Get the commit objects.
946 Get trees associated with the commit objects.
950 Report what is downloaded.
954 git-ls-files - Information about files in the cache/working directory
958 'git-ls-files' [-z] [-t]
959 (--[cached|deleted|others|ignored|stage|unmerged])\*
961 [-x <pattern>|--exclude=<pattern>]
962 [-X <file>|--exclude-from=<file>]
966 This merges the file listing in the directory cache index with the
967 actual working directory list, and shows different combinations of the
970 One or more of the options below may be used to determine the files
976 Show cached files in the output (default)
979 Show deleted files in the output
982 Show other files in the output
985 Show ignored files in the output
986 Note the this also reverses any exclude list present.
989 Show stage files in the output
992 Show unmerged files in the output (forces --stage)
995 \0 line termination on output
997 -x|--exclude=<pattern>::
998 Skips files matching pattern.
999 Note that pattern is a shell wildcard pattern.
1001 -X|--exclude-from=<file>::
1002 exclude patterns are read from <file>; 1 per line.
1003 Allows the use of the famous dontdiff file as follows to find
1004 out about uncommitted files just as dontdiff is used with
1006 git-ls-files --others --exclude-from=dontdiff
1009 Identify the file status with the following tags (followed by
1010 a space) at the start of each line:
1018 show files just outputs the filename unless '--stage' is specified in
1019 which case it outputs:
1021 [<tag> ]<mode> <object> <stage> <file>
1023 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
1024 detailed information on unmerged paths.
1026 For an unmerged path, instead of recording a single mode/SHA1 pair,
1027 the dircache records up to three such pairs; one from tree O in stage
1028 1, A in stage 2, and B in stage 3. This information can be used by
1029 the user (or Cogito) to see what should eventually be recorded at the
1030 path. (see read-cache for more information on state)
1032 see also: link:read-cache.html[read-cache]
1037 git-ls-tree - Displays a tree object in human readable form
1041 'git-ls-tree' [-r] [-z] <tree-ish>
1045 Converts the tree object to a human readable (and script processable)
1054 recurse into sub-trees
1057 \0 line termination on output
1061 <mode>\t <type>\t <object>\t <file>
1066 git-merge-base - Finds as good a common ancestor as possible for a merge
1070 'git-merge-base' <commit> <commit>
1074 "git-merge-base" finds as good a common ancestor as possible. Given a
1075 selection of equally good common ancestors it should not be relied on
1076 to decide in any particular way.
1078 The "git-merge-base" algorithm is still in flux - use the source...
1083 git-merge-cache - Runs a merge for files needing merging
1087 'git-merge-cache' <merge-program> (-a | -- | <file>\*)
1091 This looks up the <file>(s) in the cache and, if there are any merge
1092 entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
1093 argument if no file), and <file> as argument 4. File modes for the three
1094 files are passed as arguments 5, 6 and 7.
1099 Interpret all future arguments as filenames.
1102 Run merge against all files in the cache that need merging.
1104 If "git-merge-cache" is called with multiple <file>s (or -a) then it
1105 processes them in turn only stopping if merge returns a non-zero exit
1108 Typically this is run with the a script calling the merge command from
1111 A sample script called "git-merge-one-file-script" is included in the
1114 ALERT ALERT ALERT! The git "merge object order" is different from the
1115 RCS "merge" program merge object order. In the above ordering, the
1116 original is first. But the argument order to the 3-way merge program
1117 "merge" is to have the original in the middle. Don't ask me why.
1121 torvalds@ppc970:~/merge-test> git-merge-cache cat MM
1122 This is MM from the original tree. # original
1123 This is modified MM in the branch A. # merge1
1124 This is modified MM in the branch B. # merge2
1125 This is modified MM in the branch B. # current contents
1129 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM
1130 cat: : No such file or directory
1131 This is added AA in the branch A.
1132 This is added AA in the branch B.
1133 This is added AA in the branch B.
1134 fatal: merge program failed
1136 where the latter example shows how "git-merge-cache" will stop trying to
1137 merge once anything has returned an error (ie "cat" returned an error
1138 for the AA file, because it didn't exist in the original, and thus
1139 "git-merge-cache" didn't even try to merge the MM thing).
1143 git-merge-one-file-script - The standard helper program to use with "git-merge-cache"
1147 'git-merge-one-file-script'
1151 This is the standard helper program to use with "git-merge-cache"
1152 to resolve a merge after the trivial merge done with "git-read-tree -m".
1156 git-mktag - Creates a tag object
1164 Reads a tag contents from its standard input and creates a tag object.
1165 The input must be a well formed tag object.
1170 git-prune-script - Prunes all unreachable objects from the object database
1178 This runs "git-fsck-cache --unreachable" program using the heads specified
1179 on the command line (or `.git/refs/heads/\*` and `.git/refs/tags/\*` if none is
1180 specified), and prunes all unreachable objects from the object database.
1185 git-pull-script - Script used by Linus to pull and merge a remote repository
1193 This script is used by Linus to pull from a remote repository and perform
1199 git-read-tree - Reads tree information into the directory cache
1203 'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"
1207 Reads the tree information given by <tree> into the directory cache,
1208 but does not actually _update_ any of the files it "caches". (see:
1211 Optionally, it can merge a tree into the cache or perform a 3-way
1214 Trivial merges are done by "git-read-tree" itself. Only conflicting paths
1215 will be in unmerged state when "git-read-tree" returns.
1220 Perform a merge, not just a read
1223 The id of the tree object(s) to be read/merged.
1228 If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree
1229 merge if only 1 tree is given or a 3-way merge if 3 trees are
1234 If only 1 tree is specified, git-read-tree operates as if the user did not
1235 specify '-m', except that if the original cache has an entry for a
1236 given pathname; and the contents of the path matches with the tree
1237 being read, the stat info from the cache is used. (In other words, the
1238 cache's stat()s take precedence over the merged tree's)
1240 That means that if you do a "git-read-tree -m <newtree>" followed by a
1241 "git-checkout-cache -f -a", the "git-checkout-cache" only checks out
1242 the stuff that really changed.
1244 This is used to avoid unnecessary false hits when "git-diff-files" is
1245 run after git-read-tree.
1249 Each "index" entry has two bits worth of "stage" state. stage 0 is the
1250 normal one, and is the only one you'd see in any kind of normal use.
1252 However, when you do "git-read-tree" with three trees, the "stage"
1255 This means that you can do
1257 git-read-tree -m <tree1> <tree2> <tree3>
1259 and you will end up with an index with all of the <tree1> entries in
1260 "stage1", all of the <tree2> entries in "stage2" and all of the
1261 <tree3> entries in "stage3".
1263 Furthermore, "git-read-tree" has special-case logic that says: if you see
1264 a file that matches in all respects in the following states, it
1265 "collapses" back to "stage0":
1267 - stage 2 and 3 are the same; take one or the other (it makes no
1268 difference - the same work has been done on stage 2 and 3)
1270 - stage 1 and stage 2 are the same and stage 3 is different; take
1271 stage 3 (some work has been done on stage 3)
1273 - stage 1 and stage 3 are the same and stage 2 is different take
1274 stage 2 (some work has been done on stage 2)
1276 The "git-write-tree" command refuses to write a nonsensical tree, and it
1277 will complain about unmerged entries if it sees a single entry that is not
1280 Ok, this all sounds like a collection of totally nonsensical rules,
1281 but it's actually exactly what you want in order to do a fast
1282 merge. The different stages represent the "result tree" (stage 0, aka
1283 "merged"), the original tree (stage 1, aka "orig"), and the two trees
1284 you are trying to merge (stage 2 and 3 respectively).
1286 In fact, the way "git-read-tree" works, it's entirely agnostic about how
1287 you assign the stages, and you could really assign them any which way,
1288 and the above is just a suggested way to do it (except since
1289 "git-write-tree" refuses to write anything but stage0 entries, it makes
1290 sense to always consider stage 0 to be the "full merge" state).
1292 So what happens? Try it out. Select the original tree, and two trees
1293 to merge, and look how it works:
1295 - if a file exists in identical format in all three trees, it will
1296 automatically collapse to "merged" state by the new git-read-tree.
1298 - a file that has _any_ difference what-so-ever in the three trees
1299 will stay as separate entries in the index. It's up to "script
1300 policy" to determine how to remove the non-0 stages, and insert a
1301 merged version. But since the index is always sorted, they're easy
1302 to find: they'll be clustered together.
1304 - the index file saves and restores with all this information, so you
1305 can merge things incrementally, but as long as it has entries in
1306 stages 1/2/3 (ie "unmerged entries") you can't write the result. So
1307 now the merge algorithm ends up being really simple:
1309 * you walk the index in order, and ignore all entries of stage 0,
1310 since they've already been done.
1312 * if you find a "stage1", but no matching "stage2" or "stage3", you
1313 know it's been removed from both trees (it only existed in the
1314 original tree), and you remove that entry.
1316 * if you find a matching "stage2" and "stage3" tree, you remove one
1317 of them, and turn the other into a "stage0" entry. Remove any
1318 matching "stage1" entry if it exists too. .. all the normal
1321 Incidentally - it also means that you don't even have to have a
1322 separate subdirectory for this. All the information literally is in
1323 the index file, which is a temporary thing anyway. There is no need to
1324 worry about what is in the working directory, since it is never shown
1327 see also: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files]
1332 git-resolve-script - Script used to merge two trees
1336 'git-resolve-script'
1340 This script is used by Linus to merge two trees.
1345 git-rev-list - Lists commit objects in reverse chronological order
1349 'git-rev-list' <commit>
1353 Lists commit objects in reverse chronological order starting at the
1354 given commit, taking ancestry relationship into account. This is
1355 useful to produce human-readable log output.
1360 git-rev-tree - Provides the revision tree for one or more commits
1364 'git-rev-tree' [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]
1368 Provides the revision tree for one or more commits.
1373 Show edges (ie places where the marking changes between parent
1376 --cache <cache-file>::
1377 Use the specified file as a cache from a previous git-rev-list run
1378 to speed things up. Note that this "cache" is totally different
1379 concept from the directory index. Also this option is not
1383 The commit id to trace (a leading caret means to ignore this
1384 commit-id and below)
1389 <date> <commit>:<flags> [<parent-commit>:<flags> ]\*
1392 Date in 'seconds since epoch'
1398 id of each parent commit object (>1 indicates a merge)
1402 The flags are read as a bitmask representing each commit
1403 provided on the commandline. eg: given the command:
1405 $ git-rev-tree <com1> <com2> <com3>
1411 means that <commit> is reachable from <com1>(1) and <com3>(4)
1413 A revtree can get quite large. "git-rev-tree" will eventually allow
1414 you to cache previous state so that you don't have to follow the whole
1417 So the change difference between two commits is literally
1419 git-rev-tree [commit-id1] > commit1-revtree
1420 git-rev-tree [commit-id2] > commit2-revtree
1421 join -t : commit1-revtree commit2-revtree > common-revisions
1423 (this is also how to find the most common parent - you'd look at just
1424 the head revisions - the ones that aren't referred to by other
1425 revisions - in "common-revision", and figure out the best one. I
1431 git-rpull - Pulls from a remote repository over ssh connection
1436 'git-rpull' [-c] [-t] [-a] [-v] commit-id url
1440 Pulls from a remote repository over ssh connection, invoking git-rpush on
1446 Get the commit objects.
1448 Get trees associated with the commit objects.
1450 Get all the objects.
1452 Report what is downloaded.
1457 git-rpush - Helper "server-side" program used by git-rpull
1465 Helper "server-side" program used by git-rpull.
1470 git-tag-script - An example script to create a tag object signed with GPG
1479 This is an example script that uses "git-mktag" to create a tag object
1485 git-tar-tree - Creates a tar archive of the files in the named tree
1489 'git-tar-tree' <tree-ish> [ <base> ]
1493 Creates a tar archive containing the tree structure for the named tree.
1494 When <base> is specified it is added as a leading path as the files in the
1495 generated tar archive.
1500 git-unpack-file - Creates a temporary file with a blob's contents
1505 'git-unpack-file' <blob>
1509 Creates a file holding the contents of the blob specified by sha1. It
1510 returns the name of the temporary file in the following format:
1520 git-update-cache - Modifies the index or directory cache
1525 [--add] [--remove] [--refresh] [--replace]
1527 [--force-remove <file>]
1528 [--cacheinfo <mode> <object> <file>]\*
1533 Modifies the index or directory cache. Each file mentioned is updated
1534 into the cache and any 'unmerged' or 'needs updating' state is
1537 The way "git-update-cache" handles files it is told about can be modified
1538 using the various options:
1543 If a specified file isn't in the cache already then it's
1545 Default behaviour is to ignore new files.
1548 If a specified file is in the cache but is missing then it's
1550 Default behaviour is to ignore removed file.
1553 Looks at the current cache and checks to see if merges or
1554 updates are needed by checking stat() information.
1557 Ignores missing files during a --refresh
1559 --cacheinfo <mode> <object> <path>::
1560 Directly insert the specified info into the cache.
1563 Remove the file from the index even when the working directory
1564 still has such a file.
1567 By default, when a file `path` exists in the index,
1568 git-update-cache refuses an attempt to add `path/file`.
1569 Similarly if a file `path/file` exists, a file `path`
1570 cannot be added. With --replace flag, existing entries
1571 that conflicts with the entry being added are
1572 automatically removed with warning messages.
1575 Do not interpret any more arguments as options.
1579 Note that files begining with '.' are discarded. This includes
1580 `./file` and `dir/./file`. If you don't want this, then use
1582 The same applies to directories ending '/' and paths with '//'
1586 '--refresh' does not calculate a new sha1 file or bring the cache
1587 up-to-date for mode/content changes. But what it *does* do is to
1588 "re-match" the stat information of a file with the cache, so that you
1589 can refresh the cache for a file that hasn't been changed but where
1590 the stat entry is out of date.
1592 For example, you'd want to do this after doing a "git-read-tree", to link
1593 up the stat cache details with the proper files.
1597 '--cacheinfo' is used to register a file that is not in the current
1598 working directory. This is useful for minimum-checkout merging.
1600 To pretend you have a file with mode and sha1 at path, say:
1602 $ git-update-cache --cacheinfo mode sha1 path
1604 To update and refresh only the files already checked out:
1606 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
1611 git-write-blob - Creates a blob from a file
1615 'git-write-blob' <any-file-on-the-filesystem>
1619 Writes the contents of the named file (which can be outside of the work
1620 tree) as a blob into the object database, and reports its object ID to its
1621 standard output. This is used by "git-merge-one-file-script" to update the
1622 cache without modifying files in the work tree.
1627 git-write-tree - Creates a tree from the current cache
1635 Creates a tree object using the current cache.
1637 The cache must be merged.
1639 Conceptually, "git-write-tree" sync()s the current directory cache contents
1640 into a set of tree files.
1641 In order to have that match what is actually in your directory right
1642 now, you need to have done a "git-update-cache" phase before you did the
1648 ////////////////////////////////////////////////////////////////
1650 Producing man pages and html
1652 To create a set of html pages run:
1653 perl split-docs.pl -html < core-git.txt
1655 To create a set of man pages run:
1656 perl split-docs.pl -man < core-git.txt
1659 ////////////////////////////////////////////////////////////////