diff options
| author | David Greaves <david@dgreaves.com> | 2005-05-10 22:32:30 +0100 |
|---|---|---|
| committer | Junio C Hamano <junkio@cox.net> | 2005-05-10 14:55:22 -0700 |
| commit | 2cf565c53c88c557eedd7e5629437b3c6fe74329 (patch) | |
| tree | bb04b39cf3fef50bc05825d953486a4d6bada056 /Documentation | |
| parent | 3be4b61aa4ffb54a42c717772518b2a14b1e352b (diff) | |
| download | git-2cf565c53c88c557eedd7e5629437b3c6fe74329.tar.gz | |
[PATCH 1/4] split core-git.txt and update
Split the core-git.txt file
Formatting fix to the diff-format.txt
Signed-off-by: David Greaves <david@dgreaves.com>
Diffstat (limited to 'Documentation')
39 files changed, 2262 insertions, 1712 deletions
diff --git a/Documentation/core-git.txt b/Documentation/core-git.txt deleted file mode 100644 index 4c80c7e9c7..0000000000 --- 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 - - -//////////////////////////////////////////////////////////////// - diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index 3af197cd2c..1a99e85ee5 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -51,15 +51,15 @@ customization also applies to "git-diff-tree-helper". 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: - 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) + GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD) 2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the diff --git a/Documentation/git-apply-patch-script.txt b/Documentation/git-apply-patch-script.txt new file mode 100644 index 0000000000..a6f860d424 --- /dev/null +++ b/Documentation/git-apply-patch-script.txt @@ -0,0 +1,32 @@ +git-apply-patch-script(1) +========================= +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt new file mode 100644 index 0000000000..48fb37769c --- /dev/null +++ b/Documentation/git-cat-file.txt @@ -0,0 +1,55 @@ +git-cat-file(1) +=============== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-check-files.txt b/Documentation/git-check-files.txt new file mode 100644 index 0000000000..c56f22f92d --- /dev/null +++ b/Documentation/git-check-files.txt @@ -0,0 +1,48 @@ +git-check-files(1) +================== +v0.1, May 2005 + +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] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-checkout-cache.txt b/Documentation/git-checkout-cache.txt new file mode 100644 index 0000000000..9d41626d97 --- /dev/null +++ b/Documentation/git-checkout-cache.txt @@ -0,0 +1,102 @@ +git-checkout-cache(1) +===================== +v0.1, May 2005 + +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` + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt new file mode 100644 index 0000000000..5552050ac1 --- /dev/null +++ b/Documentation/git-commit-tree.txt @@ -0,0 +1,81 @@ +git-commit-tree(1) +================== +v0.1, May 2005 + +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] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-convert-cache.txt b/Documentation/git-convert-cache.txt new file mode 100644 index 0000000000..66d7fe7855 --- /dev/null +++ b/Documentation/git-convert-cache.txt @@ -0,0 +1,30 @@ +git-convert-cache(1) +==================== +v0.1, May 2005 + +NAME +---- +git-convert-cache - Converts old-style GIT repository + + +SYNOPSIS +-------- +'git-convert-cache' + +DESCRIPTION +----------- +Converts old-style GIT repository to the latest format + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-cache.txt b/Documentation/git-diff-cache.txt new file mode 100644 index 0000000000..b54b8226ad --- /dev/null +++ b/Documentation/git-diff-cache.txt @@ -0,0 +1,141 @@ +git-diff-cache(1) +================= +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt new file mode 100644 index 0000000000..0ad2f89550 --- /dev/null +++ b/Documentation/git-diff-files.txt @@ -0,0 +1,51 @@ +git-diff-files(1) +================= +v0.1, May 2005 + +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[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-tree-helper.txt b/Documentation/git-diff-tree-helper.txt new file mode 100644 index 0000000000..d44858df51 --- /dev/null +++ b/Documentation/git-diff-tree-helper.txt @@ -0,0 +1,47 @@ +git-diff-tree-helper(1) +======================= +v0.1, May 2005 + +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] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt new file mode 100644 index 0000000000..ff7f25f3f4 --- /dev/null +++ b/Documentation/git-diff-tree.txt @@ -0,0 +1,126 @@ +git-diff-tree(1) +================ +v0.1, May 2005 + +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[] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-export.txt b/Documentation/git-export.txt new file mode 100644 index 0000000000..d2d0dc498e --- /dev/null +++ b/Documentation/git-export.txt @@ -0,0 +1,31 @@ +git-export(1) +============= +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-fsck-cache.txt b/Documentation/git-fsck-cache.txt new file mode 100644 index 0000000000..bcd3b0adcc --- /dev/null +++ b/Documentation/git-fsck-cache.txt @@ -0,0 +1,122 @@ +git-fsck-cache(1) +================= +v0.1, May 2005 + +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 + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-http-pull.txt b/Documentation/git-http-pull.txt new file mode 100644 index 0000000000..59cd090a78 --- /dev/null +++ b/Documentation/git-http-pull.txt @@ -0,0 +1,39 @@ +git-http-pull(1) +================ +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-init-db.txt b/Documentation/git-init-db.txt new file mode 100644 index 0000000000..febc8c811d --- /dev/null +++ b/Documentation/git-init-db.txt @@ -0,0 +1,37 @@ +git-init-db(1) +============== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-local-pull.txt b/Documentation/git-local-pull.txt new file mode 100644 index 0000000000..53f5d39682 --- /dev/null +++ b/Documentation/git-local-pull.txt @@ -0,0 +1,40 @@ +git-local-pull(1) +================= +v0.1, May 2005 + +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. + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt new file mode 100644 index 0000000000..2face87ae5 --- /dev/null +++ b/Documentation/git-ls-files.txt @@ -0,0 +1,100 @@ +git-ls-files(1) +=============== +v0.1, May 2005 + +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] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt new file mode 100644 index 0000000000..f6e15ad7fa --- /dev/null +++ b/Documentation/git-ls-tree.txt @@ -0,0 +1,46 @@ +git-ls-tree(1) +============== +v0.1, May 2005 + +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> + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt new file mode 100644 index 0000000000..1e27bf2301 --- /dev/null +++ b/Documentation/git-merge-base.txt @@ -0,0 +1,34 @@ +git-merge-base(1) +================= +v0.1, May 2005 + +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... + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-merge-cache.txt b/Documentation/git-merge-cache.txt new file mode 100644 index 0000000000..343607cf9a --- /dev/null +++ b/Documentation/git-merge-cache.txt @@ -0,0 +1,77 @@ +git-merge-cache(1) +================== +v0.1, May 2005 + +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). + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-merge-one-file-script.txt b/Documentation/git-merge-one-file-script.txt new file mode 100644 index 0000000000..387601d7e4 --- /dev/null +++ b/Documentation/git-merge-one-file-script.txt @@ -0,0 +1,30 @@ +git-merge-one-file-script(1) +============================ +v0.1, May 2005 + +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". + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt new file mode 100644 index 0000000000..320f5a1efb --- /dev/null +++ b/Documentation/git-mktag.txt @@ -0,0 +1,31 @@ +git-mktag(1) +============ +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-prune-script.txt b/Documentation/git-prune-script.txt new file mode 100644 index 0000000000..537b7905b6 --- /dev/null +++ b/Documentation/git-prune-script.txt @@ -0,0 +1,32 @@ +git-prune-script(1) +=================== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-pull-script.txt b/Documentation/git-pull-script.txt new file mode 100644 index 0000000000..44fd09a97a --- /dev/null +++ b/Documentation/git-pull-script.txt @@ -0,0 +1,31 @@ +git-pull-script(1) +================== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt new file mode 100644 index 0000000000..df2e36775c --- /dev/null +++ b/Documentation/git-read-tree.txt @@ -0,0 +1,150 @@ +git-read-tree(1) +================ +v0.1, May 2005 + +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] + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-resolve-script.txt b/Documentation/git-resolve-script.txt new file mode 100644 index 0000000000..8dd84a381a --- /dev/null +++ b/Documentation/git-resolve-script.txt @@ -0,0 +1,30 @@ +git-resolve-script(1) +===================== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt new file mode 100644 index 0000000000..f2c5fa9f4c --- /dev/null +++ b/Documentation/git-rev-list.txt @@ -0,0 +1,32 @@ +git-rev-list(1) +=============== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-rev-tree.txt b/Documentation/git-rev-tree.txt new file mode 100644 index 0000000000..2ec7ed073b --- /dev/null +++ b/Documentation/git-rev-tree.txt @@ -0,0 +1,88 @@ +git-rev-tree(1) +=============== +v0.1, May 2005 + +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.) + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-rpull.txt b/Documentation/git-rpull.txt new file mode 100644 index 0000000000..1807fc571a --- /dev/null +++ b/Documentation/git-rpull.txt @@ -0,0 +1,43 @@ +git-rpull(1) +============ +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-rpush.txt b/Documentation/git-rpush.txt new file mode 100644 index 0000000000..1c1cbab1cf --- /dev/null +++ b/Documentation/git-rpush.txt @@ -0,0 +1,30 @@ +git-rpush(1) +============ +v0.1, May 2005 + +NAME +---- +git-rpush - Helper "server-side" program used by git-rpull + + +SYNOPSIS +-------- +'git-rpush' + +DESCRIPTION +----------- +Helper "server-side" program used by git-rpull. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-tag-script.txt b/Documentation/git-tag-script.txt new file mode 100644 index 0000000000..daf350b5bf --- /dev/null +++ b/Documentation/git-tag-script.txt @@ -0,0 +1,32 @@ +git-tag-script(1) +================= +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-tar-tree.txt b/Documentation/git-tar-tree.txt new file mode 100644 index 0000000000..7870e92ae9 --- /dev/null +++ b/Documentation/git-tar-tree.txt @@ -0,0 +1,32 @@ +git-tar-tree(1) +=============== +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-unpack-file.txt b/Documentation/git-unpack-file.txt new file mode 100644 index 0000000000..2f2130d511 --- /dev/null +++ b/Documentation/git-unpack-file.txt @@ -0,0 +1,37 @@ +git-unpack-file(1) +================== +v0.1, May 2005 + +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 + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-update-cache.txt b/Documentation/git-update-cache.txt new file mode 100644 index 0000000000..604411d6d7 --- /dev/null +++ b/Documentation/git-update-cache.txt @@ -0,0 +1,108 @@ +git-update-cache(1) +=================== +v0.1, May 2005 + +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 + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-write-blob.txt b/Documentation/git-write-blob.txt new file mode 100644 index 0000000000..22d75556e2 --- /dev/null +++ b/Documentation/git-write-blob.txt @@ -0,0 +1,33 @@ +git-write-blob(1) +================= +v0.1, May 2005 + +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. + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git-write-tree.txt b/Documentation/git-write-tree.txt new file mode 100644 index 0000000000..458d97ac98 --- /dev/null +++ b/Documentation/git-write-tree.txt @@ -0,0 +1,52 @@ +git-write-tree(1) +================= +v0.1, May 2005 + +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 + + +//////////////////////////////////////////////////////////////// +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/git.txt b/Documentation/git.txt new file mode 100644 index 0000000000..83d9ca6d9a --- /dev/null +++ b/Documentation/git.txt @@ -0,0 +1,224 @@ +git(1) +====== +v0.1, May 2005 + +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' + + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> + +Documentation +-------------- +Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. + +GIT +--- +Part of the link:git.html[git] suite + diff --git a/Documentation/split_docs.pl b/Documentation/split_docs.pl deleted file mode 100755 index 655489315f..0000000000 --- a/Documentation/split_docs.pl +++ /dev/null @@ -1,44 +0,0 @@ -#!/usr/bin/perl -w -use strict; - -my $cmd; -my $name; - -my $author; - -while (<STDIN>) { - if (/^NAME$/ || eof(STDIN)) { - if ($cmd) { - print PAGE $author if defined($author); - print PAGE "Documentation\n--------------\nDocumentation by David Greaves, Junio C Hamano and the git-list <git\@vger.kernel.org>.\n\n"; - print PAGE "GIT\n---\nPart of the link:git.html[git] suite\n\n"; - - if ($#ARGV || $ARGV[0] eq "-html") { - system(qw(asciidoc -b css-embedded -d manpage), "$cmd.txt"); - } elsif ($ARGV[0] eq "-man") { - system(qw(asciidoc -b docbook -d manpage), "$cmd.txt"); - system(qw(xmlto man), "$cmd.xml") if -e "$cmd.xml"; - } - } - exit if eof(STDIN); - $_=<STDIN>;$_=<STDIN>; # discard underline and get command - chomp; - $name = $_; - ($cmd) = split(' ',$_); - print "$name\n"; - open(PAGE, "> $cmd.txt") or die; - print PAGE "$cmd(1)\n==="."="x length($cmd); - print PAGE "\nv0.1, May 2005\n\nNAME\n----\n$name\n\n"; - - - $author = "Author\n------\nWritten by Linus Torvalds <torvalds\@osdl.org>\n\n"; - - next; - } - next unless $cmd; - - $author=undef if /^AUTHOR$/i; # don't use default for commands with an author - - print PAGE $_; - -} |