Code

7d3b09fd28790dc9a3a164d91e54cf17aa1470f3
[git.git] / Documentation / core-git.txt
1 This file contains reference information for the core git commands.
3 The README contains much useful definition and clarification
4 info - read that first.  And of the commands, I suggest reading
5 'git-update-cache' and 'git-read-tree' first - I wish I had!
7 David Greaves <david@dgreaves.com>
8 24/4/05
10 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
11 reflect recent changes.
13 Identifier terminology used:
15 <object>
16         Indicates any object sha1 identifier
18 <blob>
19         Indicates a blob object sha1 identifier
21 <tree>
22         Indicates a tree object sha1 identifier
24 <commit>
25         Indicates a commit object sha1 identifier
27 <tree-ish>
28         Indicates a tree, commit or tag object sha1 identifier.
29         A command that takes a <tree-ish> argument ultimately
30         wants to operate on a <tree> object but automatically
31         dereferences <commit> and <tag> that points at a
32         <tree>.
34 <type>
35         Indicates that an object type is required.
36         Currently one of: blob/tree/commit/tag
38 <file>
39         Indicates a filename - always relative to the root of
40         the tree structure GIT_INDEX_FILE describes.
43 ################################################################
44 git-apply-patch-script
46 This is a sample script to be used as GIT_EXTERNAL_DIFF to apply
47 differences git-diff-* family of commands reports to the current
48 work tree.
51 ################################################################
52 git-cat-file
53         git-cat-file (-t | <type>) <object>
55 Provides contents or type of objects in the repository. The type
56 is required if -t is not being used to find the object type.
58 <object>
59         The sha1 identifier of the object.
61 -t
62         Instead of the content, show the object type identified
63         by <object>.
65 <type>
66         Typically this matches the real type of <object> but
67         asking for type that can trivially dereferenced from the
68         given <object> is also permitted.  An example is to ask
69         "tree" with <object> for a commit object that contains
70         it, or to ask "blob" with <object> for a tag object that
71         points at it.
73 Output
75 If -t is specified, one of the <type>.
77 Otherwise the raw (though uncompressed) contents of the <object> will
78 be returned.
81 ################################################################
82 git-check-files
83         git-check-files <file>...
85 Check that a list of files are up-to-date between the filesystem and
86 the cache. Used to verify a patch target before doing a patch.
88 Files that do not exist on the filesystem are considered up-to-date
89 (whether or not they are in the cache).
91 Emits an error message on failure.
92 preparing to update existing file <file> not in cache
93           <file> exists but is not in the cache
95 preparing to update file <file> not uptodate in cache
96           <file> on disk is not up-to-date with the cache
98 Exits with a status code indicating success if all files are
99 up-to-date.
101 see also: git-update-cache
104 ################################################################
105 git-checkout-cache
106         git-checkout-cache [-q] [-a] [-f] [-n] [--prefix=<string>]
107                            [--] <file>...
109 Will copy all files listed from the cache to the working directory
110 (not overwriting existing files).
112 -q
113         be quiet if files exist or are not in the cache
115 -f
116         forces overwrite of existing files
118 -a
119         checks out all files in the cache (will then continue to
120         process listed files).
122 -n
123         Don't checkout new files, only refresh files already checked
124         out.
126 --prefix=<string>
127         When creating files, prepend <string> (usually a directory
128         including a trailing /)
130 --
131         Do not interpret any more arguments as options.
133 Note that the order of the flags matters:
135         git-checkout-cache -a -f file.c
137 will first check out all files listed in the cache (but not overwrite
138 any old ones), and then force-checkout file.c a second time (ie that
139 one _will_ overwrite any old contents with the same filename).
141 Also, just doing "git-checkout-cache" does nothing. You probably meant
142 "git-checkout-cache -a". And if you want to force it, you want
143 "git-checkout-cache -f -a".
145 Intuitiveness is not the goal here. Repeatability is. The reason for
146 the "no arguments means no work" thing is that from scripts you are
147 supposed to be able to do things like
149         find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f --
151 which will force all existing *.h files to be replaced with their
152 cached copies. If an empty command line implied "all", then this would
153 force-refresh everything in the cache, which was not the point.
155 To update and refresh only the files already checked out:
157    git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
159 Oh, and the "--" is just a good idea when you know the rest will be
160 filenames. Just so that you wouldn't have a filename of "-a" causing
161 problems (not possible in the above example, but get used to it in
162 scripting!).
164 The prefix ability basically makes it trivial to use
165 git-checkout-cache as an "export as tree" function. Just read the
166 desired tree into the index, and do a
167   
168         git-checkout-cache --prefix=git-export-dir/ -a
169   
170 and git-checkout-cache will "export" the cache into the specified
171 directory.
172   
173 NOTE! The final "/" is important. The exported name is literally just
174 prefixed with the specified string, so you can also do something like
175   
176         git-checkout-cache --prefix=.merged- Makefile
177   
178 to check out the currently cached copy of "Makefile" into the file
179 ".merged-Makefile".
182 ################################################################
183 git-commit-tree
184         git-commit-tree <tree> [-p <parent commit>]*   < changelog
186 Creates a new commit object based on the provided tree object and
187 emits the new commit object id on stdout. If no parent is given then
188 it is considered to be an initial tree.
190 A commit object usually has 1 parent (a commit after a change) or up
191 to 16 parents.  More than one parent represents a merge of branches
192 that led to them.
194 While a tree represents a particular directory state of a working
195 directory, a commit represents that state in "time", and explains how
196 to get there.
198 Normally a commit would identify a new "HEAD" state, and while git
199 doesn't care where you save the note about that state, in practice we
200 tend to just write the result to the file ".git/HEAD", so that we can
201 always see what the last committed state was.
203 Options
205 <tree>
206         An existing tree object
208 -p <parent commit>
209         Each -p indicates a the id of a parent commit object.
210         
212 Commit Information
214 A commit encapsulates:
215         all parent object ids
216         author name, email and date
217         committer name and email and the commit time.
219 If not provided, git-commit-tree uses your name, hostname and domain to
220 provide author and committer info. This can be overridden using the
221 following environment variables.
222         AUTHOR_NAME
223         AUTHOR_EMAIL
224         AUTHOR_DATE
225         COMMIT_AUTHOR_NAME
226         COMMIT_AUTHOR_EMAIL
227 (nb <,> and '\n's are stripped)
229 A commit comment is read from stdin (max 999 chars). If a changelog
230 entry is not provided via '<' redirection, git-commit-tree will just wait
231 for one to be entered and terminated with ^D
233 see also: git-write-tree
236 ################################################################
237 git-convert-cache
239 Converts old-style GIT repository to the latest.
242 ################################################################
243 git-diff-cache
244         git-diff-cache [-p] [-r] [-z] [-m] [--cached] <tree-ish>
246 Compares the content and mode of the blobs found via a tree object
247 with the content of the current cache and, optionally ignoring the
248 stat state of the file on disk.
250 <tree-ish>
251         The id of a tree object to diff against.
253 -p
254         Generate patch (see section on generating patches)
256 -r
257         This flag does not mean anything.  It is there only to match
258         git-diff-tree.  Unlike git-diff-tree, git-diff-cache always looks
259         at all the subdirectories.
261 -z
262         \0 line termination on output
264 --cached
265         do not consider the on-disk file at all
267 -m
269         By default, files recorded in the index but not checked
270         out are reported as deleted.  This flag makes
271         git-diff-cache say that all non-checked-out files are up
272         to date.
274 Output format:
276 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
277 section.
279 Operating Modes
281 You can choose whether you want to trust the index file entirely
282 (using the "--cached" flag) or ask the diff logic to show any files
283 that don't match the stat state as being "tentatively changed".  Both
284 of these operations are very useful indeed.
286 Cached Mode
288 If --cached is specified, it allows you to ask:
290         show me the differences between HEAD and the current index
291         contents (the ones I'd write with a "git-write-tree")
293 For example, let's say that you have worked on your index file, and are
294 ready to commit. You want to see eactly _what_ you are going to commit is
295 without having to write a new tree object and compare it that way, and to
296 do that, you just do
298         git-diff-cache --cached $(cat .git/HEAD)
300 Example: let's say I had renamed "commit.c" to "git-commit.c", and I had
301 done an "git-update-cache" to make that effective in the index file.
302 "git-diff-files" wouldn't show anything at all, since the index file
303 matches my working directory. But doing a git-diff-cache does:
305   torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)
306   -100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit.c
307   +100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git-commit.c
309 You can trivially see that the above is a rename.
311 In fact, "git-diff-cache --cached" _should_ always be entirely equivalent to
312 actually doing a "git-write-tree" and comparing that. Except this one is much
313 nicer for the case where you just want to check where you are.
315 So doing a "git-diff-cache --cached" is basically very useful when you are 
316 asking yourself "what have I already marked for being committed, and 
317 what's the difference to a previous tree".
319 Non-cached Mode
321 The "non-cached" mode takes a different approach, and is potentially the
322 even more useful of the two in that what it does can't be emulated with a
323 "git-write-tree + git-diff-tree". Thus that's the default mode.  The
324 non-cached version asks the question
326    "show me the differences between HEAD and the currently checked out 
327     tree - index contents _and_ files that aren't up-to-date"
329 which is obviously a very useful question too, since that tells you what
330 you _could_ commit. Again, the output matches the "git-diff-tree -r"
331 output to a tee, but with a twist.
333 The twist is that if some file doesn't match the cache, we don't have a
334 backing store thing for it, and we use the magic "all-zero" sha1 to show
335 that. So let's say that you have edited "kernel/sched.c", but have not
336 actually done an git-update-cache on it yet - there is no "object" associated
337 with the new state, and you get:
339   torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )
340   *100644->100664 blob    7476bb......->000000......      kernel/sched.c
342 ie it shows that the tree has changed, and that "kernel/sched.c" has is
343 not up-to-date and may contain new stuff. The all-zero sha1 means that to
344 get the real diff, you need to look at the object in the working directory
345 directly rather than do an object-to-object diff.
347 NOTE! As with other commands of this type, "git-diff-cache" does not
348 actually look at the contents of the file at all. So maybe
349 "kernel/sched.c" hasn't actually changed, and it's just that you touched
350 it. In either case, it's a note that you need to upate-cache it to make
351 the cache be in sync.
353 NOTE 2! You can have a mixture of files show up as "has been updated" and
354 "is still dirty in the working directory" together. You can always tell
355 which file is in which state, since the "has been updated" ones show a
356 valid sha1, and the "not in sync with the index" ones will always have the
357 special all-zero sha1.
360 ################################################################
361 git-diff-files
362         git-diff-files [-p] [-q] [-r] [-z] [<pattern>...]
364 Compares the files in the working tree and the cache.  When paths
365 are specified, compares only those named paths.  Otherwise all
366 entries in the cache are compared.  The output format is the
367 same as git-diff-cache and git-diff-tree.
369 -p
370         generate patch (see section on generating patches).
372 -q
373         Remain silent even on nonexisting files
375 -r
376         This flag does not mean anything.  It is there only to match
377         git-diff-tree.  Unlike git-diff-tree, git-diff-files always looks
378         at all the subdirectories.
381 Output format:
383 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
384 section.
387 ################################################################
388 git-diff-tree
389         git-diff-tree [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]*
391 Compares the content and mode of the blobs found via two tree objects.
393 Note that git-diff-tree can use the tree encapsulated in a commit object.
395 <tree-ish>
396         The id of a tree object.
398 <pattern>
399         If provided, the results are limited to a subset of files
400         matching one of these prefix strings.
401         ie file matches /^<pattern1>|<pattern2>|.../
402         Note that pattern does not provide any wildcard or regexp
403         features.
405 -p
406         generate patch (see section on generating patches).  For
407         git-diff-tree, this flag implies -r as well.
409 -r
410         recurse
412 -z
413         \0 line termination on output
415 --stdin
416         When --stdin is specified, the command does not take
417         <tree-ish> arguments from the command line.  Instead, it
418         reads either one <commit> or a pair of <tree-ish>
419         separated with a single space from its standard input.
421         When a single commit is given on one line of such input,
422         it compares the commit with its parents.  The following
423         flags further affects its behaviour.  This does not
424         apply to the case where two <tree-ish> separated with a
425         single space are given.
427 -m
428         By default, "git-diff-tree --stdin" does not show
429         differences for merge commits.  With this flag, it shows
430         differences to that commit from all of its parents.
432 -s
433         By default, "git-diff-tree --stdin" shows differences,
434         either in machine-readable form (without -p) or in patch
435         form (with -p).  This output can be supressed.  It is
436         only useful with -v flag.
438 -v
439         This flag causes "git-diff-tree --stdin" to also show
440         the commit message before the differences.
443 Limiting Output
445 If you're only interested in differences in a subset of files, for
446 example some architecture-specific files, you might do:
448         git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
450 and it will only show you what changed in those two directories.
452 Or if you are searching for what changed in just kernel/sched.c, just do
454         git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
456 and it will ignore all differences to other files.
458 The pattern is always the prefix, and is matched exactly.  There are no
459 wildcards.  Even stricter, it has to match complete path comonent.
460 I.e. "foo" does not pick up "foobar.h".  "foo" does match "foo/bar.h"
461 so it can be used to name subdirectories.
463 Output format:
465 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
466 section.
468 An example of normal usage is:
470   torvalds@ppc970:~/git> git-diff-tree 5319e4......
471   *100664->100664 blob    ac348b.......->a01513.......      git-fsck-cache.c
473 which tells you that the last commit changed just one file (it's from
474 this one:
476   commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
477   tree 5319e4d609cdd282069cc4dce33c1db559539b03
478   parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
479   author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
480   committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
482   Make "git-fsck-cache" print out all the root commits it finds.
484   Once I do the reference tracking, I'll also make it print out all the
485   HEAD commits it finds, which is even more interesting.
487 in case you care).
490 ################################################################
491 git-diff-tree-helper
492         git-diff-tree-helper [-z] [-R]
494 Reads output from git-diff-cache, git-diff-tree and git-diff-files and
495 generates patch format output.
497 -z
498         \0 line termination on input
500 -R
501         Output diff in reverse.  This is useful for displaying output from
502         git-diff-cache which always compares tree with cache or working
503         file.  E.g.
505         git-diff-cache <tree> | git-diff-tree-helper -R file.c
507         would show a diff to bring the working file back to what is in the
508         <tree>.
510 See also the section on generating patches.
513 ################################################################
514 git-export
515         git-export top [base]
517 Exports each commit and diff against each of its parents, between
518 top and base.  If base is not specified it exports everything.
521 ################################################################
522 git-fsck-cache
523         git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*]
525 Verifies the connectivity and validity of the objects in the database.
527 <object>
528         An object to treat as the head of an unreachability trace.
530 --unreachable
531         Print out objects that exist but that aren't readable from any
532         of the specified head nodes.
534 --root
535         Report root nodes.
537 --tags
538         Report tags.
540 --cache
541         Consider any object recorded in the cache also as a head node for
542         an unreachability trace.
544 It tests SHA1 and general object sanity, and it does full tracking of
545 the resulting reachability and everything else. It prints out any
546 corruption it finds (missing or bad objects), and if you use the
547 "--unreachable" flag it will also print out objects that exist but
548 that aren't readable from any of the specified head nodes.
550 So for example
552         git-fsck-cache --unreachable $(cat .git/HEAD)
554 or, for Cogito users:
556         git-fsck-cache --unreachable $(cat .git/refs/heads/*)
558 will do quite a _lot_ of verification on the tree. There are a few
559 extra validity tests to be added (make sure that tree objects are
560 sorted properly etc), but on the whole if "git-fsck-cache" is happy, you
561 do have a valid tree.
563 Any corrupt objects you will have to find in backups or other archives
564 (ie you can just remove them and do an "rsync" with some other site in
565 the hopes that somebody else has the object you have corrupted).
567 Of course, "valid tree" doesn't mean that it wasn't generated by some
568 evil person, and the end result might be crap. Git is a revision
569 tracking system, not a quality assurance system ;)
571 Extracted Diagnostics
573 expect dangling commits - potential heads - due to lack of head information
574         You haven't specified any nodes as heads so it won't be
575         possible to differentiate between un-parented commits and
576         root nodes.
578 missing sha1 directory '<dir>'
579         The directory holding the sha1 objects is missing.
581 unreachable <type> <object>
582         The <type> object <object>, isn't actually referred to directly
583         or indirectly in any of the trees or commits seen. This can
584         mean that there's another root na SHA1_ode that you're not specifying
585         or that the tree is corrupt. If you haven't missed a root node
586         then you might as well delete unreachable nodes since they
587         can't be used.
589 missing <type> <object>
590         The <type> object <object>, is referred to but isn't present in
591         the database.
593 dangling <type> <object>
594         The <type> object <object>, is present in the database but never
595         _directly_ used. A dangling commit could be a root node.
597 warning: git-fsck-cache: tree <tree> has full pathnames in it
598         And it shouldn't...
600 sha1 mismatch <object>
601         The database has an object who's sha1 doesn't match the
602         database value.
603         This indicates a ??serious?? data integrity problem.
604         (note: this error occured during early git development when
605         the database format changed.)
607 Environment Variables
609 SHA1_FILE_DIRECTORY
610         used to specify the object database root (usually .git/objects)
612 GIT_INDEX_FILE
613         used to specify the cache
616 ################################################################
617 git-http-pull
619         git-http-pull [-c] [-t] [-a] [-v] commit-id url
621 Downloads a remote GIT repository via HTTP protocol.
623 -c
624         Get the commit objects.
625 -t
626         Get trees associated with the commit objects.
627 -a
628         Get all the objects.
629 -v
630         Report what is downloaded.
633 ################################################################
634 git-init-db
635         git-init-db
637 This simply creates an empty git object database - basically a .git
638 directory and .git/object/??/ directories.
640 If the object storage directory is specified via the SHA1_FILE_DIRECTORY
641 environment variable then the sha1 directories are created underneath -
642 otherwise the default .git/objects directory is used.
644 git-init-db won't hurt an existing repository.
647 ################################################################
648 git-local-pull
650         git-local-pull [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path
652 Downloads another GIT repository on a local system.
654 -c
655         Get the commit objects.
656 -t
657         Get trees associated with the commit objects.
658 -a
659         Get all the objects.
660 -v
661         Report what is downloaded.
663 ################################################################
664 git-ls-files
665         git-ls-files [-z] [-t]
666                 (--[cached|deleted|others|ignored|stage|unmerged])*
667                 (-[c|d|o|i|s|u])*
668                 [-x <pattern>|--exclude=<pattern>]
669                 [-X <file>|--exclude-from=<file>]
671 This merges the file listing in the directory cache index with the
672 actual working directory list, and shows different combinations of the
673 two.
675 One or more of the options below may be used to determine the files
676 shown:
678 -c|--cached
679         Show cached files in the output (default)
681 -d|--deleted
682         Show deleted files in the output
684 -o|--others
685         Show other files in the output
687 -i|--ignored
688         Show ignored files in the output
689         Note the this also reverses any exclude list present.
691 -s|--stage
692         Show stage files in the output
694 -u|--unmerged
695         Show unmerged files in the output (forces --stage)
697 -z
698         \0 line termination on output
700 -x|--exclude=<pattern>
701         Skips files matching pattern.
702         Note that pattern is a shell wildcard pattern.
704 -X|--exclude-from=<file>
705         exclude patterns are read from <file>; 1 per line.
706         Allows the use of the famous dontdiff file as follows to find
707         out about uncommitted files just as dontdiff is used with
708         the diff command:
709              git-ls-files --others --exclude-from=dontdiff
711 -t
712         Identify the file status with the following tags (followed by
713         a space) at the start of each line:
714         H       cached
715         M       unmerged
716         R       removed/deleted
717         ?       other
719 Output
720 show files just outputs the filename unless --stage is specified in
721 which case it outputs:
723 [<tag> ]<mode> <object> <stage> <file>
725 git-ls-files --unmerged" and "git-ls-files --stage " can be used to examine
726 detailed information on unmerged paths.
728 For an unmerged path, instead of recording a single mode/SHA1 pair,
729 the dircache records up to three such pairs; one from tree O in stage
730 1, A in stage 2, and B in stage 3.  This information can be used by
731 the user (or Cogito) to see what should eventually be recorded at the
732 path. (see read-cache for more information on state)
734 see also:
735 read-cache
738 ################################################################
739 git-ls-tree
740         git-ls-tree [-r] [-z] <tree-ish>
742 Converts the tree object to a human readable (and script processable)
743 form.
745 <tree-ish>
746         Id of a tree.
748 -r
749         recurse into sub-trees
751 -z
752         \0 line termination on output
754 Output Format
755 <mode>\t        <type>\t        <object>\t      <file>
758 ################################################################
759 git-merge-base
760         git-merge-base <commit> <commit>
762 git-merge-base finds as good a common ancestor as possible. Given a
763 selection of equally good common ancestors it should not be relied on
764 to decide in any particular way.
766 The git-merge-base algorithm is still in flux - use the source...
769 ################################################################
770 git-merge-cache
771         git-merge-cache <merge-program> (-a | -- | <file>*) 
773 This looks up the <file>(s) in the cache and, if there are any merge
774 entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
775 argument if no file), and <file> as argument 4.  File modes for the three
776 files are passed as arguments 5, 6 and 7.
778 --
779         Interpret all future arguments as filenames.
781 -a
782         Run merge against all files in the cache that need merging.
784 If git-merge-cache is called with multiple <file>s (or -a) then it
785 processes them in turn only stopping if merge returns a non-zero exit
786 code.
788 Typically this is run with the a script calling the merge command from
789 the RCS package.
791 A sample script called git-merge-one-file-script is included in the
792 ditribution.
794 ALERT ALERT ALERT! The git "merge object order" is different from the
795 RCS "merge" program merge object order. In the above ordering, the
796 original is first. But the argument order to the 3-way merge program
797 "merge" is to have the original in the middle. Don't ask me why.
799 Examples:
801   torvalds@ppc970:~/merge-test> git-merge-cache cat MM
802   This is MM from the original tree.                    # original
803   This is modified MM in the branch A.                  # merge1
804   This is modified MM in the branch B.                  # merge2
805   This is modified MM in the branch B.                  # current contents
807 or 
809   torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM
810   cat: : No such file or directory
811   This is added AA in the branch A.
812   This is added AA in the branch B.
813   This is added AA in the branch B.
814   fatal: merge program failed
816 where the latter example shows how "git-merge-cache" will stop trying to
817 merge once anything has returned an error (ie "cat" returned an error
818 for the AA file, because it didn't exist in the original, and thus
819 "git-merge-cache" didn't even try to merge the MM thing).
821 ################################################################
822 git-merge-one-file-script
824 This is the standard helper program to use with git-merge-cache
825 to resolve a merge after the trivial merge done with git-read-tree -m.
827 ################################################################
828 git-mktag
830 Reads a tag contents from its standard input and creates a tag object.
831 The input must be a well formed tag object.
834 ################################################################
835 git-prune-script
837 This runs git-fsck-cache --unreachable program using the heads specified
838 on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is
839 specified), and prunes all unreachable objects from the object database.
842 ################################################################
843 git-pull-script
845 This script is used by Linus to pull from a remote repository and perform
846 a merge.
849 ################################################################
850 git-read-tree
851         git-read-tree (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"
853 Reads the tree information given by <tree> into the directory cache,
854 but does not actually _update_ any of the files it "caches". (see:
855 git-checkout-cache)
857 Optionally, it can merge a tree into the cache or perform a 3-way
858 merge.
860 Trivial merges are done by git-read-tree itself.  Only conflicting paths
861 will be in unmerged state when git-read-tree returns.
863 -m
864         Perform a merge, not just a read
866 <tree-ish#>
867         The id of the tree object(s) to be read/merged.
870 Merging
871 If -m is specified, git-read-tree performs 2 kinds of merge, a single tree
872 merge if only 1 tree is given or a 3-way merge if 3 trees are
873 provided.
875 Single Tree Merge
876 If only 1 tree is specified, git-read-tree operates as if the user did not
877 specify "-m", except that if the original cache has an entry for a
878 given pathname; and the contents of the path matches with the tree
879 being read, the stat info from the cache is used. (In other words, the
880 cache's stat()s take precedence over the merged tree's)
882 That means that if you do a "git-read-tree -m <newtree>" followed by a
883 "git-checkout-cache -f -a", the git-checkout-cache only checks out the stuff
884 that really changed.
886 This is used to avoid unnecessary false hits when git-diff-files is
887 run after git-read-tree.
889 3-Way Merge
890 Each "index" entry has two bits worth of "stage" state. stage 0 is the
891 normal one, and is the only one you'd see in any kind of normal use.
893 However, when you do "git-read-tree" with three trees, the "stage"
894 starts out at 1.
896 This means that you can do
898         git-read-tree -m <tree1> <tree2> <tree3>
900 and you will end up with an index with all of the <tree1> entries in
901 "stage1", all of the <tree2> entries in "stage2" and all of the
902 <tree3> entries in "stage3".
904 Furthermore, "git-read-tree" has special-case logic that says: if you see
905 a file that matches in all respects in the following states, it
906 "collapses" back to "stage0":
908    - stage 2 and 3 are the same; take one or the other (it makes no
909      difference - the same work has been done on stage 2 and 3)
911    - stage 1 and stage 2 are the same and stage 3 is different; take
912      stage 3 (some work has been done on stage 3)
914    - stage 1 and stage 3 are the same and stage 2 is different take
915      stage 2 (some work has been done on stage 2)
917 The git-write-tree command refuses to write a nonsensical tree, and it
918 will complain about unmerged entries if it sees a single entry that is not
919 stage 0.
921 Ok, this all sounds like a collection of totally nonsensical rules,
922 but it's actually exactly what you want in order to do a fast
923 merge. The different stages represent the "result tree" (stage 0, aka
924 "merged"), the original tree (stage 1, aka "orig"), and the two trees
925 you are trying to merge (stage 2 and 3 respectively).
927 In fact, the way "git-read-tree" works, it's entirely agnostic about how
928 you assign the stages, and you could really assign them any which way,
929 and the above is just a suggested way to do it (except since
930 "git-write-tree" refuses to write anything but stage0 entries, it makes
931 sense to always consider stage 0 to be the "full merge" state).
933 So what happens? Try it out. Select the original tree, and two trees
934 to merge, and look how it works:
936  - if a file exists in identical format in all three trees, it will 
937    automatically collapse to "merged" state by the new git-read-tree.
939  - a file that has _any_ difference what-so-ever in the three trees
940    will stay as separate entries in the index. It's up to "script
941    policy" to determine how to remove the non-0 stages, and insert a
942    merged version.  But since the index is always sorted, they're easy
943    to find: they'll be clustered together.
945  - the index file saves and restores with all this information, so you
946    can merge things incrementally, but as long as it has entries in
947    stages 1/2/3 (ie "unmerged entries") you can't write the result.
949 So now the merge algorithm ends up being really simple:
951  - you walk the index in order, and ignore all entries of stage 0,
952    since they've already been done.
954  - if you find a "stage1", but no matching "stage2" or "stage3", you
955    know it's been removed from both trees (it only existed in the
956    original tree), and you remove that entry.  - if you find a
957    matching "stage2" and "stage3" tree, you remove one of them, and
958    turn the other into a "stage0" entry. Remove any matching "stage1"
959    entry if it exists too.  .. all the normal trivial rules ..
961 Incidentally - it also means that you don't even have to have a separate
962 subdirectory for this. All the information literally is in the index file,
963 which is a temporary thing anyway. There is no need to worry about what is
964 in the working directory, since it is never shown and never used.
966 see also:
967 git-write-tree
968 git-ls-files
971 ################################################################
972 git-resolve-script
974 This script is used by Linus to merge two trees.
977 ################################################################
978 git-rev-list <commit>
980 Lists commit objects in reverse chronological order starting at the
981 given commit, taking ancestry relationship into account.  This is
982 useful to produce human-readable log output.
985 ################################################################
986 git-rev-tree
987         git-rev-tree [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]
989 Provides the revision tree for one or more commits.
991 --edges
992         Show edges (ie places where the marking changes between parent
993         and child)
995 --cache <cache-file>
996         Use the specified file as a cache from a previous git-rev-list run
997         to speed things up.  Note that this "cache" is totally different
998         concept from the directory index.  Also this option is not
999         implemented yet.
1001 [^]<commit>
1002         The commit id to trace (a leading caret means to ignore this
1003         commit-id and below)
1005 Output:
1006 <date> <commit>:<flags> [<parent-commit>:<flags> ]*
1008 <date>
1009         Date in 'seconds since epoch'
1011 <commit>
1012         id of commit object
1014 <parent-commit>
1015         id of each parent commit object (>1 indicates a merge)
1017 <flags>
1019         The flags are read as a bitmask representing each commit
1020         provided on the commandline. eg: given the command:
1022                  $ git-rev-tree <com1> <com2> <com3>
1024         The output:
1026             <date> <commit>:5
1028          means that <commit> is reachable from <com1>(1) and <com3>(4)
1029         
1030 A revtree can get quite large. git-rev-tree will eventually allow you to
1031 cache previous state so that you don't have to follow the whole thing
1032 down.
1034 So the change difference between two commits is literally
1036         git-rev-tree [commit-id1]  > commit1-revtree
1037         git-rev-tree [commit-id2]  > commit2-revtree
1038         join -t : commit1-revtree commit2-revtree > common-revisions
1040 (this is also how to find the most common parent - you'd look at just
1041 the head revisions - the ones that aren't referred to by other
1042 revisions - in "common-revision", and figure out the best one. I
1043 think.)
1046 ################################################################
1047 git-rpull
1049         git-rpull [-c] [-t] [-a] [-v] commit-id url
1051 Pulls from a remote repository over ssh connection, invoking git-rpush on
1052 the other end.
1054 -c
1055         Get the commit objects.
1056 -t
1057         Get trees associated with the commit objects.
1058 -a
1059         Get all the objects.
1060 -v
1061         Report what is downloaded.
1064 ################################################################
1065 git-rpush
1067 Helper "server-side" program used by git-rpull.
1070 ################################################################
1071 git-tag-script
1073 This is an example script that uses git-mktag to create a tag object
1074 signed with GPG.
1077 ################################################################
1078 git-tar-tree
1080         git-tar-tree <tree-ish> [ <base> ]
1082 Creates a tar archive containing the tree structure for the named tree.
1083 When <base> is specified it is added as a leading path as the files in the
1084 generated tar archive.
1087 ################################################################
1088 git-unpack-file
1089         git-unpack-file <blob>
1091 Creates a file holding the contents of the blob specified by sha1. It
1092 returns the name of the temporary file in the following format:
1093         .merge_file_XXXXX
1095 <blob>
1096         Must be a blob id
1098 ################################################################
1099 git-update-cache
1100         git-update-cache
1101              [--add] [--remove] [--refresh] [--replace]
1102              [--ignore-missing]
1103              [--force-remove <file>]
1104              [--cacheinfo <mode> <object> <file>]*
1105              [--] [<file>]*
1107 Modifies the index or directory cache. Each file mentioned is updated
1108 into the cache and any 'unmerged' or 'needs updating' state is
1109 cleared.
1111 The way git-update-cache handles files it is told about can be modified
1112 using the various options:
1114 --add
1115         If a specified file isn't in the cache already then it's
1116         added.
1117         Default behaviour is to ignore new files.
1119 --remove
1120         If a specified file is in the cache but is missing then it's
1121         removed.
1122         Default behaviour is to ignore removed file.
1124 --refresh
1125         Looks at the current cache and checks to see if merges or
1126         updates are needed by checking stat() information.
1128 --ignore-missing
1129         Ignores missing files during a --refresh
1131 --cacheinfo <mode> <object> <path>
1132         Directly insert the specified info into the cache.
1133         
1134 --force-remove
1135         Remove the file from the index even when the working directory
1136         still has such a file.
1138 --replace
1139         By default, when a file "path" exists in the index,
1140         git-update-cache refuses an attempt to add "path/file".
1141         Similarly if a file "path/file" exists, a file "path"
1142         cannot be added.  With --replace flag, existing entries
1143         that conflicts with the entry being added are
1144         automatically removed with warning messages.
1146 --
1147         Do not interpret any more arguments as options.
1149 <file>
1150         Files to act on.
1151         Note that files begining with '.' are discarded. This includes
1152         "./file" and "dir/./file". If you don't want this, then use     
1153         cleaner names.
1154         The same applies to directories ending '/' and paths with '//'
1156 Using --refresh
1157 --refresh does not calculate a new sha1 file or bring the cache
1158 up-to-date for mode/content changes. But what it _does_ do is to
1159 "re-match" the stat information of a file with the cache, so that you
1160 can refresh the cache for a file that hasn't been changed but where
1161 the stat entry is out of date.
1163 For example, you'd want to do this after doing a "git-read-tree", to link
1164 up the stat cache details with the proper files.
1166 Using --cacheinfo
1167 --cacheinfo is used to register a file that is not in the current
1168 working directory.  This is useful for minimum-checkout merging.
1170 To pretend you have a file with mode and sha1 at path, say:
1172  $ git-update-cache --cacheinfo mode sha1 path
1174 To update and refresh only the files already checked out:
1176    git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
1179 ################################################################
1180 git-write-blob
1182         git-write-blob <any-file-on-the-filesystem>
1184 Writes the contents of the named file (which can be outside of the work
1185 tree) as a blob into the object database, and reports its object ID to its
1186 standard output.  This is used by git-merge-one-file-script to update the
1187 cache without modifying files in the work tree.
1190 ################################################################
1191 git-write-tree
1192         git-write-tree
1194 Creates a tree object using the current cache.
1196 The cache must be merged.
1198 Conceptually, git-write-tree sync()s the current directory cache contents
1199 into a set of tree files.
1200 In order to have that match what is actually in your directory right
1201 now, you need to have done a "git-update-cache" phase before you did the
1202 "git-write-tree".
1205 ################################################################
1207 Output format from git-diff-cache, git-diff-tree and git-diff-files.
1209 These commands all compare two sets of things; what are
1210 compared are different:
1212     git-diff-cache <tree-ish>
1214         compares the <tree-ish> and the files on the filesystem.
1216     git-diff-cache --cached <tree-ish>
1218         compares the <tree-ish> and the cache.
1220     git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]
1222         compares the trees named by the two arguments.
1224     git-diff-files [<pattern>...]
1226         compares the cache and the files on the filesystem.
1228 The following desription uses "old" and "new" to mean those
1229 compared entities.
1231 For files in old but not in new (i.e. removed):
1232 -<mode> \t <type> \t <object> \t <path>
1234 For files not in old but in new (i.e. added):
1235 +<mode> \t <type> \t <object> \t <path>
1237 For files that differ:
1238 *<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path>
1240 <new-sha1> is shown as all 0's if new is a file on the
1241 filesystem and it is out of sync with the cache.  Example:
1243   *100644->100644 blob    5be4a4.......->000000.......      file.c
1245 ################################################################
1247 Generating patches
1249 When git-diff-cache, git-diff-tree, or git-diff-files are run with a -p
1250 option, they do not produce the output described in "Output format from
1251 git-diff-cache, git-diff-tree and git-diff-files" section.  It instead
1252 produces a patch file.
1254 The patch generation can be customized at two levels.  This
1255 customization also applies to git-diff-tree-helper.
1257 1. When the environment variable GIT_EXTERNAL_DIFF is not set,
1258    these commands internally invoke diff like this:
1260    diff -L a/<path> -L a/<path> -pu <old> <new>
1262    For added files, /dev/null is used for <old>.  For removed
1263    files, /dev/null is used for <new>
1265    The diff formatting options can be customized via the
1266    environment variable GIT_DIFF_OPTS.  For example, if you
1267    prefer context diff:
1269    GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)
1272 2. When the environment variable GIT_EXTERNAL_DIFF is set, the
1273    program named by it is called, instead of the diff invocation
1274    described above.
1276    For a path that is added, removed, or modified,
1277    GIT_EXTERNAL_DIFF is called with 7 parameters:
1279      path old-file old-hex old-mode new-file new-hex new-mode
1281    where
1282      <old|new>-file are files GIT_EXTERNAL_DIFF can use to read the
1283                     contents of <old|ne>,
1284      <old|new>-hex are the 40-hexdigit SHA1 hashes,
1285      <old|new>-mode are the octal representation of the file modes.
1287    The file parameters can point at the user's working file (e.g. new-file
1288    in git-diff-files), /dev/null (e.g. old-file when a new file is added),
1289    or a temporary file (e.g. old-file in the cache).  GIT_EXTERNAL_DIFF
1290    should not worry about unlinking the temporary file --- it is removed
1291    when GIT_EXTERNAL_DIFF exits.
1293    For a path that is unmerged, GIT_EXTERNAL_DIFF is called with
1294    1 parameter, path.
1296 ################################################################
1298 Terminology: - see README for description
1299 Each line contains terms used interchangeably
1301 object database, .git directory
1302 directory cache, index
1303 id, sha1, sha1-id, sha1 hash
1304 type, tag
1305 blob, blob object
1306 tree, tree object
1307 commit, commit object
1308 parent
1309 root object
1310 changeset
1313 git Environment Variables
1314 AUTHOR_NAME
1315 AUTHOR_EMAIL
1316 AUTHOR_DATE
1317 COMMIT_AUTHOR_NAME
1318 COMMIT_AUTHOR_EMAIL
1319 GIT_DIFF_OPTS
1320 GIT_EXTERNAL_DIFF
1321 GIT_INDEX_FILE
1322 SHA1_FILE_DIRECTORY