path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
11 files changed, 205 insertions, 35 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9ccb8f7..318b04f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -4,8 +4,8 @@ it for the core GIT to make sure people understand what they are
doing when they write "Signed-off-by" line.
But the patch submission requirements are a lot more relaxed
-here, because the core GIT is thousand times smaller ;-). So
-here is only the relevant bits.
+here on the technical/contents front, because the core GIT is
+thousand times smaller ;-). So here is only the relevant bits.
(1) Make separate commits for logically separate changes.
@@ -18,13 +18,19 @@ repository. It is a good discipline.
Describe the technical detail of the change(s).
-If your description starts to get long, that's a sign that you
+If your description starts to get too long, that's a sign that you
probably need to split up your commit to finer grained pieces.
+Oh, another thing. I am picky about whitespaces. Make sure your
+changes do not trigger errors with the sample pre-commit hook shipped
+in templates/hooks--pre-commit.
-(2) Generate your patch using git/cogito out of your commits.
-git diff tools generate unidiff which is the preferred format.
+(2) Generate your patch using git tools out of your commits.
+git based diff tools (git, Cogito, and StGIT included) generate
+unidiff which is the preferred format.
You do not have to be afraid to use -M option to "git diff" or
"git format-patch", if your patch involves file renames. The
receiving end can handle them just fine.
@@ -33,20 +39,22 @@ Please make sure your patch does not include any extra files
which do not belong in a patch submission. Make sure to review
your patch after generating it, to ensure accuracy. Before
sending out, please make sure it cleanly applies to the "master"
-branch head.
+branch head. If you are preparing a work based on "next" branch,
+that is fine, but please mark it as such.
(3) Sending your patches.
-People on the git mailing list needs to be able to read and
+People on the git mailing list need to be able to read and
comment on the changes you are submitting. It is important for
a developer to be able to "quote" your changes, using standard
e-mail tools, so that they may comment on specific portions of
-your code. For this reason, all patches should be submitting
-e-mail "inline". WARNING: Be wary of your MUAs word-wrap
-corrupting your patch. Do not cut-n-paste your patch.
+your code. For this reason, all patches should be submited
+"inline". WARNING: Be wary of your MUAs word-wrap
+corrupting your patch. Do not cut-n-paste your patch; you can
+lose tabs that way if you are not careful.
-It is common convention to prefix your subject line with
+It is a common convention to prefix your subject line with
[PATCH]. This lets people easily distinguish patches from other
e-mail discussions.
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 5b1b4d3..214ed23 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -85,27 +85,12 @@ OPTIONS
Files to be committed. The meaning of these is
different between `--include` and `--only`. Without
- either, it defaults `--include` semantics.
+ either, it defaults `--only` semantics.
If you make a commit and then found a mistake immediately after
that, you can recover from it with gitlink:git-reset[1].
-The 1.2.0 and its maintenance series 1.2.X will keep the
-traditional `--include` semantics as the default when neither
-`--only` nor `--include` is specified and `paths...` are given.
-This *will* change during the development towards 1.3.0 in the
-'master' branch of `git.git` repository. If you are using this
-command in your scripts, and you depend on the traditional
-`--include` semantics, please update them to explicitly ask for
-`--include` semantics. Also if you are used to making partial
-commit using `--include` semantics, please train your fingers to
-say `git commit --include paths...` (or `git commit -i paths...`).
@@ -121,7 +106,7 @@ even the command is invoked from a subdirectory.
That is, update the specified paths to the index and then commit
the whole tree.
-`git commit --only paths...` largely bypasses the index file and
+`git commit paths...` largely bypasses the index file and
commits only the changes made to the specified paths. It has
however several safety valves to prevent confusion.
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index fe53412..e813f84 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -8,12 +8,14 @@ git-ls-files - Information about files in the index/working directory
-'git-ls-files' [-z] [-t]
+'git-ls-files' [-z] [-t] [-v]
[-x <pattern>|--exclude=<pattern>]
[-X <file>|--exclude-from=<file>]
+ [--error-unmatch]
[--full-name] [--] [<file>]\*
@@ -72,6 +74,10 @@ OPTIONS
read additional exclude patterns that apply only to the
directory and its subdirectories in <file>.
+ If any <file> does not appear in the index, treat this as an
+ error (return 1).
Identify the file status with the following tags (followed by
a space) at the start of each line:
@@ -82,6 +88,10 @@ OPTIONS
K:: to be killed
?:: other
+ Similar to `-t`, but use lowercase letters for files
+ that are marked as 'always matching index'.
When run from a subdirectory, the command usually
outputs paths relative to the current directory. This
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 2d67d39..4cb2e83 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -8,7 +8,10 @@ git-pack-objects - Create a packed archive of objects.
-'git-pack-objects' [--non-empty] [--local] [--incremental] [--window=N] [--depth=N] {--stdout | base-name} < object-list
+'git-pack-objects' [-q] [--no-reuse-delta] [--non-empty]
+ [--local] [--incremental] [--window=N] [--depth=N]
+ {--stdout | base-name} < object-list
@@ -32,6 +35,10 @@ Placing both in the pack/ subdirectory of $GIT_OBJECT_DIRECTORY (or
any of the directories on $GIT_ALTERNATE_OBJECT_DIRECTORIES)
enables git to read from such an archive.
+In a packed archive, an object is either stored as a compressed
+whole, or as a difference from some other object. The latter is
+often called a delta.
@@ -74,6 +81,18 @@ base-name::
Only create a packed archive if it would contain at
least one object.
+ This flag makes the command not to report its progress
+ on the standard error stream.
+ When creating a packed archive in a repository that
+ has existing packs, the command reuses existing deltas.
+ This sometimes results in a slightly suboptimal pack.
+ This flag tells the command not to reuse existing deltas
+ but compute them from scratch.
Written by Linus Torvalds <>
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 16c158f..f037d12 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -7,14 +7,54 @@ git-rebase - Rebase local commits to new upstream head.
-'git-rebase' <upstream> [<head>]
+'git-rebase' [--onto <newbase>] <upstream> [<branch>]
-Rebases local commits to the new head of the upstream tree.
+git-rebase applies to <upstream> (or optionally to <newbase>) commits
+from <branch> that do not appear in <upstream>. When <branch> is not
+specified it defaults to the current branch (HEAD).
+When git-rebase is complete, <branch> will be updated to point to the
+newly created line of commit objects, so the previous line will not be
+accessible unless there are other references to it already.
+Assume the following history exists and the current branch is "topic":
+ A---B---C topic
+ /
+ D---E---F---G master
+From this point, the result of the following commands:
+ git-rebase master
+ git-rebase master topic
+would be:
+ A'--B'--C' topic
+ /
+ D---E---F---G master
+While, starting from the same point, the result of the following
+ git-rebase --onto master~1 master
+ git-rebase --onto master~1 master topic
+would be:
+ A'--B'--C' topic
+ /
+ D---E---F---G master
+ Starting point at which to create the new commits. If the
+ --onto option is not specified, the starting point is
+ <upstream>.
Upstream branch to compare against.
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 9060fe8..6c0f792 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -9,7 +9,7 @@ objects into pack files.
-'git-repack' [-a] [-d] [-l] [-n]
+'git-repack' [-a] [-d] [-f] [-l] [-n] [-q]
@@ -43,6 +43,14 @@ OPTIONS
Pass the `--local` option to `git pack-objects`, see
+ Pass the `--no-reuse-delta` option to `git pack-objects`, see
+ gitlink:git-pack-objects[1].
+ Pass the `-q` option to `git pack-objects`, see
+ gitlink:git-pack-objects[1].
Do not update the server information with
`git update-server-info`.
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 1662e06..29b5789 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -80,7 +80,7 @@ OPTIONS
Show `$GIT_DIR` if defined else show the path to the .git directory.
---short, short=number::
+--short, --short=number::
Instead of outputting the full SHA1 values of object names try to
abbriviate them to a shorter unique name. When no length is specified
7 is used. The minimum length is 4.
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 00537d8..8c58685 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -24,6 +24,9 @@ OPTIONS
The options available are:
+ Specify a starting "Cc:" value for each email.
--chain-reply-to, --no-chain-reply-to::
If this is set, each email will be sent as a reply to the previous
email sent. If disabled with "--no-chain-reply-to", all emails after
@@ -48,6 +51,9 @@ The options available are:
Only necessary if --compose is also set. If --compose
is not set, this will be prompted for.
+ Do not add emails foudn in Signed-off-by: lines to the cc list.
Make git-send-email less verbose. One line per email should be
all that is output.
@@ -61,6 +67,10 @@ The options available are:
Only necessary if --compose is also set. If --compose
is not set, this will be prompted for.
+ Do not add the From: address to the cc: list, if it shows up in a From:
+ line.
Specify the primary recipient of the emails generated.
Generally, this will be the upstream maintainer of the
diff --git a/Documentation/git-svnimport.txt b/Documentation/git-svnimport.txt
index 63e28b8..5c543d5 100644
--- a/Documentation/git-svnimport.txt
+++ b/Documentation/git-svnimport.txt
@@ -61,6 +61,10 @@ When importing incrementally, you might need to edit the .git/svn2git file.
the git repository. Use this option if you want to import into a
different branch.
+ Prepend 'rX: ' to commit messages, where X is the imported
+ subversion revision.
Attempt to detect merges based on the commit message. This option
will enable default regexes that try to capture the name source
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index e8892bb..e1c76c6 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -8,11 +8,13 @@ git-tag - Create a tag object signed with GPG
'git-tag' [-a | -s | -u <key-id>] [-f | -d] [-m <msg>] <name> [<head>]
+'git-tag' -l [<pattern>]
-Adds a 'tag' reference in .git/refs/tags/
+Adds a 'tag' reference in `.git/refs/tags/`
Unless `-f` is given, the tag must not yet exist in
`.git/refs/tags/` directory.
@@ -32,6 +34,9 @@ GnuPG key for signing.
`-d <tag>` deletes the tag.
+`-l <pattern>` lists tags that match the given pattern (or all
+if no pattern is given).
@@ -49,6 +54,9 @@ OPTIONS
Delete an existing tag with the given name
+-l <pattern>::
+ List tags that match the given pattern (or all if no pattern is given).
-m <msg>::
Use the given tag message (instead of prompting)
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index c74311d..0a1b0ad 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -8,11 +8,14 @@ git-update-index - Modifies the index or directory cache
[--add] [--remove | --force-remove] [--replace]
[--refresh [-q] [--unmerged] [--ignore-missing]]
[--cacheinfo <mode> <object> <file>]\*
+ [--assume-unchanged | --no-assume-unchanged]
+ [--really-refresh]
[--info-only] [--index-info]
[-z] [--stdin]
@@ -65,6 +68,18 @@ OPTIONS
Set the execute permissions on the updated files.
+--assume-unchanged, --no-assume-unchanged::
+ When these flags are specified, the object name recorded
+ for the paths are not updated. Instead, these options
+ sets and unsets the "assume unchanged" bit for the
+ paths. When the "assume unchanged" bit is on, git stops
+ checking the working tree files for possible
+ modifications, so you need to manually unset the bit to
+ tell git when you change the working tree file. This is
+ sometimes helpful when working with a big project on a
+ filesystem that has very slow lstat(2) system call
+ (e.g. cifs).
Do not create objects in the object database for all
<file> arguments that follow this flag; just insert
@@ -193,6 +208,37 @@ $ git ls-files -s
+Using "assume unchanged" bit
+Many operations in git depend on your filesystem to have an
+efficient `lstat(2)` implementation, so that `st_mtime`
+information for working tree files can be cheaply checked to see
+if the file contents have changed from the version recorded in
+the index file. Unfortunately, some filesystems have
+inefficient `lstat(2)`. If your filesystem is one of them, you
+can set "assume unchanged" bit to paths you have not changed to
+cause git not to do this check. Note that setting this bit on a
+path does not mean git will check the contents of the file to
+see if it has changed -- it makes git to omit any checking and
+assume it has *not* changed. When you make changes to working
+tree files, you have to explicitly tell git about it by dropping
+"assume unchanged" bit, either before or after you modify them.
+In order to set "assume unchanged" bit, use `--assume-unchanged`
+option. To unset, use `--no-assume-unchanged`.
+The command looks at `core.ignorestat` configuration variable. When
+this is true, paths updated with `git-update-index paths...` and
+paths updated with other git commands that update both index and
+working tree (e.g. `git-apply --index`, `git-checkout-index -u`,
+and `git-read-tree -u`) are automatically marked as "assume
+unchanged". Note that "assume unchanged" bit is *not* set if
+`git-update-index --refresh` finds the working tree file matches
+the index (use `git-update-index --really-refresh` if you want
+to mark them as "assume unchanged").
To update and refresh only the files already checked out:
@@ -201,6 +247,35 @@ To update and refresh only the files already checked out:
$ git-checkout-index -n -f -a && git-update-index --ignore-missing --refresh
+On an inefficient filesystem with `core.ignorestat` set:
+$ git update-index --really-refresh <1>
+$ git update-index --no-assume-unchanged foo.c <2>
+$ git diff --name-only <3>
+$ edit foo.c
+$ git diff --name-only <4>
+M foo.c
+$ git update-index foo.c <5>
+$ git diff --name-only <6>
+$ edit foo.c
+$ git diff --name-only <7>
+$ git update-index --no-assume-unchanged foo.c <8>
+$ git diff --name-only <9>
+M foo.c
+<1> forces lstat(2) to set "assume unchanged" bits for paths
+ that match index.
+<2> mark the path to be edited.
+<3> this does lstat(2) and finds index matches the path.
+<4> this does lstat(2) and finds index does not match the path.
+<5> registering the new version to index sets "assume unchanged" bit.
+<6> and it is assumed unchanged.
+<7> even after you edit it.
+<8> you can tell about the change after the fact.
+<9> now it checks with lstat(2) and finds it has been changed.
@@ -213,6 +288,9 @@ in the index and the file mode on the filesystem if they differ only on
executable bit. On such an unfortunate filesystem, you may
need to use `git-update-index --chmod=`.
+The command looks at `core.ignorestat` configuration variable. See
+'Using "assume unchanged" bit' section above.
See Also