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>
10 Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
11 reflect recent changes.
13 Identifier terminology used:
16 Indicates any object sha1 identifier
19 Indicates a blob object sha1 identifier
22 Indicates a tree object sha1 identifier
25 Indicates a commit object sha1 identifier
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
35 Indicates that an object type is required.
36 Currently one of: blob/tree/commit/tag
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
51 ################################################################
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.
59 The sha1 identifier of the object.
62 Instead of the content, show the object type identified
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
75 If -t is specified, one of the <type>.
77 Otherwise the raw (though uncompressed) contents of the <object> will
81 ################################################################
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
101 see also: git-update-cache
104 ################################################################
106 git-checkout-cache [-q] [-a] [-f] [-n] [--prefix=<string>]
109 Will copy all files listed from the cache to the working directory
110 (not overwriting existing files).
113 be quiet if files exist or are not in the cache
116 forces overwrite of existing files
119 checks out all files in the cache (will then continue to
120 process listed files).
123 Don't checkout new files, only refresh files already checked
127 When creating files, prepend <string> (usually a directory
128 including a trailing /)
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
164 The prefix ability basically makes it trivial to use git-checkout-cache as
165 a "git-export as tree" function. Just read the desired tree into the
168 git-checkout-cache --prefix=git-export-dir/ -a
170 and git-checkout-cache will "git-export" the cache into the specified
173 NOTE! The final "/" is important. The git-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
182 ################################################################
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
194 While a tree represents a particular directory state of a working
195 directory, a commit represents that state in "time", and explains how
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.
206 An existing tree object
209 Each -p indicates a the id of a parent commit object.
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.
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 ################################################################
239 Converts old-style GIT repository to the latest.
242 ################################################################
244 git-diff-cache [-p] [-r] [-z] [--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.
251 The id of a tree object to diff against.
254 Generate patch (see section on generating patches)
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.
262 \0 line termination on output
265 do not consider the on-disk file at all
269 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
274 You can choose whether you want to trust the index file entirely
275 (using the "--cached" flag) or ask the diff logic to show any files
276 that don't match the stat state as being "tentatively changed". Both
277 of these operations are very useful indeed.
281 If --cached is specified, it allows you to ask:
283 show me the differences between HEAD and the current index
284 contents (the ones I'd write with a "git-write-tree")
286 For example, let's say that you have worked on your index file, and are
287 ready to commit. You want to see eactly _what_ you are going to commit is
288 without having to write a new tree object and compare it that way, and to
291 git-diff-cache --cached $(cat .git/HEAD)
293 Example: let's say I had renamed "commit.c" to "git-commit.c", and I had
294 done an "git-update-cache" to make that effective in the index file.
295 "git-diff-files" wouldn't show anything at all, since the index file
296 matches my working directory. But doing a git-diff-cache does:
298 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)
299 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c
300 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c
302 You can trivially see that the above is a rename.
304 In fact, "git-diff-cache --cached" _should_ always be entirely equivalent to
305 actually doing a "git-write-tree" and comparing that. Except this one is much
306 nicer for the case where you just want to check where you are.
308 So doing a "git-diff-cache --cached" is basically very useful when you are
309 asking yourself "what have I already marked for being committed, and
310 what's the difference to a previous tree".
314 The "non-cached" mode takes a different approach, and is potentially the
315 even more useful of the two in that what it does can't be emulated with a
316 "git-write-tree + git-diff-tree". Thus that's the default mode. The
317 non-cached version asks the question
319 "show me the differences between HEAD and the currently checked out
320 tree - index contents _and_ files that aren't up-to-date"
322 which is obviously a very useful question too, since that tells you what
323 you _could_ commit. Again, the output matches the "git-diff-tree -r"
324 output to a tee, but with a twist.
326 The twist is that if some file doesn't match the cache, we don't have a
327 backing store thing for it, and we use the magic "all-zero" sha1 to show
328 that. So let's say that you have edited "kernel/sched.c", but have not
329 actually done an git-update-cache on it yet - there is no "object" associated
330 with the new state, and you get:
332 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )
333 *100644->100664 blob 7476bb......->000000...... kernel/sched.c
335 ie it shows that the tree has changed, and that "kernel/sched.c" has is
336 not up-to-date and may contain new stuff. The all-zero sha1 means that to
337 get the real diff, you need to look at the object in the working directory
338 directly rather than do an object-to-object diff.
340 NOTE! As with other commands of this type, "git-diff-cache" does not
341 actually look at the contents of the file at all. So maybe
342 "kernel/sched.c" hasn't actually changed, and it's just that you touched
343 it. In either case, it's a note that you need to upate-cache it to make
344 the cache be in sync.
346 NOTE 2! You can have a mixture of files show up as "has been updated" and
347 "is still dirty in the working directory" together. You can always tell
348 which file is in which state, since the "has been updated" ones show a
349 valid sha1, and the "not in sync with the index" ones will always have the
350 special all-zero sha1.
353 ################################################################
355 git-diff-tree [-p] [-r] [-z] <tree-ish> <tree-ish> [<pattern>]*
357 Compares the content and mode of the blobs found via two tree objects.
359 Note that git-diff-tree can use the tree encapsulated in a commit object.
362 The id of a tree object.
365 If provided, the results are limited to a subset of files
366 matching one of these prefix strings.
367 ie file matches /^<pattern1>|<pattern2>|.../
368 Note that pattern does not provide any wildcard or regexp
372 generate patch (see section on generating patches). For
373 git-diff-tree, this flag implies -r as well.
379 \0 line termination on output
383 If you're only interested in differences in a subset of files, for
384 example some architecture-specific files, you might do:
386 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
388 and it will only show you what changed in those two directories.
390 Or if you are searching for what changed in just kernel/sched.c, just do
392 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
394 and it will ignore all differences to other files.
396 The pattern is always the prefix, and is matched exactly. There are no
397 wildcards. Even stricter, it has to match complete path comonent.
398 I.e. "foo" does not pick up "foobar.h". "foo" does match "foo/bar.h"
399 so it can be used to name subdirectories.
403 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
406 An example of normal usage is:
408 torvalds@ppc970:~/git> git-diff-tree 5319e4......
409 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c
411 which tells you that the last commit changed just one file (it's from
414 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
415 tree 5319e4d609cdd282069cc4dce33c1db559539b03
416 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
417 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
418 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
420 Make "git-fsck-cache" print out all the root commits it finds.
422 Once I do the reference tracking, I'll also make it print out all the
423 HEAD commits it finds, which is even more interesting.
428 ################################################################
430 git-diff-tree-helper [-z] [-R]
432 Reads output from git-diff-cache, git-diff-tree and git-diff-files and
433 generates patch format output.
436 \0 line termination on input
439 Output diff in reverse. This is useful for displaying output from
440 git-diff-cache which always compares tree with cache or working
443 git-diff-cache <tree> | git-diff-tree-helper -R file.c
445 would show a diff to bring the working file back to what is in the
448 See also the section on generating patches.
451 ################################################################
453 git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*]
455 Verifies the connectivity and validity of the objects in the database.
458 An object to treat as the head of an unreachability trace.
461 Print out objects that exist but that aren't readable from any
462 of the specified head nodes.
471 Consider any object recorded in the cache also as a head node for
472 an unreachability trace.
474 It tests SHA1 and general object sanity, and it does full tracking of
475 the resulting reachability and everything else. It prints out any
476 corruption it finds (missing or bad objects), and if you use the
477 "--unreachable" flag it will also print out objects that exist but
478 that aren't readable from any of the specified head nodes.
482 git-fsck-cache --unreachable $(cat .git/HEAD)
484 or, for Cogito users:
486 git-fsck-cache --unreachable $(cat .git/refs/heads/*)
488 will do quite a _lot_ of verification on the tree. There are a few
489 extra validity tests to be added (make sure that tree objects are
490 sorted properly etc), but on the whole if "git-fsck-cache" is happy, you
491 do have a valid tree.
493 Any corrupt objects you will have to find in backups or other archives
494 (ie you can just remove them and do an "rsync" with some other site in
495 the hopes that somebody else has the object you have corrupted).
497 Of course, "valid tree" doesn't mean that it wasn't generated by some
498 evil person, and the end result might be crap. Git is a revision
499 tracking system, not a quality assurance system ;)
501 Extracted Diagnostics
503 expect dangling commits - potential heads - due to lack of head information
504 You haven't specified any nodes as heads so it won't be
505 possible to differentiate between un-parented commits and
508 missing sha1 directory '<dir>'
509 The directory holding the sha1 objects is missing.
511 unreachable <type> <object>
512 The <type> object <object>, isn't actually referred to directly
513 or indirectly in any of the trees or commits seen. This can
514 mean that there's another root na SHA1_ode that you're not specifying
515 or that the tree is corrupt. If you haven't missed a root node
516 then you might as well delete unreachable nodes since they
519 missing <type> <object>
520 The <type> object <object>, is referred to but isn't present in
523 dangling <type> <object>
524 The <type> object <object>, is present in the database but never
525 _directly_ used. A dangling commit could be a root node.
527 warning: git-fsck-cache: tree <tree> has full pathnames in it
530 sha1 mismatch <object>
531 The database has an object who's sha1 doesn't match the
533 This indicates a ??serious?? data integrity problem.
534 (note: this error occured during early git development when
535 the database format changed.)
537 Environment Variables
540 used to specify the object database root (usually .git/objects)
543 used to specify the cache
546 ################################################################
548 git-export top [base]
550 Exports each commit and diff against each of its parents, between
551 top and base. If base is not specified it exports everything.
554 ################################################################
558 This simply creates an empty git object database - basically a .git
559 directory and .git/object/??/ directories.
561 If the object storage directory is specified via the SHA1_FILE_DIRECTORY
562 environment variable then the sha1 directories are created underneath -
563 otherwise the default .git/objects directory is used.
565 git-init-db won't hurt an existing repository.
568 ################################################################
571 git-http-pull [-c] [-t] [-a] [-v] commit-id url
573 Downloads a remote GIT repository via HTTP protocol.
576 Get the commit objects.
578 Get trees associated with the commit objects.
582 Report what is downloaded.
585 ################################################################
588 git-local-pull [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path
590 Downloads another GIT repository on a local system.
593 Get the commit objects.
595 Get trees associated with the commit objects.
599 Report what is downloaded.
601 ################################################################
603 git-ls-tree [-r] [-z] <tree-ish>
605 Converts the tree object to a human readable (and script processable)
612 recurse into sub-trees
615 \0 line termination on output
618 <mode>\t <type>\t <object>\t <file>
621 ################################################################
623 git-merge-base <commit> <commit>
625 git-merge-base finds as good a common ancestor as possible. Given a
626 selection of equally good common ancestors it should not be relied on
627 to decide in any particular way.
629 The git-merge-base algorithm is still in flux - use the source...
632 ################################################################
634 git-merge-cache <merge-program> (-a | -- | <file>*)
636 This looks up the <file>(s) in the cache and, if there are any merge
637 entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
638 argument if no file), and <file> as argument 4. File modes for the three
639 files are passed as arguments 5, 6 and 7.
642 Interpret all future arguments as filenames.
645 Run merge against all files in the cache that need merging.
647 If git-merge-cache is called with multiple <file>s (or -a) then it
648 processes them in turn only stopping if merge returns a non-zero exit
651 Typically this is run with the a script calling the merge command from
654 A sample script called git-merge-one-file-script is included in the
657 ALERT ALERT ALERT! The git "merge object order" is different from the
658 RCS "merge" program merge object order. In the above ordering, the
659 original is first. But the argument order to the 3-way merge program
660 "merge" is to have the original in the middle. Don't ask me why.
664 torvalds@ppc970:~/merge-test> git-merge-cache cat MM
665 This is MM from the original tree. # original
666 This is modified MM in the branch A. # merge1
667 This is modified MM in the branch B. # merge2
668 This is modified MM in the branch B. # current contents
672 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM
673 cat: : No such file or directory
674 This is added AA in the branch A.
675 This is added AA in the branch B.
676 This is added AA in the branch B.
677 fatal: merge program failed
679 where the latter example shows how "git-merge-cache" will stop trying to
680 merge once anything has returned an error (ie "cat" returned an error
681 for the AA file, because it didn't exist in the original, and thus
682 "git-merge-cache" didn't even try to merge the MM thing).
684 ################################################################
685 git-merge-one-file-script
687 This is the standard helper program to use with git-merge-cache
688 to resolve a merge after the trivial merge done with git-read-tree -m.
690 ################################################################
693 Reads a tag contents from its standard input and creates a tag object.
694 The input must be a well formed tag object.
697 ################################################################
700 This runs git-fsck-cache --unreachable program using the heads specified
701 on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is
702 specified), and prunes all unreachable objects from the object database.
705 ################################################################
708 This script is used by Linus to pull from a remote repository and perform
712 ################################################################
714 git-read-tree (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"
716 Reads the tree information given by <tree> into the directory cache,
717 but does not actually _update_ any of the files it "caches". (see:
720 Optionally, it can merge a tree into the cache or perform a 3-way
723 Trivial merges are done by git-read-tree itself. Only conflicting paths
724 will be in unmerged state when git-read-tree returns.
727 Perform a merge, not just a read
730 The id of the tree object(s) to be read/merged.
734 If -m is specified, git-read-tree performs 2 kinds of merge, a single tree
735 merge if only 1 tree is given or a 3-way merge if 3 trees are
739 If only 1 tree is specified, git-read-tree operates as if the user did not
740 specify "-m", except that if the original cache has an entry for a
741 given pathname; and the contents of the path matches with the tree
742 being read, the stat info from the cache is used. (In other words, the
743 cache's stat()s take precedence over the merged tree's)
745 That means that if you do a "git-read-tree -m <newtree>" followed by a
746 "git-checkout-cache -f -a", the git-checkout-cache only checks out the stuff
749 This is used to avoid unnecessary false hits when git-diff-files is
750 run after git-read-tree.
753 Each "index" entry has two bits worth of "stage" state. stage 0 is the
754 normal one, and is the only one you'd see in any kind of normal use.
756 However, when you do "git-read-tree" with three trees, the "stage"
759 This means that you can do
761 git-read-tree -m <tree1> <tree2> <tree3>
763 and you will end up with an index with all of the <tree1> entries in
764 "stage1", all of the <tree2> entries in "stage2" and all of the
765 <tree3> entries in "stage3".
767 Furthermore, "git-read-tree" has special-case logic that says: if you see
768 a file that matches in all respects in the following states, it
769 "collapses" back to "stage0":
771 - stage 2 and 3 are the same; take one or the other (it makes no
772 difference - the same work has been done on stage 2 and 3)
774 - stage 1 and stage 2 are the same and stage 3 is different; take
775 stage 3 (some work has been done on stage 3)
777 - stage 1 and stage 3 are the same and stage 2 is different take
778 stage 2 (some work has been done on stage 2)
780 The git-write-tree command refuses to write a nonsensical tree, and it
781 will complain about unmerged entries if it sees a single entry that is not
784 Ok, this all sounds like a collection of totally nonsensical rules,
785 but it's actually exactly what you want in order to do a fast
786 merge. The different stages represent the "result tree" (stage 0, aka
787 "merged"), the original tree (stage 1, aka "orig"), and the two trees
788 you are trying to merge (stage 2 and 3 respectively).
790 In fact, the way "git-read-tree" works, it's entirely agnostic about how
791 you assign the stages, and you could really assign them any which way,
792 and the above is just a suggested way to do it (except since
793 "git-write-tree" refuses to write anything but stage0 entries, it makes
794 sense to always consider stage 0 to be the "full merge" state).
796 So what happens? Try it out. Select the original tree, and two trees
797 to merge, and look how it works:
799 - if a file exists in identical format in all three trees, it will
800 automatically collapse to "merged" state by the new git-read-tree.
802 - a file that has _any_ difference what-so-ever in the three trees
803 will stay as separate entries in the index. It's up to "script
804 policy" to determine how to remove the non-0 stages, and insert a
805 merged version. But since the index is always sorted, they're easy
806 to find: they'll be clustered together.
808 - the index file saves and restores with all this information, so you
809 can merge things incrementally, but as long as it has entries in
810 stages 1/2/3 (ie "unmerged entries") you can't write the result.
812 So now the merge algorithm ends up being really simple:
814 - you walk the index in order, and ignore all entries of stage 0,
815 since they've already been done.
817 - if you find a "stage1", but no matching "stage2" or "stage3", you
818 know it's been removed from both trees (it only existed in the
819 original tree), and you remove that entry. - if you find a
820 matching "stage2" and "stage3" tree, you remove one of them, and
821 turn the other into a "stage0" entry. Remove any matching "stage1"
822 entry if it exists too. .. all the normal trivial rules ..
824 Incidentally - it also means that you don't even have to have a separate
825 subdirectory for this. All the information literally is in the index file,
826 which is a temporary thing anyway. There is no need to worry about what is
827 in the working directory, since it is never shown and never used.
834 ################################################################
837 This script is used by Linus to merge two trees.
840 ################################################################
841 git-rev-list <commit>
843 Lists commit objects in reverse chronological order starting at the
844 given commit, taking ancestry relationship into account. This is
845 useful to produce human-readable log output.
848 ################################################################
850 git-rev-tree [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]
852 Provides the revision tree for one or more commits.
855 Show edges (ie places where the marking changes between parent
859 Use the specified file as a cache from a previous git-rev-list run
860 to speed things up. Note that this "cache" is totally different
861 concept from the directory index. Also this option is not
865 The commit id to trace (a leading caret means to ignore this
869 <date> <commit>:<flags> [<parent-commit>:<flags> ]*
872 Date in 'seconds since epoch'
878 id of each parent commit object (>1 indicates a merge)
882 The flags are read as a bitmask representing each commit
883 provided on the commandline. eg: given the command:
885 $ git-rev-tree <com1> <com2> <com3>
891 means that <commit> is reachable from <com1>(1) and <com3>(4)
893 A revtree can get quite large. git-rev-tree will eventually allow you to
894 cache previous state so that you don't have to follow the whole thing
897 So the change difference between two commits is literally
899 git-rev-tree [commit-id1] > commit1-revtree
900 git-rev-tree [commit-id2] > commit2-revtree
901 join -t : commit1-revtree commit2-revtree > common-revisions
903 (this is also how to find the most common parent - you'd look at just
904 the head revisions - the ones that aren't referred to by other
905 revisions - in "common-revision", and figure out the best one. I
909 ################################################################
912 git-rpull [-c] [-t] [-a] [-v] commit-id url
914 Pulls from a remote repository over ssh connection, invoking git-rpush on
918 Get the commit objects.
920 Get trees associated with the commit objects.
924 Report what is downloaded.
927 ################################################################
930 Helper "server-side" program used by git-rpull.
933 ################################################################
935 git-diff-files [-p] [-q] [-r] [-z] [<pattern>...]
937 Compares the files in the working tree and the cache. When paths
938 are specified, compares only those named paths. Otherwise all
939 entries in the cache are compared. The output format is the
940 same as git-diff-cache and git-diff-tree.
943 generate patch (see section on generating patches).
946 Remain silent even on nonexisting files
949 This flag does not mean anything. It is there only to match
950 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks
951 at all the subdirectories.
956 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
960 ################################################################
963 This is an example script that uses git-mktag to create a tag object
967 ################################################################
970 git-tar-tree <tree-ish> [ <base> ]
972 Creates a tar archive containing the tree structure for the named tree.
973 When <base> is specified it is added as a leading path as the files in the
974 generated tar archive.
977 ################################################################
979 git-ls-files [-z] [-t]
980 (--[cached|deleted|others|ignored|stage|unmerged])*
982 [-x <pattern>|--exclude=<pattern>]
983 [-X <file>|--exclude-from=<file>]
985 This merges the file listing in the directory cache index with the
986 actual working directory list, and shows different combinations of the
989 One or more of the options below may be used to determine the files
993 Show cached files in the output (default)
996 Show deleted files in the output
999 Show other files in the output
1002 Show ignored files in the output
1003 Note the this also reverses any exclude list present.
1006 Show stage files in the output
1009 Show unmerged files in the output (forces --stage)
1012 \0 line termination on output
1014 -x|--exclude=<pattern>
1015 Skips files matching pattern.
1016 Note that pattern is a shell wildcard pattern.
1018 -X|--exclude-from=<file>
1019 exclude patterns are read from <file>; 1 per line.
1020 Allows the use of the famous dontdiff file as follows to find
1021 out about uncommitted files just as dontdiff is used with
1023 git-ls-files --others --exclude-from=dontdiff
1026 Identify the file status with the following tags (followed by
1027 a space) at the start of each line:
1034 show files just outputs the filename unless --stage is specified in
1035 which case it outputs:
1037 [<tag> ]<mode> <object> <stage> <file>
1039 git-ls-files --unmerged" and "git-ls-files --stage " can be used to examine
1040 detailed information on unmerged paths.
1042 For an unmerged path, instead of recording a single mode/SHA1 pair,
1043 the dircache records up to three such pairs; one from tree O in stage
1044 1, A in stage 2, and B in stage 3. This information can be used by
1045 the user (or Cogito) to see what should eventually be recorded at the
1046 path. (see read-cache for more information on state)
1052 ################################################################
1054 git-unpack-file <blob>
1056 Creates a file holding the contents of the blob specified by sha1. It
1057 returns the name of the temporary file in the following format:
1063 ################################################################
1066 [--add] [--remove] [--refresh]
1068 [--force-remove <file>]
1069 [--cacheinfo <mode> <object> <file>]*
1072 Modifies the index or directory cache. Each file mentioned is updated
1073 into the cache and any 'unmerged' or 'needs updating' state is
1076 The way git-update-cache handles files it is told about can be modified
1077 using the various options:
1080 If a specified file isn't in the cache already then it's
1082 Default behaviour is to ignore new files.
1085 If a specified file is in the cache but is missing then it's
1087 Default behaviour is to ignore removed file.
1090 Looks at the current cache and checks to see if merges or
1091 updates are needed by checking stat() information.
1094 Ignores missing files during a --refresh
1096 --cacheinfo <mode> <object> <path>
1097 Directly insert the specified info into the cache.
1100 Remove the file from the index even when the working directory
1101 still has such a file.
1104 Do not interpret any more arguments as options.
1108 Note that files begining with '.' are discarded. This includes
1109 "./file" and "dir/./file". If you don't want this, then use
1111 The same applies to directories ending '/' and paths with '//'
1114 --refresh does not calculate a new sha1 file or bring the cache
1115 up-to-date for mode/content changes. But what it _does_ do is to
1116 "re-match" the stat information of a file with the cache, so that you
1117 can refresh the cache for a file that hasn't been changed but where
1118 the stat entry is out of date.
1120 For example, you'd want to do this after doing a "git-read-tree", to link
1121 up the stat cache details with the proper files.
1124 --cacheinfo is used to register a file that is not in the current
1125 working directory. This is useful for minimum-checkout merging.
1127 To pretend you have a file with mode and sha1 at path, say:
1129 $ git-update-cache --cacheinfo mode sha1 path
1131 To update and refresh only the files already checked out:
1133 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
1136 ################################################################
1139 git-write-blob <any-file-on-the-filesystem>
1141 Writes the contents of the named file (which can be outside of the work
1142 tree) as a blob into the object database, and reports its object ID to its
1143 standard output. This is used by git-merge-one-file-script to update the
1144 cache without modifying files in the work tree.
1147 ################################################################
1151 Creates a tree object using the current cache.
1153 The cache must be merged.
1155 Conceptually, git-write-tree sync()s the current directory cache contents
1156 into a set of tree files.
1157 In order to have that match what is actually in your directory right
1158 now, you need to have done a "git-update-cache" phase before you did the
1162 ################################################################
1164 Output format from git-diff-cache, git-diff-tree and git-diff-files.
1166 These commands all compare two sets of things; what are
1167 compared are different:
1169 git-diff-cache <tree-ish>
1171 compares the <tree-ish> and the files on the filesystem.
1173 git-diff-cache --cached <tree-ish>
1175 compares the <tree-ish> and the cache.
1177 git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]
1179 compares the trees named by the two arguments.
1181 git-diff-files [<pattern>...]
1183 compares the cache and the files on the filesystem.
1185 The following desription uses "old" and "new" to mean those
1188 For files in old but not in new (i.e. removed):
1189 -<mode> \t <type> \t <object> \t <path>
1191 For files not in old but in new (i.e. added):
1192 +<mode> \t <type> \t <object> \t <path>
1194 For files that differ:
1195 *<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path>
1197 <new-sha1> is shown as all 0's if new is a file on the
1198 filesystem and it is out of sync with the cache. Example:
1200 *100644->100644 blob 5be4a4.......->000000....... file.c
1202 ################################################################
1206 When git-diff-cache, git-diff-tree, or git-diff-files are run with a -p
1207 option, they do not produce the output described in "Output format from
1208 git-diff-cache, git-diff-tree and git-diff-files" section. It instead
1209 produces a patch file.
1211 The patch generation can be customized at two levels. This
1212 customization also applies to git-diff-tree-helper.
1214 1. When the environment variable GIT_EXTERNAL_DIFF is not set,
1215 these commands internally invoke diff like this:
1217 diff -L a/<path> -L a/<path> -pu <old> <new>
1219 For added files, /dev/null is used for <old>. For removed
1220 files, /dev/null is used for <new>
1222 The diff formatting options can be customized via the
1223 environment variable GIT_DIFF_OPTS. For example, if you
1224 prefer context diff:
1226 GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)
1229 2. When the environment variable GIT_EXTERNAL_DIFF is set, the
1230 program named by it is called, instead of the diff invocation
1233 For a path that is added, removed, or modified,
1234 GIT_EXTERNAL_DIFF is called with 7 parameters:
1236 path old-file old-hex old-mode new-file new-hex new-mode
1239 <old|new>-file are files GIT_EXTERNAL_DIFF can use to read the
1240 contents of <old|ne>,
1241 <old|new>-hex are the 40-hexdigit SHA1 hashes,
1242 <old|new>-mode are the octal representation of the file modes.
1244 The file parameters can point at the user's working file (e.g. new-file
1245 in git-diff-files), /dev/null (e.g. old-file when a new file is added),
1246 or a temporary file (e.g. old-file in the cache). GIT_EXTERNAL_DIFF
1247 should not worry about unlinking the temporary file --- it is removed
1248 when GIT_EXTERNAL_DIFF exits.
1250 For a path that is unmerged, GIT_EXTERNAL_DIFF is called with
1253 ################################################################
1255 Terminology: - see README for description
1256 Each line contains terms used interchangeably
1258 object database, .git directory
1259 directory cache, index
1260 id, sha1, sha1-id, sha1 hash
1264 commit, commit object
1270 git Environment Variables