mirror of
https://github.com/git/git
synced 2024-08-27 11:39:22 +00:00
![Junio C Hamano](/assets/img/avatar_default.png)
This updates the usage message string and Documentation/core-git.txt to describe the new flags added to the git-diff-tree command. Signed-off-by: Junio C Hamano <junkio@cox.net> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
1308 lines
40 KiB
Plaintext
1308 lines
40 KiB
Plaintext
This file contains reference information for the core git commands.
|
|
|
|
The README contains much useful definition and clarification
|
|
info - read that first. And of the commands, I suggest reading
|
|
'git-update-cache' and 'git-read-tree' first - I wish I had!
|
|
|
|
David Greaves <david@dgreaves.com>
|
|
24/4/05
|
|
|
|
Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to
|
|
reflect recent changes.
|
|
|
|
Identifier terminology used:
|
|
|
|
<object>
|
|
Indicates any object sha1 identifier
|
|
|
|
<blob>
|
|
Indicates a blob object sha1 identifier
|
|
|
|
<tree>
|
|
Indicates a tree object sha1 identifier
|
|
|
|
<commit>
|
|
Indicates a commit object sha1 identifier
|
|
|
|
<tree-ish>
|
|
Indicates a tree, commit or tag object sha1 identifier.
|
|
A command that takes a <tree-ish> argument ultimately
|
|
wants to operate on a <tree> object but automatically
|
|
dereferences <commit> and <tag> that points at a
|
|
<tree>.
|
|
|
|
<type>
|
|
Indicates that an object type is required.
|
|
Currently one of: blob/tree/commit/tag
|
|
|
|
<file>
|
|
Indicates a filename - always relative to the root of
|
|
the tree structure GIT_INDEX_FILE describes.
|
|
|
|
|
|
################################################################
|
|
git-apply-patch-script
|
|
|
|
This is a sample script to be used as GIT_EXTERNAL_DIFF to apply
|
|
differences git-diff-* family of commands reports to the current
|
|
work tree.
|
|
|
|
|
|
################################################################
|
|
git-cat-file
|
|
git-cat-file (-t | <type>) <object>
|
|
|
|
Provides contents or type of objects in the repository. The type
|
|
is required if -t is not being used to find the object type.
|
|
|
|
<object>
|
|
The sha1 identifier of the object.
|
|
|
|
-t
|
|
Instead of the content, show the object type identified
|
|
by <object>.
|
|
|
|
<type>
|
|
Typically this matches the real type of <object> but
|
|
asking for type that can trivially dereferenced from the
|
|
given <object> is also permitted. An example is to ask
|
|
"tree" with <object> for a commit object that contains
|
|
it, or to ask "blob" with <object> for a tag object that
|
|
points at it.
|
|
|
|
Output
|
|
|
|
If -t is specified, one of the <type>.
|
|
|
|
Otherwise the raw (though uncompressed) contents of the <object> will
|
|
be returned.
|
|
|
|
|
|
################################################################
|
|
git-check-files
|
|
git-check-files <file>...
|
|
|
|
Check that a list of files are up-to-date between the filesystem and
|
|
the cache. Used to verify a patch target before doing a patch.
|
|
|
|
Files that do not exist on the filesystem are considered up-to-date
|
|
(whether or not they are in the cache).
|
|
|
|
Emits an error message on failure.
|
|
preparing to update existing file <file> not in cache
|
|
<file> exists but is not in the cache
|
|
|
|
preparing to update file <file> not uptodate in cache
|
|
<file> on disk is not up-to-date with the cache
|
|
|
|
Exits with a status code indicating success if all files are
|
|
up-to-date.
|
|
|
|
see also: git-update-cache
|
|
|
|
|
|
################################################################
|
|
git-checkout-cache
|
|
git-checkout-cache [-q] [-a] [-f] [-n] [--prefix=<string>]
|
|
[--] <file>...
|
|
|
|
Will copy all files listed from the cache to the working directory
|
|
(not overwriting existing files).
|
|
|
|
-q
|
|
be quiet if files exist or are not in the cache
|
|
|
|
-f
|
|
forces overwrite of existing files
|
|
|
|
-a
|
|
checks out all files in the cache (will then continue to
|
|
process listed files).
|
|
|
|
-n
|
|
Don't checkout new files, only refresh files already checked
|
|
out.
|
|
|
|
--prefix=<string>
|
|
When creating files, prepend <string> (usually a directory
|
|
including a trailing /)
|
|
|
|
--
|
|
Do not interpret any more arguments as options.
|
|
|
|
Note that the order of the flags matters:
|
|
|
|
git-checkout-cache -a -f file.c
|
|
|
|
will first check out all files listed in the cache (but not overwrite
|
|
any old ones), and then force-checkout file.c a second time (ie that
|
|
one _will_ overwrite any old contents with the same filename).
|
|
|
|
Also, just doing "git-checkout-cache" does nothing. You probably meant
|
|
"git-checkout-cache -a". And if you want to force it, you want
|
|
"git-checkout-cache -f -a".
|
|
|
|
Intuitiveness is not the goal here. Repeatability is. The reason for
|
|
the "no arguments means no work" thing is that from scripts you are
|
|
supposed to be able to do things like
|
|
|
|
find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f --
|
|
|
|
which will force all existing *.h files to be replaced with their
|
|
cached copies. If an empty command line implied "all", then this would
|
|
force-refresh everything in the cache, which was not the point.
|
|
|
|
To update and refresh only the files already checked out:
|
|
|
|
git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
|
|
|
|
Oh, and the "--" is just a good idea when you know the rest will be
|
|
filenames. Just so that you wouldn't have a filename of "-a" causing
|
|
problems (not possible in the above example, but get used to it in
|
|
scripting!).
|
|
|
|
The prefix ability basically makes it trivial to use git-checkout-cache as
|
|
a "git-export as tree" function. Just read the desired tree into the
|
|
index, and do a
|
|
|
|
git-checkout-cache --prefix=git-export-dir/ -a
|
|
|
|
and git-checkout-cache will "git-export" the cache into the specified
|
|
directory.
|
|
|
|
NOTE! The final "/" is important. The git-exported name is literally just
|
|
prefixed with the specified string, so you can also do something like
|
|
|
|
git-checkout-cache --prefix=.merged- Makefile
|
|
|
|
to check out the currently cached copy of "Makefile" into the file
|
|
".merged-Makefile".
|
|
|
|
|
|
################################################################
|
|
git-commit-tree
|
|
git-commit-tree <tree> [-p <parent commit>]* < changelog
|
|
|
|
Creates a new commit object based on the provided tree object and
|
|
emits the new commit object id on stdout. If no parent is given then
|
|
it is considered to be an initial tree.
|
|
|
|
A commit object usually has 1 parent (a commit after a change) or up
|
|
to 16 parents. More than one parent represents a merge of branches
|
|
that led to them.
|
|
|
|
While a tree represents a particular directory state of a working
|
|
directory, a commit represents that state in "time", and explains how
|
|
to get there.
|
|
|
|
Normally a commit would identify a new "HEAD" state, and while git
|
|
doesn't care where you save the note about that state, in practice we
|
|
tend to just write the result to the file ".git/HEAD", so that we can
|
|
always see what the last committed state was.
|
|
|
|
Options
|
|
|
|
<tree>
|
|
An existing tree object
|
|
|
|
-p <parent commit>
|
|
Each -p indicates a the id of a parent commit object.
|
|
|
|
|
|
Commit Information
|
|
|
|
A commit encapsulates:
|
|
all parent object ids
|
|
author name, email and date
|
|
committer name and email and the commit time.
|
|
|
|
If not provided, git-commit-tree uses your name, hostname and domain to
|
|
provide author and committer info. This can be overridden using the
|
|
following environment variables.
|
|
AUTHOR_NAME
|
|
AUTHOR_EMAIL
|
|
AUTHOR_DATE
|
|
COMMIT_AUTHOR_NAME
|
|
COMMIT_AUTHOR_EMAIL
|
|
(nb <,> and '\n's are stripped)
|
|
|
|
A commit comment is read from stdin (max 999 chars). If a changelog
|
|
entry is not provided via '<' redirection, git-commit-tree will just wait
|
|
for one to be entered and terminated with ^D
|
|
|
|
see also: git-write-tree
|
|
|
|
|
|
################################################################
|
|
git-convert-cache
|
|
|
|
Converts old-style GIT repository to the latest.
|
|
|
|
|
|
################################################################
|
|
git-diff-cache
|
|
git-diff-cache [-p] [-r] [-z] [--cached] <tree-ish>
|
|
|
|
Compares the content and mode of the blobs found via a tree object
|
|
with the content of the current cache and, optionally ignoring the
|
|
stat state of the file on disk.
|
|
|
|
<tree-ish>
|
|
The id of a tree object to diff against.
|
|
|
|
-p
|
|
Generate patch (see section on generating patches)
|
|
|
|
-r
|
|
This flag does not mean anything. It is there only to match
|
|
git-diff-tree. Unlike git-diff-tree, git-diff-cache always looks
|
|
at all the subdirectories.
|
|
|
|
-z
|
|
\0 line termination on output
|
|
|
|
--cached
|
|
do not consider the on-disk file at all
|
|
|
|
Output format:
|
|
|
|
See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
|
|
section.
|
|
|
|
Operating Modes
|
|
|
|
You can choose whether you want to trust the index file entirely
|
|
(using the "--cached" flag) or ask the diff logic to show any files
|
|
that don't match the stat state as being "tentatively changed". Both
|
|
of these operations are very useful indeed.
|
|
|
|
Cached Mode
|
|
|
|
If --cached is specified, it allows you to ask:
|
|
|
|
show me the differences between HEAD and the current index
|
|
contents (the ones I'd write with a "git-write-tree")
|
|
|
|
For example, let's say that you have worked on your index file, and are
|
|
ready to commit. You want to see eactly _what_ you are going to commit is
|
|
without having to write a new tree object and compare it that way, and to
|
|
do that, you just do
|
|
|
|
git-diff-cache --cached $(cat .git/HEAD)
|
|
|
|
Example: let's say I had renamed "commit.c" to "git-commit.c", and I had
|
|
done an "git-update-cache" to make that effective in the index file.
|
|
"git-diff-files" wouldn't show anything at all, since the index file
|
|
matches my working directory. But doing a git-diff-cache does:
|
|
|
|
torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD)
|
|
-100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c
|
|
+100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c
|
|
|
|
You can trivially see that the above is a rename.
|
|
|
|
In fact, "git-diff-cache --cached" _should_ always be entirely equivalent to
|
|
actually doing a "git-write-tree" and comparing that. Except this one is much
|
|
nicer for the case where you just want to check where you are.
|
|
|
|
So doing a "git-diff-cache --cached" is basically very useful when you are
|
|
asking yourself "what have I already marked for being committed, and
|
|
what's the difference to a previous tree".
|
|
|
|
Non-cached Mode
|
|
|
|
The "non-cached" mode takes a different approach, and is potentially the
|
|
even more useful of the two in that what it does can't be emulated with a
|
|
"git-write-tree + git-diff-tree". Thus that's the default mode. The
|
|
non-cached version asks the question
|
|
|
|
"show me the differences between HEAD and the currently checked out
|
|
tree - index contents _and_ files that aren't up-to-date"
|
|
|
|
which is obviously a very useful question too, since that tells you what
|
|
you _could_ commit. Again, the output matches the "git-diff-tree -r"
|
|
output to a tee, but with a twist.
|
|
|
|
The twist is that if some file doesn't match the cache, we don't have a
|
|
backing store thing for it, and we use the magic "all-zero" sha1 to show
|
|
that. So let's say that you have edited "kernel/sched.c", but have not
|
|
actually done an git-update-cache on it yet - there is no "object" associated
|
|
with the new state, and you get:
|
|
|
|
torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD )
|
|
*100644->100664 blob 7476bb......->000000...... kernel/sched.c
|
|
|
|
ie it shows that the tree has changed, and that "kernel/sched.c" has is
|
|
not up-to-date and may contain new stuff. The all-zero sha1 means that to
|
|
get the real diff, you need to look at the object in the working directory
|
|
directly rather than do an object-to-object diff.
|
|
|
|
NOTE! As with other commands of this type, "git-diff-cache" does not
|
|
actually look at the contents of the file at all. So maybe
|
|
"kernel/sched.c" hasn't actually changed, and it's just that you touched
|
|
it. In either case, it's a note that you need to upate-cache it to make
|
|
the cache be in sync.
|
|
|
|
NOTE 2! You can have a mixture of files show up as "has been updated" and
|
|
"is still dirty in the working directory" together. You can always tell
|
|
which file is in which state, since the "has been updated" ones show a
|
|
valid sha1, and the "not in sync with the index" ones will always have the
|
|
special all-zero sha1.
|
|
|
|
|
|
################################################################
|
|
git-diff-tree
|
|
git-diff-tree [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]*
|
|
|
|
Compares the content and mode of the blobs found via two tree objects.
|
|
|
|
Note that git-diff-tree can use the tree encapsulated in a commit object.
|
|
|
|
<tree-ish>
|
|
The id of a tree object.
|
|
|
|
<pattern>
|
|
If provided, the results are limited to a subset of files
|
|
matching one of these prefix strings.
|
|
ie file matches /^<pattern1>|<pattern2>|.../
|
|
Note that pattern does not provide any wildcard or regexp
|
|
features.
|
|
|
|
-p
|
|
generate patch (see section on generating patches). For
|
|
git-diff-tree, this flag implies -r as well.
|
|
|
|
-r
|
|
recurse
|
|
|
|
-z
|
|
\0 line termination on output
|
|
|
|
--stdin
|
|
When --stdin is specified, the command does not take
|
|
<tree-ish> arguments from the command line. Instead, it
|
|
reads either one <commit> or a pair of <tree-ish>
|
|
separated with a single space from its standard input.
|
|
|
|
When a single commit is given on one line of such input,
|
|
it compares the commit with its parents. The following
|
|
flags further affects its behaviour. This does not
|
|
apply to the case where two <tree-ish> separated with a
|
|
single space are given.
|
|
|
|
-m
|
|
By default, "git-diff-tree --stdin" does not show
|
|
differences for merge commits. With this flag, it shows
|
|
differences to that commit from all of its parents.
|
|
|
|
-s
|
|
By default, "git-diff-tree --stdin" shows differences,
|
|
either in machine-readable form (without -p) or in patch
|
|
form (with -p). This output can be supressed. It is
|
|
only useful with -v flag.
|
|
|
|
-v
|
|
This flag causes "git-diff-tree --stdin" to also show
|
|
the commit message before the differences.
|
|
|
|
|
|
Limiting Output
|
|
|
|
If you're only interested in differences in a subset of files, for
|
|
example some architecture-specific files, you might do:
|
|
|
|
git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64
|
|
|
|
and it will only show you what changed in those two directories.
|
|
|
|
Or if you are searching for what changed in just kernel/sched.c, just do
|
|
|
|
git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c
|
|
|
|
and it will ignore all differences to other files.
|
|
|
|
The pattern is always the prefix, and is matched exactly. There are no
|
|
wildcards. Even stricter, it has to match complete path comonent.
|
|
I.e. "foo" does not pick up "foobar.h". "foo" does match "foo/bar.h"
|
|
so it can be used to name subdirectories.
|
|
|
|
Output format:
|
|
|
|
See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
|
|
section.
|
|
|
|
An example of normal usage is:
|
|
|
|
torvalds@ppc970:~/git> git-diff-tree 5319e4......
|
|
*100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c
|
|
|
|
which tells you that the last commit changed just one file (it's from
|
|
this one:
|
|
|
|
commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
|
|
tree 5319e4d609cdd282069cc4dce33c1db559539b03
|
|
parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
|
|
author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
|
|
committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
|
|
|
|
Make "git-fsck-cache" print out all the root commits it finds.
|
|
|
|
Once I do the reference tracking, I'll also make it print out all the
|
|
HEAD commits it finds, which is even more interesting.
|
|
|
|
in case you care).
|
|
|
|
|
|
################################################################
|
|
git-diff-tree-helper
|
|
git-diff-tree-helper [-z] [-R]
|
|
|
|
Reads output from git-diff-cache, git-diff-tree and git-diff-files and
|
|
generates patch format output.
|
|
|
|
-z
|
|
\0 line termination on input
|
|
|
|
-R
|
|
Output diff in reverse. This is useful for displaying output from
|
|
git-diff-cache which always compares tree with cache or working
|
|
file. E.g.
|
|
|
|
git-diff-cache <tree> | git-diff-tree-helper -R file.c
|
|
|
|
would show a diff to bring the working file back to what is in the
|
|
<tree>.
|
|
|
|
See also the section on generating patches.
|
|
|
|
|
|
################################################################
|
|
git-fsck-cache
|
|
git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*]
|
|
|
|
Verifies the connectivity and validity of the objects in the database.
|
|
|
|
<object>
|
|
An object to treat as the head of an unreachability trace.
|
|
|
|
--unreachable
|
|
Print out objects that exist but that aren't readable from any
|
|
of the specified head nodes.
|
|
|
|
--root
|
|
Report root nodes.
|
|
|
|
--tags
|
|
Report tags.
|
|
|
|
--cache
|
|
Consider any object recorded in the cache also as a head node for
|
|
an unreachability trace.
|
|
|
|
It tests SHA1 and general object sanity, and it does full tracking of
|
|
the resulting reachability and everything else. It prints out any
|
|
corruption it finds (missing or bad objects), and if you use the
|
|
"--unreachable" flag it will also print out objects that exist but
|
|
that aren't readable from any of the specified head nodes.
|
|
|
|
So for example
|
|
|
|
git-fsck-cache --unreachable $(cat .git/HEAD)
|
|
|
|
or, for Cogito users:
|
|
|
|
git-fsck-cache --unreachable $(cat .git/refs/heads/*)
|
|
|
|
will do quite a _lot_ of verification on the tree. There are a few
|
|
extra validity tests to be added (make sure that tree objects are
|
|
sorted properly etc), but on the whole if "git-fsck-cache" is happy, you
|
|
do have a valid tree.
|
|
|
|
Any corrupt objects you will have to find in backups or other archives
|
|
(ie you can just remove them and do an "rsync" with some other site in
|
|
the hopes that somebody else has the object you have corrupted).
|
|
|
|
Of course, "valid tree" doesn't mean that it wasn't generated by some
|
|
evil person, and the end result might be crap. Git is a revision
|
|
tracking system, not a quality assurance system ;)
|
|
|
|
Extracted Diagnostics
|
|
|
|
expect dangling commits - potential heads - due to lack of head information
|
|
You haven't specified any nodes as heads so it won't be
|
|
possible to differentiate between un-parented commits and
|
|
root nodes.
|
|
|
|
missing sha1 directory '<dir>'
|
|
The directory holding the sha1 objects is missing.
|
|
|
|
unreachable <type> <object>
|
|
The <type> object <object>, isn't actually referred to directly
|
|
or indirectly in any of the trees or commits seen. This can
|
|
mean that there's another root na SHA1_ode that you're not specifying
|
|
or that the tree is corrupt. If you haven't missed a root node
|
|
then you might as well delete unreachable nodes since they
|
|
can't be used.
|
|
|
|
missing <type> <object>
|
|
The <type> object <object>, is referred to but isn't present in
|
|
the database.
|
|
|
|
dangling <type> <object>
|
|
The <type> object <object>, is present in the database but never
|
|
_directly_ used. A dangling commit could be a root node.
|
|
|
|
warning: git-fsck-cache: tree <tree> has full pathnames in it
|
|
And it shouldn't...
|
|
|
|
sha1 mismatch <object>
|
|
The database has an object who's sha1 doesn't match the
|
|
database value.
|
|
This indicates a ??serious?? data integrity problem.
|
|
(note: this error occured during early git development when
|
|
the database format changed.)
|
|
|
|
Environment Variables
|
|
|
|
SHA1_FILE_DIRECTORY
|
|
used to specify the object database root (usually .git/objects)
|
|
|
|
GIT_INDEX_FILE
|
|
used to specify the cache
|
|
|
|
|
|
################################################################
|
|
git-export
|
|
git-export top [base]
|
|
|
|
Exports each commit and diff against each of its parents, between
|
|
top and base. If base is not specified it exports everything.
|
|
|
|
|
|
################################################################
|
|
git-init-db
|
|
git-init-db
|
|
|
|
This simply creates an empty git object database - basically a .git
|
|
directory and .git/object/??/ directories.
|
|
|
|
If the object storage directory is specified via the SHA1_FILE_DIRECTORY
|
|
environment variable then the sha1 directories are created underneath -
|
|
otherwise the default .git/objects directory is used.
|
|
|
|
git-init-db won't hurt an existing repository.
|
|
|
|
|
|
################################################################
|
|
git-http-pull
|
|
|
|
git-http-pull [-c] [-t] [-a] [-v] commit-id url
|
|
|
|
Downloads a remote GIT repository via HTTP protocol.
|
|
|
|
-c
|
|
Get the commit objects.
|
|
-t
|
|
Get trees associated with the commit objects.
|
|
-a
|
|
Get all the objects.
|
|
-v
|
|
Report what is downloaded.
|
|
|
|
|
|
################################################################
|
|
git-local-pull
|
|
|
|
git-local-pull [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path
|
|
|
|
Downloads another GIT repository on a local system.
|
|
|
|
-c
|
|
Get the commit objects.
|
|
-t
|
|
Get trees associated with the commit objects.
|
|
-a
|
|
Get all the objects.
|
|
-v
|
|
Report what is downloaded.
|
|
|
|
################################################################
|
|
git-ls-tree
|
|
git-ls-tree [-r] [-z] <tree-ish>
|
|
|
|
Converts the tree object to a human readable (and script processable)
|
|
form.
|
|
|
|
<tree-ish>
|
|
Id of a tree.
|
|
|
|
-r
|
|
recurse into sub-trees
|
|
|
|
-z
|
|
\0 line termination on output
|
|
|
|
Output Format
|
|
<mode>\t <type>\t <object>\t <file>
|
|
|
|
|
|
################################################################
|
|
git-merge-base
|
|
git-merge-base <commit> <commit>
|
|
|
|
git-merge-base finds as good a common ancestor as possible. Given a
|
|
selection of equally good common ancestors it should not be relied on
|
|
to decide in any particular way.
|
|
|
|
The git-merge-base algorithm is still in flux - use the source...
|
|
|
|
|
|
################################################################
|
|
git-merge-cache
|
|
git-merge-cache <merge-program> (-a | -- | <file>*)
|
|
|
|
This looks up the <file>(s) in the cache and, if there are any merge
|
|
entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty
|
|
argument if no file), and <file> as argument 4. File modes for the three
|
|
files are passed as arguments 5, 6 and 7.
|
|
|
|
--
|
|
Interpret all future arguments as filenames.
|
|
|
|
-a
|
|
Run merge against all files in the cache that need merging.
|
|
|
|
If git-merge-cache is called with multiple <file>s (or -a) then it
|
|
processes them in turn only stopping if merge returns a non-zero exit
|
|
code.
|
|
|
|
Typically this is run with the a script calling the merge command from
|
|
the RCS package.
|
|
|
|
A sample script called git-merge-one-file-script is included in the
|
|
ditribution.
|
|
|
|
ALERT ALERT ALERT! The git "merge object order" is different from the
|
|
RCS "merge" program merge object order. In the above ordering, the
|
|
original is first. But the argument order to the 3-way merge program
|
|
"merge" is to have the original in the middle. Don't ask me why.
|
|
|
|
Examples:
|
|
|
|
torvalds@ppc970:~/merge-test> git-merge-cache cat MM
|
|
This is MM from the original tree. # original
|
|
This is modified MM in the branch A. # merge1
|
|
This is modified MM in the branch B. # merge2
|
|
This is modified MM in the branch B. # current contents
|
|
|
|
or
|
|
|
|
torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM
|
|
cat: : No such file or directory
|
|
This is added AA in the branch A.
|
|
This is added AA in the branch B.
|
|
This is added AA in the branch B.
|
|
fatal: merge program failed
|
|
|
|
where the latter example shows how "git-merge-cache" will stop trying to
|
|
merge once anything has returned an error (ie "cat" returned an error
|
|
for the AA file, because it didn't exist in the original, and thus
|
|
"git-merge-cache" didn't even try to merge the MM thing).
|
|
|
|
################################################################
|
|
git-merge-one-file-script
|
|
|
|
This is the standard helper program to use with git-merge-cache
|
|
to resolve a merge after the trivial merge done with git-read-tree -m.
|
|
|
|
################################################################
|
|
git-mktag
|
|
|
|
Reads a tag contents from its standard input and creates a tag object.
|
|
The input must be a well formed tag object.
|
|
|
|
|
|
################################################################
|
|
git-prune-script
|
|
|
|
This runs git-fsck-cache --unreachable program using the heads specified
|
|
on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is
|
|
specified), and prunes all unreachable objects from the object database.
|
|
|
|
|
|
################################################################
|
|
git-pull-script
|
|
|
|
This script is used by Linus to pull from a remote repository and perform
|
|
a merge.
|
|
|
|
|
|
################################################################
|
|
git-read-tree
|
|
git-read-tree (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"
|
|
|
|
Reads the tree information given by <tree> into the directory cache,
|
|
but does not actually _update_ any of the files it "caches". (see:
|
|
git-checkout-cache)
|
|
|
|
Optionally, it can merge a tree into the cache or perform a 3-way
|
|
merge.
|
|
|
|
Trivial merges are done by git-read-tree itself. Only conflicting paths
|
|
will be in unmerged state when git-read-tree returns.
|
|
|
|
-m
|
|
Perform a merge, not just a read
|
|
|
|
<tree-ish#>
|
|
The id of the tree object(s) to be read/merged.
|
|
|
|
|
|
Merging
|
|
If -m is specified, git-read-tree performs 2 kinds of merge, a single tree
|
|
merge if only 1 tree is given or a 3-way merge if 3 trees are
|
|
provided.
|
|
|
|
Single Tree Merge
|
|
If only 1 tree is specified, git-read-tree operates as if the user did not
|
|
specify "-m", except that if the original cache has an entry for a
|
|
given pathname; and the contents of the path matches with the tree
|
|
being read, the stat info from the cache is used. (In other words, the
|
|
cache's stat()s take precedence over the merged tree's)
|
|
|
|
That means that if you do a "git-read-tree -m <newtree>" followed by a
|
|
"git-checkout-cache -f -a", the git-checkout-cache only checks out the stuff
|
|
that really changed.
|
|
|
|
This is used to avoid unnecessary false hits when git-diff-files is
|
|
run after git-read-tree.
|
|
|
|
3-Way Merge
|
|
Each "index" entry has two bits worth of "stage" state. stage 0 is the
|
|
normal one, and is the only one you'd see in any kind of normal use.
|
|
|
|
However, when you do "git-read-tree" with three trees, the "stage"
|
|
starts out at 1.
|
|
|
|
This means that you can do
|
|
|
|
git-read-tree -m <tree1> <tree2> <tree3>
|
|
|
|
and you will end up with an index with all of the <tree1> entries in
|
|
"stage1", all of the <tree2> entries in "stage2" and all of the
|
|
<tree3> entries in "stage3".
|
|
|
|
Furthermore, "git-read-tree" has special-case logic that says: if you see
|
|
a file that matches in all respects in the following states, it
|
|
"collapses" back to "stage0":
|
|
|
|
- stage 2 and 3 are the same; take one or the other (it makes no
|
|
difference - the same work has been done on stage 2 and 3)
|
|
|
|
- stage 1 and stage 2 are the same and stage 3 is different; take
|
|
stage 3 (some work has been done on stage 3)
|
|
|
|
- stage 1 and stage 3 are the same and stage 2 is different take
|
|
stage 2 (some work has been done on stage 2)
|
|
|
|
The git-write-tree command refuses to write a nonsensical tree, and it
|
|
will complain about unmerged entries if it sees a single entry that is not
|
|
stage 0.
|
|
|
|
Ok, this all sounds like a collection of totally nonsensical rules,
|
|
but it's actually exactly what you want in order to do a fast
|
|
merge. The different stages represent the "result tree" (stage 0, aka
|
|
"merged"), the original tree (stage 1, aka "orig"), and the two trees
|
|
you are trying to merge (stage 2 and 3 respectively).
|
|
|
|
In fact, the way "git-read-tree" works, it's entirely agnostic about how
|
|
you assign the stages, and you could really assign them any which way,
|
|
and the above is just a suggested way to do it (except since
|
|
"git-write-tree" refuses to write anything but stage0 entries, it makes
|
|
sense to always consider stage 0 to be the "full merge" state).
|
|
|
|
So what happens? Try it out. Select the original tree, and two trees
|
|
to merge, and look how it works:
|
|
|
|
- if a file exists in identical format in all three trees, it will
|
|
automatically collapse to "merged" state by the new git-read-tree.
|
|
|
|
- a file that has _any_ difference what-so-ever in the three trees
|
|
will stay as separate entries in the index. It's up to "script
|
|
policy" to determine how to remove the non-0 stages, and insert a
|
|
merged version. But since the index is always sorted, they're easy
|
|
to find: they'll be clustered together.
|
|
|
|
- the index file saves and restores with all this information, so you
|
|
can merge things incrementally, but as long as it has entries in
|
|
stages 1/2/3 (ie "unmerged entries") you can't write the result.
|
|
|
|
So now the merge algorithm ends up being really simple:
|
|
|
|
- you walk the index in order, and ignore all entries of stage 0,
|
|
since they've already been done.
|
|
|
|
- if you find a "stage1", but no matching "stage2" or "stage3", you
|
|
know it's been removed from both trees (it only existed in the
|
|
original tree), and you remove that entry. - if you find a
|
|
matching "stage2" and "stage3" tree, you remove one of them, and
|
|
turn the other into a "stage0" entry. Remove any matching "stage1"
|
|
entry if it exists too. .. all the normal trivial rules ..
|
|
|
|
Incidentally - it also means that you don't even have to have a separate
|
|
subdirectory for this. All the information literally is in the index file,
|
|
which is a temporary thing anyway. There is no need to worry about what is
|
|
in the working directory, since it is never shown and never used.
|
|
|
|
see also:
|
|
git-write-tree
|
|
git-ls-files
|
|
|
|
|
|
################################################################
|
|
git-resolve-script
|
|
|
|
This script is used by Linus to merge two trees.
|
|
|
|
|
|
################################################################
|
|
git-rev-list <commit>
|
|
|
|
Lists commit objects in reverse chronological order starting at the
|
|
given commit, taking ancestry relationship into account. This is
|
|
useful to produce human-readable log output.
|
|
|
|
|
|
################################################################
|
|
git-rev-tree
|
|
git-rev-tree [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]
|
|
|
|
Provides the revision tree for one or more commits.
|
|
|
|
--edges
|
|
Show edges (ie places where the marking changes between parent
|
|
and child)
|
|
|
|
--cache <cache-file>
|
|
Use the specified file as a cache from a previous git-rev-list run
|
|
to speed things up. Note that this "cache" is totally different
|
|
concept from the directory index. Also this option is not
|
|
implemented yet.
|
|
|
|
[^]<commit>
|
|
The commit id to trace (a leading caret means to ignore this
|
|
commit-id and below)
|
|
|
|
Output:
|
|
<date> <commit>:<flags> [<parent-commit>:<flags> ]*
|
|
|
|
<date>
|
|
Date in 'seconds since epoch'
|
|
|
|
<commit>
|
|
id of commit object
|
|
|
|
<parent-commit>
|
|
id of each parent commit object (>1 indicates a merge)
|
|
|
|
<flags>
|
|
|
|
The flags are read as a bitmask representing each commit
|
|
provided on the commandline. eg: given the command:
|
|
|
|
$ git-rev-tree <com1> <com2> <com3>
|
|
|
|
The output:
|
|
|
|
<date> <commit>:5
|
|
|
|
means that <commit> is reachable from <com1>(1) and <com3>(4)
|
|
|
|
A revtree can get quite large. git-rev-tree will eventually allow you to
|
|
cache previous state so that you don't have to follow the whole thing
|
|
down.
|
|
|
|
So the change difference between two commits is literally
|
|
|
|
git-rev-tree [commit-id1] > commit1-revtree
|
|
git-rev-tree [commit-id2] > commit2-revtree
|
|
join -t : commit1-revtree commit2-revtree > common-revisions
|
|
|
|
(this is also how to find the most common parent - you'd look at just
|
|
the head revisions - the ones that aren't referred to by other
|
|
revisions - in "common-revision", and figure out the best one. I
|
|
think.)
|
|
|
|
|
|
################################################################
|
|
git-rpull
|
|
|
|
git-rpull [-c] [-t] [-a] [-v] commit-id url
|
|
|
|
Pulls from a remote repository over ssh connection, invoking git-rpush on
|
|
the other end.
|
|
|
|
-c
|
|
Get the commit objects.
|
|
-t
|
|
Get trees associated with the commit objects.
|
|
-a
|
|
Get all the objects.
|
|
-v
|
|
Report what is downloaded.
|
|
|
|
|
|
################################################################
|
|
git-rpush
|
|
|
|
Helper "server-side" program used by git-rpull.
|
|
|
|
|
|
################################################################
|
|
git-diff-files
|
|
git-diff-files [-p] [-q] [-r] [-z] [<pattern>...]
|
|
|
|
Compares the files in the working tree and the cache. When paths
|
|
are specified, compares only those named paths. Otherwise all
|
|
entries in the cache are compared. The output format is the
|
|
same as git-diff-cache and git-diff-tree.
|
|
|
|
-p
|
|
generate patch (see section on generating patches).
|
|
|
|
-q
|
|
Remain silent even on nonexisting files
|
|
|
|
-r
|
|
This flag does not mean anything. It is there only to match
|
|
git-diff-tree. Unlike git-diff-tree, git-diff-files always looks
|
|
at all the subdirectories.
|
|
|
|
|
|
Output format:
|
|
|
|
See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
|
|
section.
|
|
|
|
|
|
################################################################
|
|
git-tag-script
|
|
|
|
This is an example script that uses git-mktag to create a tag object
|
|
signed with GPG.
|
|
|
|
|
|
################################################################
|
|
git-tar-tree
|
|
|
|
git-tar-tree <tree-ish> [ <base> ]
|
|
|
|
Creates a tar archive containing the tree structure for the named tree.
|
|
When <base> is specified it is added as a leading path as the files in the
|
|
generated tar archive.
|
|
|
|
|
|
################################################################
|
|
git-ls-files
|
|
git-ls-files [-z] [-t]
|
|
(--[cached|deleted|others|ignored|stage|unmerged])*
|
|
(-[c|d|o|i|s|u])*
|
|
[-x <pattern>|--exclude=<pattern>]
|
|
[-X <file>|--exclude-from=<file>]
|
|
|
|
This merges the file listing in the directory cache index with the
|
|
actual working directory list, and shows different combinations of the
|
|
two.
|
|
|
|
One or more of the options below may be used to determine the files
|
|
shown:
|
|
|
|
-c|--cached
|
|
Show cached files in the output (default)
|
|
|
|
-d|--deleted
|
|
Show deleted files in the output
|
|
|
|
-o|--others
|
|
Show other files in the output
|
|
|
|
-i|--ignored
|
|
Show ignored files in the output
|
|
Note the this also reverses any exclude list present.
|
|
|
|
-s|--stage
|
|
Show stage files in the output
|
|
|
|
-u|--unmerged
|
|
Show unmerged files in the output (forces --stage)
|
|
|
|
-z
|
|
\0 line termination on output
|
|
|
|
-x|--exclude=<pattern>
|
|
Skips files matching pattern.
|
|
Note that pattern is a shell wildcard pattern.
|
|
|
|
-X|--exclude-from=<file>
|
|
exclude patterns are read from <file>; 1 per line.
|
|
Allows the use of the famous dontdiff file as follows to find
|
|
out about uncommitted files just as dontdiff is used with
|
|
the diff command:
|
|
git-ls-files --others --exclude-from=dontdiff
|
|
|
|
-t
|
|
Identify the file status with the following tags (followed by
|
|
a space) at the start of each line:
|
|
H cached
|
|
M unmerged
|
|
R removed/deleted
|
|
? other
|
|
|
|
Output
|
|
show files just outputs the filename unless --stage is specified in
|
|
which case it outputs:
|
|
|
|
[<tag> ]<mode> <object> <stage> <file>
|
|
|
|
git-ls-files --unmerged" and "git-ls-files --stage " can be used to examine
|
|
detailed information on unmerged paths.
|
|
|
|
For an unmerged path, instead of recording a single mode/SHA1 pair,
|
|
the dircache records up to three such pairs; one from tree O in stage
|
|
1, A in stage 2, and B in stage 3. This information can be used by
|
|
the user (or Cogito) to see what should eventually be recorded at the
|
|
path. (see read-cache for more information on state)
|
|
|
|
see also:
|
|
read-cache
|
|
|
|
|
|
################################################################
|
|
git-unpack-file
|
|
git-unpack-file <blob>
|
|
|
|
Creates a file holding the contents of the blob specified by sha1. It
|
|
returns the name of the temporary file in the following format:
|
|
.merge_file_XXXXX
|
|
|
|
<blob>
|
|
Must be a blob id
|
|
|
|
################################################################
|
|
git-update-cache
|
|
git-update-cache
|
|
[--add] [--remove] [--refresh]
|
|
[--ignore-missing]
|
|
[--force-remove <file>]
|
|
[--cacheinfo <mode> <object> <file>]*
|
|
[--] [<file>]*
|
|
|
|
Modifies the index or directory cache. Each file mentioned is updated
|
|
into the cache and any 'unmerged' or 'needs updating' state is
|
|
cleared.
|
|
|
|
The way git-update-cache handles files it is told about can be modified
|
|
using the various options:
|
|
|
|
--add
|
|
If a specified file isn't in the cache already then it's
|
|
added.
|
|
Default behaviour is to ignore new files.
|
|
|
|
--remove
|
|
If a specified file is in the cache but is missing then it's
|
|
removed.
|
|
Default behaviour is to ignore removed file.
|
|
|
|
--refresh
|
|
Looks at the current cache and checks to see if merges or
|
|
updates are needed by checking stat() information.
|
|
|
|
--ignore-missing
|
|
Ignores missing files during a --refresh
|
|
|
|
--cacheinfo <mode> <object> <path>
|
|
Directly insert the specified info into the cache.
|
|
|
|
--force-remove
|
|
Remove the file from the index even when the working directory
|
|
still has such a file.
|
|
|
|
--
|
|
Do not interpret any more arguments as options.
|
|
|
|
<file>
|
|
Files to act on.
|
|
Note that files begining with '.' are discarded. This includes
|
|
"./file" and "dir/./file". If you don't want this, then use
|
|
cleaner names.
|
|
The same applies to directories ending '/' and paths with '//'
|
|
|
|
Using --refresh
|
|
--refresh does not calculate a new sha1 file or bring the cache
|
|
up-to-date for mode/content changes. But what it _does_ do is to
|
|
"re-match" the stat information of a file with the cache, so that you
|
|
can refresh the cache for a file that hasn't been changed but where
|
|
the stat entry is out of date.
|
|
|
|
For example, you'd want to do this after doing a "git-read-tree", to link
|
|
up the stat cache details with the proper files.
|
|
|
|
Using --cacheinfo
|
|
--cacheinfo is used to register a file that is not in the current
|
|
working directory. This is useful for minimum-checkout merging.
|
|
|
|
To pretend you have a file with mode and sha1 at path, say:
|
|
|
|
$ git-update-cache --cacheinfo mode sha1 path
|
|
|
|
To update and refresh only the files already checked out:
|
|
|
|
git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh
|
|
|
|
|
|
################################################################
|
|
git-write-blob
|
|
|
|
git-write-blob <any-file-on-the-filesystem>
|
|
|
|
Writes the contents of the named file (which can be outside of the work
|
|
tree) as a blob into the object database, and reports its object ID to its
|
|
standard output. This is used by git-merge-one-file-script to update the
|
|
cache without modifying files in the work tree.
|
|
|
|
|
|
################################################################
|
|
git-write-tree
|
|
git-write-tree
|
|
|
|
Creates a tree object using the current cache.
|
|
|
|
The cache must be merged.
|
|
|
|
Conceptually, git-write-tree sync()s the current directory cache contents
|
|
into a set of tree files.
|
|
In order to have that match what is actually in your directory right
|
|
now, you need to have done a "git-update-cache" phase before you did the
|
|
"git-write-tree".
|
|
|
|
|
|
################################################################
|
|
|
|
Output format from git-diff-cache, git-diff-tree and git-diff-files.
|
|
|
|
These commands all compare two sets of things; what are
|
|
compared are different:
|
|
|
|
git-diff-cache <tree-ish>
|
|
|
|
compares the <tree-ish> and the files on the filesystem.
|
|
|
|
git-diff-cache --cached <tree-ish>
|
|
|
|
compares the <tree-ish> and the cache.
|
|
|
|
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]
|
|
|
|
compares the trees named by the two arguments.
|
|
|
|
git-diff-files [<pattern>...]
|
|
|
|
compares the cache and the files on the filesystem.
|
|
|
|
The following desription uses "old" and "new" to mean those
|
|
compared entities.
|
|
|
|
For files in old but not in new (i.e. removed):
|
|
-<mode> \t <type> \t <object> \t <path>
|
|
|
|
For files not in old but in new (i.e. added):
|
|
+<mode> \t <type> \t <object> \t <path>
|
|
|
|
For files that differ:
|
|
*<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path>
|
|
|
|
<new-sha1> is shown as all 0's if new is a file on the
|
|
filesystem and it is out of sync with the cache. Example:
|
|
|
|
*100644->100644 blob 5be4a4.......->000000....... file.c
|
|
|
|
################################################################
|
|
|
|
Generating patches
|
|
|
|
When git-diff-cache, git-diff-tree, or git-diff-files are run with a -p
|
|
option, they do not produce the output described in "Output format from
|
|
git-diff-cache, git-diff-tree and git-diff-files" section. It instead
|
|
produces a patch file.
|
|
|
|
The patch generation can be customized at two levels. This
|
|
customization also applies to git-diff-tree-helper.
|
|
|
|
1. When the environment variable GIT_EXTERNAL_DIFF is not set,
|
|
these commands internally invoke diff like this:
|
|
|
|
diff -L a/<path> -L a/<path> -pu <old> <new>
|
|
|
|
For added files, /dev/null is used for <old>. For removed
|
|
files, /dev/null is used for <new>
|
|
|
|
The diff formatting options can be customized via the
|
|
environment variable GIT_DIFF_OPTS. For example, if you
|
|
prefer context diff:
|
|
|
|
GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)
|
|
|
|
|
|
2. When the environment variable GIT_EXTERNAL_DIFF is set, the
|
|
program named by it is called, instead of the diff invocation
|
|
described above.
|
|
|
|
For a path that is added, removed, or modified,
|
|
GIT_EXTERNAL_DIFF is called with 7 parameters:
|
|
|
|
path old-file old-hex old-mode new-file new-hex new-mode
|
|
|
|
where
|
|
<old|new>-file are files GIT_EXTERNAL_DIFF can use to read the
|
|
contents of <old|ne>,
|
|
<old|new>-hex are the 40-hexdigit SHA1 hashes,
|
|
<old|new>-mode are the octal representation of the file modes.
|
|
|
|
The file parameters can point at the user's working file (e.g. new-file
|
|
in git-diff-files), /dev/null (e.g. old-file when a new file is added),
|
|
or a temporary file (e.g. old-file in the cache). GIT_EXTERNAL_DIFF
|
|
should not worry about unlinking the temporary file --- it is removed
|
|
when GIT_EXTERNAL_DIFF exits.
|
|
|
|
For a path that is unmerged, GIT_EXTERNAL_DIFF is called with
|
|
1 parameter, path.
|
|
|
|
################################################################
|
|
|
|
Terminology: - see README for description
|
|
Each line contains terms used interchangeably
|
|
|
|
object database, .git directory
|
|
directory cache, index
|
|
id, sha1, sha1-id, sha1 hash
|
|
type, tag
|
|
blob, blob object
|
|
tree, tree object
|
|
commit, commit object
|
|
parent
|
|
root object
|
|
changeset
|
|
|
|
|
|
git Environment Variables
|
|
AUTHOR_NAME
|
|
AUTHOR_EMAIL
|
|
AUTHOR_DATE
|
|
COMMIT_AUTHOR_NAME
|
|
COMMIT_AUTHOR_EMAIL
|
|
GIT_DIFF_OPTS
|
|
GIT_EXTERNAL_DIFF
|
|
GIT_INDEX_FILE
|
|
SHA1_FILE_DIRECTORY
|