path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
15 files changed, 256 insertions, 30 deletions
diff --git a/Documentation/RelNotes-1.6.4.txt b/Documentation/RelNotes-1.6.4.txt
new file mode 100644
index 0000000..af68297
--- /dev/null
+++ b/Documentation/RelNotes-1.6.4.txt
@@ -0,0 +1,93 @@
+GIT v1.6.4 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.
+When the user does not tell "git push" what to push, it has always
+pushed matching refs. For some people it is unexpected, and a new
+configuration variable push.default has been introduced to allow
+changing a different default behaviour. To advertise the new feature,
+a big warning is issued if this is not configured and a git push without
+arguments is attempted.
+Updates since v1.6.3
+ * gitweb Perl style clean-up.
+ * git-svn updates, including a new --authors-prog option to map author
+ names by invoking an external program.
+ * We feed iconv with "UTF-8" instead of "utf8"; the former is
+ understood more widely.
+(usability, bells and whistles)
+ * "git add --edit" lets users edit the whole patch text to fine-tune what
+ is added to the index.
+ * "git log --graph" draws graphs more compactly by using horizonal lines
+ when able.
+ * "git log --decorate" shows shorter refnames by stripping well-known
+ refs/* prefix.
+ * "git send-email" understands quoted aliases in .mailrc files (might
+ have to be backported to 1.6.3.X).
+ * "git send-email" can fetch the sender address from the configuration
+ variable "sendmail.from" (and "sendmail.<identity>.from").
+ * "git show-branch" can color its output.
+ * "add" and "update" subcommands to "git submodule" learned --reference
+ option to use local clone with references.
+ * A major part of the "git bisect" wrapper has moved to C.
+Fixes since v1.6.3
+All of the fixes in v1.6.3.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.3.X series.
+ * The way sets up a Repository object was not friendly to callers
+ that chdir around. It now internally records the repository location
+ as an absolute path when autodetected.
+exec >/var/tmp/1
+echo O=$(git describe master)
+git shortlog --no-merges $O..master ^maint
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 5dcad94..3a86d1f 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -438,6 +438,11 @@ On some file system/operating system combinations, this is unreliable.
Set this config setting to 'rename' there; However, This will remove the
check that makes sure that existing object files will not get overwritten.
+ Tells 'git-add' to continue adding files when some files cannot be
+ added due to indexing errors. Equivalent to the '--ignore-errors'
+ option of linkgit:git-add[1].
Command aliases for the linkgit:git[1] command wrapper - e.g.
after defining "alias.last = cat-file commit HEAD", the invocation
@@ -604,6 +609,12 @@ color.pager::
A boolean to enable/disable colored output when the pager is in
use (default is true).
+ A boolean to enable/disable color in the output of
+ linkgit:git-show-branch[1]. May be set to `always`,
+ `false` (or `never`) or `auto` (or `true`), in which case colors are used
+ only when the output is to a terminal. Defaults to false.
A boolean to enable/disable color in the output of
linkgit:git-status[1]. May be set to `always`,
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index d938b42..ab1943c 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -9,7 +9,7 @@ SYNOPSIS
'git add' [-n] [-v] [--force | -f] [--interactive | -i] [--patch | -p]
- [--all | [--update | -u]] [--intent-to-add | -N]
+ [--edit | -e] [--all | [--update | -u]] [--intent-to-add | -N]
[--refresh] [--ignore-errors] [--] <filepattern>...
@@ -76,6 +76,15 @@ OPTIONS
bypassed and the 'patch' subcommand is invoked using each of
the specified filepatterns before exiting.
+-e, \--edit::
+ Open the diff vs. the index in an editor and let the user
+ edit it. After the editor was closed, adjust the hunk headers
+ and apply the patch to the index.
+*NOTE*: Obviously, if you change anything else than the first character
+on lines beginning with a space or a minus, the patch will no longer
Update only files that git already knows about, staging modified
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 9e5baa2..735374d 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -3,7 +3,7 @@ git-apply(1)
-git-apply - Apply a patch on a git index file and a working tree
+git-apply - Apply a patch on a git index file and/or a working tree
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index cbd4275..ae201de 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -111,6 +111,7 @@ OPTIONS
Display the full sha1s in the output listing rather than abbreviating them.
When creating a new branch, set up configuration to mark the
start-point branch as "upstream" from the new branch. This
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index c1ce268..0b7982e 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -25,6 +25,10 @@ imposes the following rules on how references are named:
grouping, but no slash-separated component can begin with a
dot `.`.
+. They must contain at least one `/`. This enforces the presence of a
+ category like `heads/`, `tags/` etc. but the actual names are not
+ restricted.
. They cannot have two consecutive dots `..` anywhere.
. They cannot have ASCII control characters (i.e. bytes whose
@@ -38,6 +42,8 @@ imposes the following rules on how references are named:
. They cannot contain a sequence `@{`.
+- They cannot contain a `\\`.
These rules make it easy for shell script based tools to parse
reference names, pathname expansion by the shell when a reference name is used
unquoted (by mistake), and also avoids ambiguities in certain
diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt
index af19f06..81e3326 100644
--- a/Documentation/git-mktree.txt
+++ b/Documentation/git-mktree.txt
@@ -8,12 +8,13 @@ git-mktree - Build a tree-object from ls-tree formatted text
-'git mktree' [-z]
+'git mktree' [-z] [--missing] [--batch]
-Reads standard input in non-recursive `ls-tree` output format,
-and creates a tree object. The object name of the tree object
+Reads standard input in non-recursive `ls-tree` output format, and creates
+a tree object. The order of the tree entries is normalised by mktree so
+pre-sorting the input is not required. The object name of the tree object
built is written to the standard output.
@@ -21,6 +22,18 @@ OPTIONS
Read the NUL-terminated `ls-tree -z` output instead.
+ Allow missing objects. The default behaviour (without this option)
+ is to verify that each tree entry's sha1 identifies an existing
+ object. This option has no effect on the treatment of gitlink entries
+ (aka "submodules") which are always allowed to be missing.
+ Allow building of more than one tree object before exiting. Each
+ tree is separated by as single blank line. The final new-line is
+ optional. Note - if the '-z' option is used, lines are terminated
+ with NUL.
Written by Junio C Hamano <>
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 3d5a066..26f3b7b 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -231,8 +231,7 @@ OPTIONS
-s <strategy>::
- Use the given merge strategy; can be supplied more than
- once to specify them in the order they should be tried.
+ Use the given merge strategy.
If there is no `-s` option, a built-in list of strategies
is used instead ('git-merge-recursive' when merging a single
head, 'git-merge-octopus' otherwise). This implies --merge.
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 52c353e..4bbdd05 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -30,6 +30,11 @@ OPTIONS
Only meaningful in `--parseopt` mode. Tells the option parser to echo
out the first `--` met instead of skipping it.
+ Use 'git-rev-parse' in shell quoting mode (see SQ-QUOTE
+ section below). In contrast to the `--sq` option below, this
+ mode does only quoting. Nothing else is done to command input.
Do not output flags and parameters not meant for
'git-rev-list' command.
@@ -64,7 +69,8 @@ OPTIONS
properly quoted for consumption by shell. Useful when
you expect your parameter to contain whitespaces and
newlines (e.g. when using pickaxe `-S` with
- 'git-diff-\*').
+ 'git-diff-\*'). In contrast to the `--sq-quote` option,
+ the command input is still interpreted as usual.
When showing object names, prefix them with '{caret}' and
@@ -406,6 +412,33 @@ C? option C with an optional argument"
eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
+In `--sq-quote` mode, 'git-rev-parse' echoes on the standard output a
+single line suitable for `sh(1)` `eval`. This line is made by
+normalizing the arguments following `--sq-quote`. Nothing other than
+quoting the arguments is done.
+If you want command input to still be interpreted as usual by
+'git-rev-parse' before the output is shell quoted, see the `--sq`
+$ cat > <<\EOF
+args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
+command="git frotz -n24 $args" # and use it inside a handcrafted
+ # command line
+eval "$command"
+$ sh "a b'c"
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 794224b..7c5ce41 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -39,6 +39,10 @@ OPTIONS
+ Review and edit each patch you're about to send. See the
+ CONFIGURATION section for 'sendemail.multiedit'.
Specify a "Bcc:" value for each email. Default is the value of
@@ -51,11 +55,6 @@ The --bcc option must be repeated for each user you want on the bcc list.
The --cc option must be repeated for each user you want on the cc list.
- Review each patch you're about to send in an editor. The setting
- 'sendemail.multiedit' defines if this will spawn one editor per patch
- or one for all of them at once.
Use $GIT_EDITOR, core.editor, $VISUAL, or $EDITOR to edit an
introductory message for the patch series.
@@ -67,11 +66,16 @@ In-Reply-To headers specified in the message. If the body of the message
and In-Reply-To headers will be used unless they are removed.
Missing From or In-Reply-To headers will be prompted for.
+See the CONFIGURATION section for 'sendemail.multiedit'.
- Specify the sender of the emails. This will default to
- the value GIT_COMMITTER_IDENT, as returned by "git var -l".
- The user will still be prompted to confirm this entry.
+ Specify the sender of the emails. If not specified on the command line,
+ the value of the 'sendemail.from' configuration option is used. If
+ neither the command line option nor 'sendemail.from' are set, then the
+ user will be prompted for the value. The default for the prompt will be
+ the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not
+ set, as returned by "git var -l".
Specify the contents of the first In-Reply-To header.
@@ -135,7 +139,9 @@ user is prompted for a password while the input is masked for privacy.
Specifies a port different from the default port (SMTP
servers typically listen to smtp port 25 and ssmtp port
- 465). This can be set with 'sendemail.smtpserverport'.
+ 465); symbolic port names (e.g. "submission" instead of 465)
+ are also accepted. The port can also be set with the
+ 'sendemail.smtpserverport' configuration variable.
Legacy alias for '--smtp-encryption ssl'.
@@ -230,6 +236,12 @@ have been specified, in which case default to 'compose'.
Do everything except actually send the emails.
+ When an argument may be understood either as a reference or as a file name,
+ choose to understand it as a format-patch argument ('--format-patch')
+ or as a file name ('--no-format-patch'). By default, when such a conflict
+ occurs, git send-email will fail.
Make git-send-email less verbose. One line per email should be
all that is output.
@@ -246,12 +258,6 @@ have been specified, in which case default to 'compose'.
Default is the value of 'sendemail.validate'; if this is not set,
default to '--validate'.
- When an argument may be understood either as a reference or as a file name,
- choose to understand it as a format-patch argument ('--format-patch')
- or as a file name ('--no-format-patch'). By default, when such a conflict
- occurs, git send-email will fail.
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 51a4e9d..89ec536 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -8,9 +8,11 @@ git-show-branch - Show branches and their commits
-'git show-branch' [--all] [--remotes] [--topo-order] [--current]
+'git show-branch' [--all] [--remotes] [--topo-order | --date-order]
+ [--current] [--color | --no-color]
[--more=<n> | --list | --independent | --merge-base]
- [--no-name | --sha1-name] [--topics] [<rev> | <glob>]...
+ [--no-name | --sha1-name] [--topics]
+ [<rev> | <glob>]...
'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
@@ -57,6 +59,11 @@ OPTIONS
appear in topological order (i.e., descendant commits
are shown before their parents).
+ This option is similar to '--topo-order' in the sense that no
+ parent comes before all of its children, but otherwise commits
+ are ordered according to their commit date.
By default, the output omits merges that are reachable
from only one tip being shown. This option makes them
@@ -107,6 +114,14 @@ OPTIONS
When no explicit <ref> parameter is given, it defaults to the
current branch (or `HEAD` if it is detached).
+ Color the status sign (one of these: `*` `!` `+` `-`) of each commit
+ corresponding to the branch it's in.
+ Turn off colored output, even when the configuration file gives the
+ default to color output.
Note that --more, --list, --independent and --merge-base options
are mutually exclusive.
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 3b8df44..14256c6 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,10 +9,12 @@ git-submodule - Initialize, update or inspect submodules
-'git submodule' [--quiet] add [-b branch] [--] <repository> <path>
+'git submodule' [--quiet] add [-b branch]
+ [--reference <repository>] [--] <repository> <path>
'git submodule' [--quiet] status [--cached] [--] [<path>...]
'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--] [<path>...]
+'git submodule' [--quiet] update [--init] [-N|--no-fetch]
+ [--reference <repository>] [--] [<path>...]
'git submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
'git submodule' [--quiet] foreach <command>
'git submodule' [--quiet] sync [--] [<path>...]
@@ -177,6 +179,14 @@ OPTIONS
This option is only valid for the update command.
Don't fetch new objects from the remote site.
+--reference <repository>::
+ This option is only valid for add and update commands. These
+ commands sometimes need to clone a remote repository. In this case,
+ this option will be passed to the linkgit:git-clone[1] command.
+*NOTE*: Do *not* use this option unless you have read the note
+for linkgit:git-clone[1]'s --reference and --shared options carefully.
Paths to submodule(s). When specified this will restrict the command
to only operate on the submodules found at the specified paths.
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 1c40894..ca3fc3d 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -398,6 +398,14 @@ after the authors-file is modified should continue operation.
config key: svn.authorsfile
+If this option is specified, for each SVN committer name that does not
+exist in the authors file, the given file is executed with the committer
+name as the first argument. The program is expected to return a single
+line of the form "Name <email>", which will be treated as if included in
+the authors file.
Make 'git-svn' less verbose. Specify a second time to make it
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 3589a12..56d4770 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -43,7 +43,12 @@ 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.3/git.html[documentation for release 1.6.3]
+* link:v1.6.3.2/git.html[documentation for release]
+* release notes for
+ link:RelNotes-[],
+ link:RelNotes-[],
+ link:RelNotes-1.6.3.txt[1.6.3].
* release notes for
diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
index e30c602..50f9e9a 100644
--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt
@@ -60,13 +60,13 @@ Steps to parse options
. in `cmd_foo(int argc, const char **argv, const char *prefix)`
- argc = parse_options(argc, argv, builtin_foo_options, builtin_foo_usage, flags);
+ argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
`parse_options()` will filter out the processed options of `argv[]` and leave the
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
+You can also pass NULL instead of a usage array as the fifth 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
@@ -137,6 +137,10 @@ There are some macros to easily define options:
Introduce a boolean option.
If used, `int_var` is bitwise-ored with `mask`.
+`OPT_NEGBIT(short, long, &int_var, description, mask)`::
+ Introduce a boolean option.
+ If used, `int_var` is bitwise-anded with the inverted `mask`.
`OPT_SET_INT(short, long, &int_var, description, integer)`::
Introduce a boolean option.
If used, set `int_var` to `integer`.
@@ -163,9 +167,22 @@ There are some macros to easily define options:
and the result will be put into `var`.
See 'Option Callbacks' below for a more elaborate description.
+`OPT_FILENAME(short, long, &var, description)`::
+ Introduce an option with a filename argument.
+ The filename will be prefixed by passing the filename along with
+ the prefix argument of `parse_options()` to `prefix_filename()`.
`OPT_ARGUMENT(long, description)`::
Introduce a long-option argument that will be kept in `argv[]`.
+`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
+ Recognize numerical options like -123 and feed the integer as
+ if it was an argument to the function given by `func_ptr`.
+ The result will be put into `var`. There can be only one such
+ option definition. It cannot be negated and it takes no
+ arguments. Short options that happen to be digits take
+ precedence over it.
The last element of the array must be `OPT_END()`.