aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Greaves <david@dgreaves.com>2005-05-10 22:32:30 +0100
committerJunio C Hamano <junkio@cox.net>2005-05-10 14:55:22 -0700
commit2cf565c53c88c557eedd7e5629437b3c6fe74329 (patch)
treebb04b39cf3fef50bc05825d953486a4d6bada056
parent3be4b61aa4ffb54a42c717772518b2a14b1e352b (diff)
downloadgit-2cf565c53c88c557eedd7e5629437b3c6fe74329.tar.gz
git-2cf565c53c88c557eedd7e5629437b3c6fe74329.tar.xz
[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>
-rw-r--r--Documentation/core-git.txt1660
-rw-r--r--Documentation/diff-format.txt16
-rw-r--r--Documentation/git-apply-patch-script.txt32
-rw-r--r--Documentation/git-cat-file.txt55
-rw-r--r--Documentation/git-check-files.txt48
-rw-r--r--Documentation/git-checkout-cache.txt102
-rw-r--r--Documentation/git-commit-tree.txt81
-rw-r--r--Documentation/git-convert-cache.txt30
-rw-r--r--Documentation/git-diff-cache.txt141
-rw-r--r--Documentation/git-diff-files.txt51
-rw-r--r--Documentation/git-diff-tree-helper.txt47
-rw-r--r--Documentation/git-diff-tree.txt126
-rw-r--r--Documentation/git-export.txt31
-rw-r--r--Documentation/git-fsck-cache.txt122
-rw-r--r--Documentation/git-http-pull.txt39
-rw-r--r--Documentation/git-init-db.txt37
-rw-r--r--Documentation/git-local-pull.txt40
-rw-r--r--Documentation/git-ls-files.txt100
-rw-r--r--Documentation/git-ls-tree.txt46
-rw-r--r--Documentation/git-merge-base.txt34
-rw-r--r--Documentation/git-merge-cache.txt77
-rw-r--r--Documentation/git-merge-one-file-script.txt30
-rw-r--r--Documentation/git-mktag.txt31
-rw-r--r--Documentation/git-prune-script.txt32
-rw-r--r--Documentation/git-pull-script.txt31
-rw-r--r--Documentation/git-read-tree.txt150
-rw-r--r--Documentation/git-resolve-script.txt30
-rw-r--r--Documentation/git-rev-list.txt32
-rw-r--r--Documentation/git-rev-tree.txt88
-rw-r--r--Documentation/git-rpull.txt43
-rw-r--r--Documentation/git-rpush.txt30
-rw-r--r--Documentation/git-tag-script.txt32
-rw-r--r--Documentation/git-tar-tree.txt32
-rw-r--r--Documentation/git-unpack-file.txt37
-rw-r--r--Documentation/git-update-cache.txt108
-rw-r--r--Documentation/git-write-blob.txt33
-rw-r--r--Documentation/git-write-tree.txt52
-rw-r--r--Documentation/git.txt224
-rwxr-xr-xDocumentation/split_docs.pl44
39 files changed, 2262 insertions, 1712 deletions
diff --git a/Documentation/core-git.txt b/Documentation/core-git.txt
deleted file mode 100644
index 4c80c7e9c..000000000
--- 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 3af197cd2..1a99e85ee 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 000000000..a6f860d42
--- /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 000000000..48fb37769
--- /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 000000000..c56f22f92
--- /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 000000000..9d41626d9
--- /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 000000000..5552050ac
--- /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 000000000..66d7fe785
--- /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 000000000..b54b8226a
--- /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 000000000..0ad2f8955
--- /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 000000000..d44858df5
--- /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 000000000..ff7f25f3f
--- /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 000000000..d2d0dc498
--- /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 000000000..bcd3b0adc
--- /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 000000000..59cd090a7
--- /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 000000000..febc8c811
--- /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 000000000..53f5d3968
--- /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 000000000..2face87ae
--- /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 000000000..f6e15ad7f
--- /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 000000000..1e27bf230
--- /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 000000000..343607cf9
--- /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 000000000..387601d7e
--- /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 000000000..320f5a1ef
--- /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 000000000..537b7905b
--- /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 000000000..44fd09a97
--- /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 000000000..df2e36775
--- /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 000000000..8dd84a381
--- /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 000000000..f2c5fa9f4
--- /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 000000000..2ec7ed073
--- /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 000000000..1807fc571
--- /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 000000000..1c1cbab1c
--- /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 000000000..daf350b5b
--- /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 000000000..7870e92ae
--- /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 000000000..2f2130d51
--- /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 000000000..604411d6d
--- /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 000000000..22d75556e
--- /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 000000000..458d97ac9
--- /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 000000000..83d9ca6d9
--- /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 655489315..000000000
--- 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 $_;
-
-}