Add git-update-cache --replace option.
[git.git] / Documentation / core-git.txt
index d979a66..5e702fd 100644 (file)
@@ -41,6 +41,14 @@ Identifier terminology used:
 
 
 ################################################################
+git-apply-patch-script
+
+This is a sample script to be used as GIT_EXTERNAL_DIFF to apply
+differences git-diff-* family of commands reports to the current
+work tree.
+
+
+################################################################
 git-cat-file
        git-cat-file (-t | <type>) <object>
 
@@ -226,8 +234,14 @@ see also: git-write-tree
 
 
 ################################################################
+git-convert-cache
+
+Converts old-style GIT repository to the latest.
+
+
+################################################################
 git-diff-cache
-       git-diff-cache [-p] [-r] [-z] [--cached] <tree-ish>
+       git-diff-cache [-p] [-r] [-z] [-m] [--cached] <tree-ish>
 
 Compares the content and mode of the blobs found via a tree object
 with the content of the current cache and, optionally ignoring the
@@ -250,6 +264,13 @@ stat state of the file on disk.
 --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:
 
 See "Output format from git-diff-cache, git-diff-tree and git-diff-files"
@@ -335,9 +356,10 @@ which file is in which state, since the "has been updated" ones show a
 valid sha1, and the "not in sync with the index" ones will always have the
 special all-zero sha1.
 
+
 ################################################################
 git-diff-tree
-       git-diff-tree [-p] [-r] [-z] <tree-ish> <tree-ish> [<pattern>]*
+       git-diff-tree [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]*
 
 Compares the content and mode of the blobs found via two tree objects.
 
@@ -363,6 +385,34 @@ Note that git-diff-tree can use the tree encapsulated in a commit object.
 -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
@@ -409,6 +459,7 @@ this one:
 
 in case you care).
 
+
 ################################################################
 git-diff-tree-helper
        git-diff-tree-helper [-z] [-R]
@@ -431,6 +482,7 @@ generates patch format output.
 
 See also the section on generating patches.
 
+
 ################################################################
 git-fsck-cache
        git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*]
@@ -525,6 +577,7 @@ SHA1_FILE_DIRECTORY
 GIT_INDEX_FILE
        used to specify the cache
 
+
 ################################################################
 git-export
        git-export top [base]
@@ -548,6 +601,39 @@ git-init-db won't hurt an existing repository.
 
 
 ################################################################
+git-http-pull
+
+       git-http-pull [-c] [-t] [-a] [-v] commit-id url
+
+Downloads a remote GIT repository via HTTP protocol.
+
+-c
+       Get the commit objects.
+-t
+       Get trees associated with the commit objects.
+-a
+       Get all the objects.
+-v
+       Report what is downloaded.
+
+
+################################################################
+git-local-pull
+
+       git-local-pull [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path
+
+Downloads another GIT repository on a local system.
+
+-c
+       Get the commit objects.
+-t
+       Get trees associated with the commit objects.
+-a
+       Get all the objects.
+-v
+       Report what is downloaded.
+
+################################################################
 git-ls-tree
        git-ls-tree [-r] [-z] <tree-ish>
 
@@ -630,6 +716,33 @@ merge once anything has returned an error (ie "cat" returned an error
 for the AA file, because it didn't exist in the original, and thus
 "git-merge-cache" didn't even try to merge the MM thing).
 
+################################################################
+git-merge-one-file-script
+
+This is the standard helper program to use with git-merge-cache
+to resolve a merge after the trivial merge done with git-read-tree -m.
+
+################################################################
+git-mktag
+
+Reads a tag contents from its standard input and creates a tag object.
+The input must be a well formed tag object.
+
+
+################################################################
+git-prune-script
+
+This runs git-fsck-cache --unreachable program using the heads specified
+on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is
+specified), and prunes all unreachable objects from the object database.
+
+
+################################################################
+git-pull-script
+
+This script is used by Linus to pull from a remote repository and perform
+a merge.
+
 
 ################################################################
 git-read-tree
@@ -754,6 +867,12 @@ git-ls-files
 
 
 ################################################################
+git-resolve-script
+
+This script is used by Linus to merge two trees.
+
+
+################################################################
 git-rev-list <commit>
 
 Lists commit objects in reverse chronological order starting at the
@@ -823,6 +942,30 @@ think.)
 
 
 ################################################################
+git-rpull
+
+       git-rpull [-c] [-t] [-a] [-v] commit-id url
+
+Pulls from a remote repository over ssh connection, invoking git-rpush on
+the other end.
+
+-c
+       Get the commit objects.
+-t
+       Get trees associated with the commit objects.
+-a
+       Get all the objects.
+-v
+       Report what is downloaded.
+
+
+################################################################
+git-rpush
+
+Helper "server-side" program used by git-rpull.
+
+
+################################################################
 git-diff-files
        git-diff-files [-p] [-q] [-r] [-z] [<pattern>...]
 
@@ -850,6 +993,23 @@ section.
 
 
 ################################################################
+git-tag-script
+
+This is an example script that uses git-mktag to create a tag object
+signed with GPG.
+
+
+################################################################
+git-tar-tree
+
+       git-tar-tree <tree-ish> [ <base> ]
+
+Creates a tar archive containing the tree structure for the named tree.
+When <base> is specified it is added as a leading path as the files in the
+generated tar archive.
+
+
+################################################################
 git-ls-files
        git-ls-files [-z] [-t]
                (--[cached|deleted|others|ignored|stage|unmerged])*
@@ -897,6 +1057,14 @@ shown:
        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:
@@ -930,7 +1098,7 @@ returns the name of the temporary file in the following format:
 ################################################################
 git-update-cache
        git-update-cache
-            [--add] [--remove] [--refresh]
+            [--add] [--remove] [--refresh] [--replace]
             [--ignore-missing]
             [--force-remove <file>]
             [--cacheinfo <mode> <object> <file>]*
@@ -967,6 +1135,14 @@ using the various options:
        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.
 
@@ -1001,6 +1177,17 @@ To update and refresh only the files already checked out:
 
 
 ################################################################
+git-write-blob
+
+       git-write-blob <any-file-on-the-filesystem>
+
+Writes the contents of the named file (which can be outside of the work
+tree) as a blob into the object database, and reports its object ID to its
+standard output.  This is used by git-merge-one-file-script to update the
+cache without modifying files in the work tree.
+
+
+################################################################
 git-write-tree
        git-write-tree