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
168 git-checkout-cache --prefix=git-export-dir/ -a
170 and git-checkout-cache will "export" the cache into the specified
171 directory.
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
176 git-checkout-cache --prefix=.merged- Makefile
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.
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)
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.
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