path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
17 files changed, 294 insertions, 31 deletions
diff --git a/Documentation/RelNotes-1.6.3.txt b/Documentation/RelNotes-1.6.3.txt
new file mode 100644
index 0000000..679ad28
--- /dev/null
+++ b/Documentation/RelNotes-1.6.3.txt
@@ -0,0 +1,104 @@
+GIT v1.6.3 Release Notes
+With the next major release, "git push" into a branch that is
+currently checked out will be refused by default. You can choose
+what should happen upon such a push by setting the configuration
+variable receive.denyCurrentBranch in the receiving repository.
+To ease the transition plan, the receiving repository of such a
+push running this release will issue a big warning when the
+configuration variable is missing. Please refer to:
+for more details on the reason why this change is needed and the
+transition plan.
+For a similar reason, "git push $there :$killed" to delete the branch
+$killed in a remote repository $there, if $killed branch is the current
+branch pointed at by its HEAD, gets a large warning. You can choose what
+should happen upon such a push by setting the configuration variable
+receive.denyDeleteCurrent in the receiving repository.
+Updates since v1.6.2
+(usability, bells and whistles)
+* "--pretty=<style>" option to the log family of commands can now be
+ spelled as "--format=<style>". In addition, --format=%formatstring
+ is a short-hand for --pretty=tformat:%formatstring.
+* "--oneline" is a synonym for "--pretty=oneline --abbrev=commit".
+* If you realize that you botched the patch when you are editing hunks
+ with the 'edit' action in git-add -i/-p, you can abort the editor to
+ tell git not to apply it.
+* git-archive learned --output=<file> option.
+* git-bisect shows not just the number of remaining commits whose goodness
+ is unknown, but also shows the estimated number of remaining rounds.
+* You can give --date=<format> option to git-blame.
+* git-branch -r shows HEAD symref that points at a remote branch in
+ interest of each tracked remote repository.
+* git-config learned -e option to open an editor to edit the config file
+ directly.
+* git-clone runs post-checkout hook when run without --no-checkout.
+* git-format-patch can be told to use attachment with a new configuration,
+ format.attach.
+* git-format-patch can be told to produce deep or shallow message threads.
+* git-imap-send learned to work around Thunderbird's inability to easily
+ disable format=flowed with a new configuration, imap.preformattedHTML.
+* git-rebase can be told to rebase the series even if your branch is a
+ descendant of the commit you are rebasing onto with --force-rebase
+ option.
+* git-rebase can be told to report diffstat with the --stat option.
+* git-send-email learned --confirm option to review the Cc: list before
+ sending the messages out.
+* Test scripts can be run under valgrind.
+* Makefile learned 'coverage' option to run the test suites with
+ coverage tracking enabled.
+Fixes since v1.6.2
+All of the fixes in v1.6.2.X maintenance series are included in this
+release, unless otherwise noted.
+Here are fixes that this release has, but have not been backported to
+v1.6.2.X series.
+* 'git-submodule add' did not tolerate extra slashes and ./ in the
+ path it accepted from the command line; it now is more lenient
+ (if needed, backport by merging db75ada).
+* git-gc spent excessive amount of time to decide if an object appears
+ in a locally existing pack (if needed, backport by merging 69e020a).
+exec >/var/tmp/1
+echo O=$(git describe master)
+git shortlog --no-merges $O..master ^maint
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9b559ad..8d818a2 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -491,6 +491,12 @@ message, complete the addressing and subject fields, and press send.
+GMail does not appear to have any way to turn off line wrapping in the web
+interface, so this will mangle any emails that you send. You can however
+use any IMAP email client to connect to the google imap server, and forward
+the emails through that. Just make sure to disable line wrapping in that
+email client. Alternatively, use "git send-email" instead.
Submitting properly formatted patches via Gmail is simple now that
IMAP support is available. First, edit your ~/.gitconfig to specify your
account settings:
@@ -503,6 +509,9 @@ account settings:
port = 993
sslverify = false
+You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
+that the "Folder doesn't exist".
Next, ensure that your Gmail settings are correct. In "Settings" the
"Use Unicode (UTF-8) encoding for outgoing messages" should be checked.
@@ -513,3 +522,4 @@ command to send the patch emails to your Gmail Drafts folder.
Go to your Gmail account, open the Drafts folder, find the patch email, fill
in the To: and CC: fields and send away!
diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index df2a7c1..63fc197 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -70,6 +70,14 @@ of lines before or after the line given by <start>.
tree copy has the contents of the named file (specify
`-` to make the command read from the standard input).
+--date <format>::
+ The value is one of the following alternatives:
+ {relative,local,default,iso,rfc,short}. If --date is not
+ provided, the value of the config variable is
+ used. If the config variable is also not set, the
+ iso format is used. For more information, See the discussion
+ of the --date option at linkgit:git-log[1].
Detect moving lines in the file as well. When a commit
moves a block of lines in a file (e.g. the original file
diff --git a/Documentation/config.txt b/Documentation/config.txt
index f5152c5..56bd781 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -677,6 +677,16 @@ format.pretty::
See linkgit:git-log[1], linkgit:git-show[1],
+ The default threading style for 'git-format-patch'. Can be
+ either a boolean value, `shallow` or `deep`. 'Shallow'
+ threading makes every mail a reply to the head of the series,
+ where the head is chosen from the cover letter, the
+ `\--in-reply-to`, and the first patch mail, in this order.
+ 'Deep' threading makes every mail a reply to the previous one.
+ A true boolean value is the same as `shallow`, and a false
+ value disables threading.
The window size parameter used in the delta compression
algorithm used by 'git-gc --aggressive'. This defaults
@@ -1160,6 +1170,10 @@ pull.octopus::
The default merge strategy to use when pulling a single branch.
+ Whether to show a diffstat of what changed upstream since the last
+ rebase. False by default.
If it is set to true, git-receive-pack will check all received
objects. It will abort in the case of a malformed object or a
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 5b3eb12..0eeefe0 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -10,6 +10,7 @@ SYNOPSIS
'git archive' --format=<fmt> [--list] [--prefix=<prefix>/] [<extra>]
+ [--output=<file>]
[--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
@@ -47,6 +48,9 @@ OPTIONS
Prepend <prefix>/ to each filename in the archive.
+ Write the archive to <file> instead of stdout.
This can be any options that the archiver backend understand.
See next section.
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 147ea38..e65c1ca 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -212,7 +212,7 @@ If you have a script that can tell if the current source code is good
or bad, you can automatically bisect using:
-$ git bisect run my_script
+$ git bisect run my_script arguments
Note that the "run" script (`my_script` in the above example) should
@@ -252,6 +252,13 @@ $ git bisect start HEAD v1.2 -- # HEAD is bad, v1.2 is good
$ git bisect run make # "make" builds the app
+* Automatically bisect a test failure between origin and HEAD:
+$ git bisect start HEAD origin -- # HEAD is bad, origin is good
+$ git bisect run make test # "make test" builds and tests
* Automatically bisect a broken test suite:
@@ -291,6 +298,15 @@ It's safer if both "" and "" scripts are
outside the repo to prevent interactions between the bisect, make and
test processes and the scripts.
+* Automatically bisect a broken test suite:
+$ git bisect start HEAD HEAD~10 -- # culprit is among the last 10
+$ git bisect run sh -c "make || exit 125; ~/"
+Does the same as the previous example, but on a single line.
Written by Linus Torvalds <>
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 3bccffa..125d8f3 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -8,7 +8,7 @@ git-checkout - Checkout a branch or paths to the working tree
-'git checkout' [-q] [-f] [--track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
+'git checkout' [-q] [-f] [-t | --track | --no-track] [-b <new_branch> [-l]] [-m] [<branch>]
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
@@ -21,15 +21,15 @@ specified, <new_branch>. Using -b will cause <new_branch> to
be created; in this case you can use the --track or --no-track
options, which will be passed to `git branch`.
-As a convenience, --track will default to create a branch whose
+As a convenience, --track will default to creating a branch whose
name is constructed from the specified branch name by stripping
the first namespace level.
When <paths> are given, this command does *not* switch
branches. It updates the named paths in the working tree from
the index file, or from a named <tree-ish> (most often a commit). In
-this case, the `-b` options is meaningless and giving
-either of them results in an error. <tree-ish> argument can be
+this case, the `-b` and `--track` options are meaningless and giving
+either of them results in an error. The <tree-ish> argument can be
used to specify a specific tree-ish (i.e. commit, tag or tree)
to update the index for the given paths before updating the
working tree.
@@ -75,14 +75,13 @@ entries; instead, unmerged entries are ignored.
<repository> <refspec>" explicitly. This behavior is the default
when the start point is a remote branch. Set the
branch.autosetupmerge configuration variable to `false` if you want
- 'git-checkout' and 'git-branch' to always behave as if '--no-track' were
+ 'git checkout' and 'git branch' to always behave as if '--no-track' were
given. Set it to `always` if you want this behavior when the
- start-point is either a local or remote branch.
+ start point is either a local or remote branch.
-If no '-b' option was given, the name of the new branch will be
-derived from the remote branch, by attempting to guess the name
-of the branch on remote system. If "remotes/" or "refs/remotes/"
-are prefixed, it is stripped away, and then the part up to the
+If no '-b' option is given, the name of the new branch will be
+derived from the remote branch. If "remotes/" or "refs/remotes/"
+is prefixed it is stripped away, and then the part up to the
next slash (which would be the nickname of the remote) is removed.
This would tell us to use "hack" as the local branch when branching
off of "origin/hack" (or "remotes/origin/hack", or even
@@ -152,12 +151,12 @@ $ git checkout v2.6.18
Earlier versions of git did not allow this and asked you to
-create a temporary branch using `-b` option, but starting from
+create a temporary branch using the `-b` option, but starting from
version 1.5.0, the above command 'detaches' your HEAD from the
-current branch and directly point at the commit named by the tag
-(`v2.6.18` in the above example).
+current branch and directly points at the commit named by the tag
+(`v2.6.18` in the example above).
-You can use usual git commands while in this state. You can use
+You can use all git commands while in this state. You can use
`git reset --hard $othercommit` to further move around, for
example. You can make changes and create a new commit on top of
a detached HEAD. You can even create a merge by using `git
@@ -191,7 +190,7 @@ $ git checkout hello.c <3>
<1> switch branch
-<2> take out a file out of other commit
+<2> take a file out of another commit
<3> restore hello.c from HEAD of current branch
If you have an unfortunate branch that is named `hello.c`, this
@@ -202,7 +201,7 @@ You should instead write:
$ git checkout -- hello.c
-. After working in a wrong branch, switching to the correct
+. After working in the wrong branch, switching to the correct
branch would be done using:
@@ -210,7 +209,7 @@ $ git checkout mytopic
However, your "wrong" branch and correct "mytopic" branch may
-differ in files that you have locally modified, in which case,
+differ in files that you have modified locally, in which case
the above checkout would fail like this:
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 6ab2af4..82ce89e 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -22,6 +22,7 @@ SYNOPSIS
'git config' [<file-option>] [-z|--null] -l | --list
'git config' [<file-option>] --get-color name [default]
'git config' [<file-option>] --get-colorbool name [stdout-is-tty]
+'git config' [<file-option>] -e | --edit
@@ -161,6 +162,11 @@ See also <<FILES>>.
output. The optional `default` parameter is used instead, if
there is no color configured for `name`.
+ Opens an editor to modify the specified config file; either
+ '--system', '--global', or repository (default).
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index 7ffe03f..237f85e 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -91,7 +91,9 @@ OPTIONS
--index-filter <command>::
This is the filter for rewriting the index. It is similar to the
tree filter but does not check out the tree, which makes it much
- faster. For hairy cases, see linkgit:git-update-index[1].
+ faster. Frequently used with `git rm \--cached
+ \--ignore-unmatch ...`, see EXAMPLES below. For hairy
+ cases, see linkgit:git-update-index[1].
--parent-filter <command>::
This is the filter for rewriting the commit's parent list.
@@ -204,19 +206,18 @@ However, if the file is absent from the tree of some commit,
a simple `rm filename` will fail for that tree and commit.
Thus you may instead want to use `rm -f filename` as the script.
-A significantly faster version:
+Using `\--index-filter` with 'git-rm' yields a significantly faster
+version. Like with using `rm filename`, `git rm --cached filename`
+will fail if the file is absent from the tree of a commit. If you
+want to "completely forget" a file, it does not matter when it entered
+history, so we also add `\--ignore-unmatch`:
-git filter-branch --index-filter 'git rm --cached filename' HEAD
+git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD
Now, you will get the rewritten history saved in HEAD.
-As with using `rm filename`, `git rm --cached filename` will fail
-if the file is absent from the tree of a commit. If it is not important
-whether the file is already absent from the tree, you can use
-`git rm --cached --ignore-unmatch filename` instead.
To rewrite the repository to look as if `foodir/` had been its project
root, and discard all other history:
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 11a7d77..c14e3ee 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -10,7 +10,8 @@ SYNOPSIS
'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
- [--attach[=<boundary>] | --inline[=<boundary>]]
+ [--attach[=<boundary>] | --inline[=<boundary>] |
+ [--no-attach]]
[-s | --signoff] [<common diff options>]
[-n | --numbered | -N | --no-numbered]
[--start-number <n>] [--numbered-files]
@@ -117,15 +118,27 @@ include::diff-options.txt[]
which is the commit message and the patch itself in the
second part, with "Content-Disposition: attachment".
+ Disable the creation of an attachment, overriding the
+ configuration setting.
Create multipart/mixed attachment, the first part of
which is the commit message and the patch itself in the
second part, with "Content-Disposition: inline".
Add In-Reply-To and References headers to make the second and
subsequent mails appear as replies to the first. Also generates
the Message-Id header to reference.
+The optional <style> argument can be either `shallow` or `deep`.
+'Shallow' threading makes every mail a reply to the head of the
+series, where the head is chosen from the cover letter, the
+`\--in-reply-to`, and the first patch mail, in this order. 'Deep'
+threading makes every mail a reply to the previous one. If not
+specified, defaults to the 'format.thread' configuration, or `shallow`
+if that is not set.
Make the first mail (or all the mails with --no-thread) appear as a
@@ -174,7 +187,8 @@ CONFIGURATION
You can specify extra mail header lines to be added to each message
in the repository configuration, new defaults for the subject prefix
-and file suffix, and number patches when outputting more than one.
+and file suffix, control attachements, and number patches when outputting
+more than one.
@@ -183,6 +197,7 @@ and file suffix, and number patches when outputting more than one.
suffix = .txt
numbered = auto
cc = <email>
+ attach [ = mime-boundary-string ]
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 1685f04..024084b 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -64,6 +64,13 @@ imap.sslverify::
used by the SSL/TLS connection. Default is `true`. Ignored when
imap.tunnel is set.
+ A boolean to enable/disable the use of html encoding when sending
+ a patch. An html encoded patch will be bracketed with <pre>
+ and have a content type of text/html. Ironically, enabling this
+ option causes Thunderbird to send the patch as a plain/text,
+ format=fixed email. Default is `false`.
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index da3c38c..57bd333 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -192,6 +192,13 @@ Alternatively, you can undo the 'git-rebase' with
git rebase --abort
+ Whether to show a diffstat of what changed upstream since the last
+ rebase. False by default.
@@ -232,7 +239,15 @@ OPTIONS
- Display a diffstat of what changed upstream since the last rebase.
+ Be verbose. Implies --stat.
+ Show a diffstat of what changed upstream since the last rebase. The
+ diffstat is also controlled by the configuration option rebase.stat.
+ Do not show a diffstat as part of the rebase process.
This option bypasses the pre-rebase hook. See also linkgit:githooks[5].
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index fc0a4ab..14dfb50 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -212,6 +212,22 @@ specified, as well as 'body' if --no-signed-off-cc is specified.
+ Confirm just before sending:
+- 'always' will always confirm before sending
+- 'never' will never confirm before sending
+- 'cc' will confirm before sending when send-email has automatically
+ added addresses from the patch to the Cc list
+- 'compose' will confirm before sending the first message when using --compose.
+- 'auto' is equivalent to 'cc' + 'compose'
+Default is the value of 'sendemail.confirm' configuration value; if that
+is unspecified, default to 'auto' unless any of the suppress options
+have been specified, in which case default to 'compose'.
Do everything except actually send the emails.
@@ -255,6 +271,11 @@ sendemail.multiedit::
summary when '--compose' is used). If false, files will be edited one
after the other, spawning a new editor each time.
+ Sets the default for whether to confirm before sending. Must be
+ one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
+ in the previous section for the meaning of these values.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 9a26bde..7513c57 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -43,9 +43,10 @@ unreleased) version of git, that is available from 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v1.6.2/git.html[documentation for release 1.6.2]
+* link:v1.6.2.1/git.html[documentation for release]
* release notes for
+ link:RelNotes-[],
* link:v1.6.1.3/git.html[documentation for release]
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 159390c..5c6e678 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -152,3 +152,12 @@ $ git log -2 --pretty=tformat:%h 4da45bef \
+In addition, any unrecognized string that has a `%` in it is interpreted
+as if it has `tformat:` in front of it. For example, these two are
+$ git log -2 --pretty=tformat:%h 4da45bef
+$ git log -2 --pretty=%h 4da45bef
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 5f21efe..bff9499 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -1,4 +1,5 @@
Pretty-print the contents of the commit logs in a given format,
where '<format>' can be one of 'oneline', 'short', 'medium',
@@ -17,6 +18,10 @@ configuration (see linkgit:git-config[1]).
This should make "--pretty=oneline" a whole lot more readable for
people using 80-column terminals.
+ This is a shorthand for "--pretty=oneline --abbrev-commit"
+ used together.
The commit objects record the encoding used for the log message
in their encoding header; this option can be used to tell the
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index 539863b..e66ca9f 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -66,6 +66,12 @@ Steps to parse options
non-option arguments in `argv[]`.
`argc` is updated appropriately because of the assignment.
+You can also pass NULL instead of a usage array as fourth parameter of
+parse_options(), to avoid displaying a help screen with usage info and
+option list. This should only be done if necessary, e.g. to implement
+a limited parser for only a subset of the options that needs to be run
+before the full parser, which in turn shows the full help message.
Flags are the bitwise-or of:
@@ -77,6 +83,28 @@ Flags are the bitwise-or of:
Using this flag, processing is stopped at the first non-option
+ Keep the first argument, which contains the program name. It's
+ removed from argv[] by default.
+ Keep unknown arguments instead of erroring out. This doesn't
+ work for all combinations of arguments as users might expect
+ it to do. E.g. if the first argument in `--unknown --known`
+ takes a value (which we can't know), the second one is
+ mistakenly interpreted as a known option. Similarly, if
+ `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
+ `--unknown value` will be mistakenly interpreted as a
+ non-option, not as a value belonging to the unknown option,
+ the parser early. That's why parse_options() errors out if
+ both options are set.
+ By default, parse_options() handles `-h`, `--help` and
+ `--help-all` internally, by showing a help screen. This option
+ turns it off and allows one to add custom handlers for these
+ options, or to just leave them unknown.
Data Structure