diff options
Diffstat (limited to 'Documentation/core-git.txt')
| -rw-r--r-- | Documentation/core-git.txt | 1660 |
1 files changed, 0 insertions, 1660 deletions
diff --git a/Documentation/core-git.txt b/Documentation/core-git.txt deleted file mode 100644 index 4c80c7e..0000000 --- a/Documentation/core-git.txt +++ /dev/null @@ -1,1660 +0,0 @@ -GIT(1) -====== -v0.1, May 2005 - -//////////////////////// -Please note that this document is in asciidoc format. - http://www.methods.co.nz/asciidoc/index.html - -You should be able to read it but be aware that there is some minor -typographical bludgeoning to allow the production of clean man and -html output. - -(eg in some synopsis lines the '*' character is preceded by a '\' and -there are one or two '+' characters) - -//////////////////////// - -NAME ----- -git - the stupid content tracker - -SYNOPSIS --------- -'git-<command>' <args> - -DESCRIPTION ------------ - -This is reference information for the core git commands. - -The link: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> -08/05/05 - -Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to -reflect recent changes. - -Commands Overview ------------------ -The git commands can helpfully be split into those that manipulate -the repository, the cache and the working fileset and those that -interrogate and compare them. - -Manipulation commands -~~~~~~~~~~~~~~~~~~~~~ -link:git-apply-patch-script.html[git-apply-patch-script]:: - Sample script to apply the diffs from git-diff-* - -link:git-checkout-cache.html[git-checkout-cache]:: - Copy files from the cache to the working directory - -link:git-commit-tree.html[git-commit-tree]:: - Creates a new commit object - -link:git-convert-cache.html[git-convert-cache]:: - Converts old-style GIT repository - -link:git-http-pull.html[git-http-pull]:: - Downloads a remote GIT repository via HTTP - -link:git-init-db.html[git-init-db]:: - Creates an empty git object database - -link:git-local-pull.html[git-local-pull]:: - Duplicates another GIT repository on a local system - -link:git-merge-base.html[git-merge-base]:: - Finds as good a common ancestor as possible for a merge - -link:git-merge-one-file-script.html[git-merge-one-file-script]:: - The standard helper program to use with "git-merge-cache" - -link:git-mktag.html[git-mktag]:: - Creates a tag object - -link:git-prune-script.html[git-prune-script]:: - Prunes all unreachable objects from the object database - -link:git-pull-script.html[git-pull-script]:: - Script used by Linus to pull and merge a remote repository - -link:git-read-tree.html[git-read-tree]:: - Reads tree information into the directory cache - -link:git-resolve-script.html[git-resolve-script]:: - Script used to merge two trees - -link:git-rpull.html[git-rpull]:: - Pulls from a remote repository over ssh connection - -link:git-tag-script.html[git-tag-script]:: - An example script to create a tag object signed with GPG - -link:git-update-cache.html[git-update-cache]:: - Modifies the index or directory cache - -link:git-write-blob.html[git-write-blob]:: - Creates a blob from a file - -link:git-write-tree.html[git-write-tree]:: - Creates a tree from the current cache - -Interrogation commands -~~~~~~~~~~~~~~~~~~~~~~ -link:git-cat-file.html[git-cat-file]:: - Provide content or type information for repository objects - -link:git-check-files.html[git-check-files]:: - Verify a list of files are up-to-date - -link:git-diff-cache.html[git-diff-cache]:: - Compares content and mode of blobs between the cache and repository - -link:git-diff-files.html[git-diff-files]:: - Compares files in the working tree and the cache - -link:git-diff-tree.html[git-diff-tree]:: - Compares the content and mode of blobs found via two tree objects - -link:git-diff-tree-helper.html[git-diff-tree-helper]:: - Generates patch format output for git-diff-* - -link:git-export.html[git-export]:: - Exports each commit and a diff against each of its parents - -link:git-fsck-cache.html[git-fsck-cache]:: - Verifies the connectivity and validity of the objects in the database - -link:git-ls-files.html[git-ls-files]:: - Information about files in the cache/working directory - -link:git-ls-tree.html[git-ls-tree]:: - Displays a tree object in human readable form - -link:git-merge-cache.html[git-merge-cache]:: - Runs a merge for files needing merging - -link:git-rev-list.html[git-rev-list]:: - Lists commit objects in reverse chronological order - -link:git-rev-tree.html[git-rev-tree]:: - Provides the revision tree for one or more commits - -link:git-rpush.html[git-rpush]:: - Helper "server-side" program used by git-rpull - -link:git-tar-tree.html[git-tar-tree]:: - Creates a tar archive of the files in the named tree - -link:git-unpack-file.html[git-unpack-file]:: - Creates a temporary file with a blob's contents - -The interrogate commands may create files - and you can force them to -touch the working file set - but in general they don't - - -Terminology ------------ -see README for description - -Identifier terminology ----------------------- -<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. - -Terminology ------------ -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 - - -Environment Variables ---------------------- -Various git commands use the following environment variables: - -- 'GIT_AUTHOR_NAME' -- 'GIT_AUTHOR_EMAIL' -- 'GIT_AUTHOR_DATE' -- 'GIT_COMMITTER_NAME' -- 'GIT_COMMITTER_EMAIL' -- 'GIT_DIFF_OPTS' -- 'GIT_EXTERNAL_DIFF' -- 'GIT_INDEX_FILE' -- 'GIT_OBJECT_DIRECTORY' -- 'GIT_ALTERNATE_OBJECT_DIRECTORIES' - - -NAME ----- -git-apply-patch-script - Sample script to apply the diffs from git-diff-* - -SYNOPSIS --------- -'git-apply-patch-script' - -DESCRIPTION ------------ -This is a sample script to be used via the 'GIT_EXTERNAL_DIFF' -environment variable to apply the differences that the "git-diff-*" -family of commands report to the current work tree. - - -NAME ----- -git-cat-file - Provide content or type information for repository objects - -SYNOPSIS --------- -'git-cat-file' (-t | <type>) <object> - -DESCRIPTION ------------ -Provides content or type of objects in the repository. The type -is required if '-t' is not being used to find the object type. - -OPTIONS -------- -<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 a type that can trivially dereferenced from the given - <object> is also permitted. An example is to ask for a - "tree" with <object> being a commit object that contains it, - or to ask for a "blob" with <object> being 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. - - -NAME ----- -git-check-files - Verify a list of files are up-to-date - - -SYNOPSIS --------- -'git-check-files' <file>... - -DESCRIPTION ------------ -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: link:git-update-cache.html[git-update-cache] - - -NAME ----- -git-checkout-cache - Copy files from the cache to the working directory - -SYNOPSIS --------- -'git-checkout-cache' [-q] [-a] [-f] [-n] [--prefix=<string>] - [--] <file>... - -DESCRIPTION ------------ -Will copy all files listed from the cache to the working directory -(not overwriting existing files). - -OPTIONS -------- --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 an "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 "export" the cache into the specified -directory. - -NOTE The final "/" is important. The 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` - -NAME ----- -git-commit-tree - Creates a new commit object - -SYNOPSIS --------- -'git-commit-tree' <tree> [-p <parent commit>]\ < changelog - -DESCRIPTION ------------ -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. - - GIT_AUTHOR_NAME - GIT_AUTHOR_EMAIL - GIT_AUTHOR_DATE - GIT_COMMITTER_NAME - GIT_COMMITTER_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: link:git-write-tree.html[git-write-tree] - - -NAME ----- -git-convert-cache - Converts old-style GIT repository - -SYNOPSIS --------- -'git-convert-cache' - -DESCRIPTION ------------ -Converts old-style GIT repository to the latest format - - -NAME ----- -git-diff-cache - Compares content and mode of blobs between the cache and repository - -SYNOPSIS --------- -'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish> - -DESCRIPTION ------------ -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. - -OPTIONS -------- -<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 - --m:: - By default, files recorded in the index but not checked - out are reported as deleted. This flag makes - "git-diff-cache" say that all non-checked-out files are up - to date. - -Output format -------------- -include::diff-format.txt[] - -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 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 a "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 -"git-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. - - -NAME ----- -git-diff-files - Compares files in the working tree and the cache - -SYNOPSIS --------- -'git-diff-files' [-p] [-q] [-r] [-z] [<pattern>...] - -DESCRIPTION ------------ -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". - -OPTIONS -------- --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 -------------- -include::diff-format.txt[] - - -NAME ----- -git-diff-tree - Compares the content and mode of blobs found via two tree objects - -SYNOPSIS --------- -'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]\* - -DESCRIPTION ------------ -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. - -OPTIONS -------- -<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. - -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). - -Output format -------------- -include::diff-format.txt[] - - -NAME ----- -git-diff-tree-helper - Generates patch format output for git-diff-* - -SYNOPSIS --------- -'git-diff-tree-helper' [-z] [-R] - -DESCRIPTION ------------ -Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and -generates patch format output. - -OPTIONS -------- --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 in link:git-diff-cache.html[git-diff-cache] - - -NAME ----- -git-export - Exports each commit and a diff against each of its parents - -SYNOPSIS --------- -'git-export' top [base] - -DESCRIPTION ------------ -Exports each commit and diff against each of its parents, between -top and base. If base is not specified it exports everything. - - -NAME ----- -git-fsck-cache - Verifies the connectivity and validity of the objects in the database - -SYNOPSIS --------- -'git-fsck-cache' [--tags] [--root] [[--unreachable] [--cache] <object>\*] - -DESCRIPTION ------------ -Verifies the connectivity and validity of the objects in the database. - -OPTIONS -------- -<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 node 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 ---------------------- - -GIT_OBJECT_DIRECTORY:: - used to specify the object database root (usually .git/objects) - -GIT_INDEX_FILE:: - used to specify the cache - - -NAME ----- -git-http-pull - Downloads a remote GIT repository via HTTP - -SYNOPSIS --------- -'git-http-pull' [-c] [-t] [-a] [-v] commit-id url - -DESCRIPTION ------------ -Downloads a remote GIT repository via HTTP. - --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. - - -NAME ----- -git-init-db - Creates an empty git object database - -SYNOPSIS --------- -'git-init-db' - -DESCRIPTION ------------ -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 'GIT_OBJECT_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. - - -NAME ----- -git-local-pull - Duplicates another GIT repository on a local system - -SYNOPSIS --------- -'git-local-pull' [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path - -DESCRIPTION ------------ -Duplicates another GIT repository on a local system. - -OPTIONS -------- --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. - -NAME ----- -git-ls-files - Information about files in the cache/working directory - -SYNOPSIS --------- -'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>] - -DESCRIPTION ------------ -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: - -OPTIONS -------- --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: link:read-cache.html[read-cache] - - -NAME ----- -git-ls-tree - Displays a tree object in human readable form - -SYNOPSIS --------- -'git-ls-tree' [-r] [-z] <tree-ish> - -DESCRIPTION ------------ -Converts the tree object to a human readable (and script processable) -form. - -OPTIONS -------- -<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> - - -NAME ----- -git-merge-base - Finds as good a common ancestor as possible for a merge - -SYNOPSIS --------- -'git-merge-base' <commit> <commit> - -DESCRIPTION ------------ -"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... - - -NAME ----- -git-merge-cache - Runs a merge for files needing merging - -SYNOPSIS --------- -'git-merge-cache' <merge-program> (-a | -- | <file>\*) - -DESCRIPTION ------------ -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. - -OPTIONS -------- ---:: - 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). - -NAME ----- -git-merge-one-file-script - The standard helper program to use with "git-merge-cache" - -SYNOPSIS --------- -'git-merge-one-file-script' - -DESCRIPTION ------------ -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". - -NAME ----- -git-mktag - Creates a tag object - -SYNOPSIS --------- -'git-mktag' - -DESCRIPTION ------------ -Reads a tag contents from its standard input and creates a tag object. -The input must be a well formed tag object. - - -NAME ----- -git-prune-script - Prunes all unreachable objects from the object database - -SYNOPSIS --------- -'git-prune-script' - -DESCRIPTION ------------ -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. - - -NAME ----- -git-pull-script - Script used by Linus to pull and merge a remote repository - -SYNOPSIS --------- -'git-pull-script' - -DESCRIPTION ------------ -This script is used by Linus to pull from a remote repository and perform -a merge. - - -NAME ----- -git-read-tree - Reads tree information into the directory cache - -SYNOPSIS --------- -'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])" - -DESCRIPTION ------------ -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. - -OPTIONS -------- --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: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files] - - -NAME ----- -git-resolve-script - Script used to merge two trees - -SYNOPSIS --------- -'git-resolve-script' - -DESCRIPTION ------------ -This script is used by Linus to merge two trees. - - -NAME ----- -git-rev-list - Lists commit objects in reverse chronological order - -SYNOPSIS --------- -'git-rev-list' <commit> - -DESCRIPTION ------------ -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. - - -NAME ----- -git-rev-tree - Provides the revision tree for one or more commits - -SYNOPSIS --------- -'git-rev-tree' [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>] - -DESCRIPTION ------------ -Provides the revision tree for one or more commits. - -OPTIONS -------- ---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.) - - -NAME ----- -git-rpull - Pulls from a remote repository over ssh connection - - -SYNOPSIS --------- -'git-rpull' [-c] [-t] [-a] [-v] commit-id url - -DESCRIPTION ------------ -Pulls from a remote repository over ssh connection, invoking git-rpush on -the other end. - -OPTIONS -------- --c:: - Get the commit objects. --t:: - Get trees associated with the commit objects. --a:: - Get all the objects. --v:: - Report what is downloaded. - - -NAME ----- -git-rpush - Helper "server-side" program used by git-rpull - -SYNOPSIS --------- -'git-rpush' - -DESCRIPTION ------------ -Helper "server-side" program used by git-rpull. - - -NAME ----- -git-tag-script - An example script to create a tag object signed with GPG - - -SYNOPSIS --------- -'git-tag-script' - -DESCRIPTION ------------ -This is an example script that uses "git-mktag" to create a tag object -signed with GPG. - - -NAME ----- -git-tar-tree - Creates a tar archive of the files in the named tree - -SYNOPSIS --------- -'git-tar-tree' <tree-ish> [ <base> ] - -DESCRIPTION ------------ -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. - - -NAME ----- -git-unpack-file - Creates a temporary file with a blob's contents - - -SYNOPSIS --------- -'git-unpack-file' <blob> - -DESCRIPTION ------------ -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 - -OPTIONS -------- -<blob>:: - Must be a blob id - -NAME ----- -git-update-cache - Modifies the index or directory cache - -SYNOPSIS --------- -'git-update-cache' - [--add] [--remove] [--refresh] [--replace] - [--ignore-missing] - [--force-remove <file>] - [--cacheinfo <mode> <object> <file>]\* - [--] [<file>]\* - -DESCRIPTION ------------ -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: - -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. - ---replace:: - By default, when a file `path` exists in the index, - git-update-cache refuses an attempt to add `path/file`. - Similarly if a file `path/file` exists, a file `path` - cannot be added. With --replace flag, existing entries - that conflicts with the entry being added are - automatically removed with warning messages. - ---:: - 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 - - -NAME ----- -git-write-blob - Creates a blob from a file - -SYNOPSIS --------- -'git-write-blob' <any-file-on-the-filesystem> - -DESCRIPTION ------------ -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. - - -NAME ----- -git-write-tree - Creates a tree from the current cache - -SYNOPSIS --------- -'git-write-tree' - -DESCRIPTION ------------ -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". - - - - -//////////////////////////////////////////////////////////////// - -Producing man pages and html - -To create a set of html pages run: - perl split-docs.pl -html < core-git.txt - -To create a set of man pages run: - perl split-docs.pl -man < core-git.txt - - -//////////////////////////////////////////////////////////////// - |