summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines150
-rw-r--r--Documentation/Makefile1
-rw-r--r--Documentation/RelNotes/1.9.4.txt16
-rw-r--r--Documentation/RelNotes/2.0.0.txt88
-rw-r--r--Documentation/RelNotes/2.1.0.txt200
-rw-r--r--Documentation/config.txt30
-rw-r--r--Documentation/diff-config.txt2
-rw-r--r--Documentation/git-bisect.txt2
-rw-r--r--Documentation/git-config.txt2
-rw-r--r--Documentation/git-daemon.txt6
-rw-r--r--Documentation/git-fast-import.txt10
-rw-r--r--Documentation/git-grep.txt3
-rw-r--r--Documentation/git-help.txt12
-rw-r--r--Documentation/git-ls-files.txt6
-rw-r--r--Documentation/git-merge.txt5
-rw-r--r--Documentation/git-mergetool.txt8
-rw-r--r--Documentation/git-patch-id.txt37
-rw-r--r--Documentation/git-read-tree.txt2
-rw-r--r--Documentation/git-replace.txt16
-rw-r--r--Documentation/git-send-email.txt6
-rw-r--r--Documentation/git-svn.txt4
-rw-r--r--Documentation/git-update-ref.txt18
-rw-r--r--Documentation/git-web--browse.txt4
-rw-r--r--Documentation/git.txt16
-rw-r--r--Documentation/gitcli.txt8
-rw-r--r--Documentation/gitk.txt2
-rw-r--r--Documentation/gitweb.conf.txt2
-rw-r--r--Documentation/howto/keep-canonical-history-correct.txt216
-rw-r--r--Documentation/howto/setup-git-server-over-http.txt2
-rw-r--r--Documentation/revisions.txt4
-rw-r--r--Documentation/technical/api-builtin.txt13
-rw-r--r--Documentation/technical/api-hashmap.txt1
-rw-r--r--Documentation/technical/api-strbuf.txt9
-rw-r--r--Documentation/technical/http-protocol.txt2
-rw-r--r--Documentation/user-manual.txt4
35 files changed, 779 insertions, 128 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index f424dbd..4d90c77 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -18,6 +18,14 @@ code. For Git in general, three rough rules are:
judgement call, the decision based more on real world
constraints people face than what the paper standard says.
+ - Fixing style violations while working on a real change as a
+ preparatory clean-up step is good, but otherwise avoid useless code
+ churn for the sake of conforming to the style.
+
+ "Once it _is_ in the tree, it's not really worth the patch noise to
+ go and fix it up."
+ Cf. http://article.gmane.org/gmane.linux.kernel/943020
+
Make your code readable and sensible, and don't try to be clever.
As for more concrete guidelines, just imitate the existing code
@@ -34,7 +42,17 @@ For shell scripts specifically (not exhaustive):
- We use tabs for indentation.
- - Case arms are indented at the same depth as case and esac lines.
+ - Case arms are indented at the same depth as case and esac lines,
+ like this:
+
+ case "$variable" in
+ pattern1)
+ do this
+ ;;
+ pattern2)
+ do that
+ ;;
+ esac
- Redirection operators should be written with space before, but no
space after them. In other words, write 'echo test >"$file"'
@@ -43,6 +61,14 @@ For shell scripts specifically (not exhaustive):
redirection target in a variable (as shown above), our code does so
because some versions of bash issue a warning without the quotes.
+ (incorrect)
+ cat hello > world < universe
+ echo hello >$world
+
+ (correct)
+ cat hello >world <universe
+ echo hello >"$world"
+
- We prefer $( ... ) for command substitution; unlike ``, it
properly nests. It should have been the way Bourne spelled
it from day one, but unfortunately isn't.
@@ -81,14 +107,33 @@ For shell scripts specifically (not exhaustive):
"then" should be on the next line for if statements, and "do"
should be on the next line for "while" and "for".
+ (incorrect)
+ if test -f hello; then
+ do this
+ fi
+
+ (correct)
+ if test -f hello
+ then
+ do this
+ fi
+
- We prefer "test" over "[ ... ]".
- We do not write the noiseword "function" in front of shell
functions.
- - We prefer a space between the function name and the parentheses. The
- opening "{" should also be on the same line.
- E.g.: my_function () {
+ - We prefer a space between the function name and the parentheses,
+ and no space inside the parentheses. The opening "{" should also
+ be on the same line.
+
+ (incorrect)
+ my_function(){
+ ...
+
+ (correct)
+ my_function () {
+ ...
- As to use of grep, stick to a subset of BRE (namely, no \{m,n\},
[::], [==], or [..]) for portability.
@@ -106,6 +151,19 @@ For shell scripts specifically (not exhaustive):
interface translatable. See "Marking strings for translation" in
po/README.
+ - We do not write our "test" command with "-a" and "-o" and use "&&"
+ or "||" to concatenate multiple "test" commands instead, because
+ the use of "-a/-o" is often error-prone. E.g.
+
+ test -n "$x" -a "$a" = "$b"
+
+ is buggy and breaks when $x is "=", but
+
+ test -n "$x" && test "$a" = "$b"
+
+ does not have such a problem.
+
+
For C programs:
- We use tabs to indent, and interpret tabs as taking up to
@@ -149,7 +207,7 @@ For C programs:
of "else if" statements, it can make sense to add braces to
single line blocks.
- - We try to avoid assignments inside if().
+ - We try to avoid assignments in the condition of an "if" statement.
- Try to make your code understandable. You may put comments
in, but comments invariably tend to stale out when the code
@@ -177,6 +235,88 @@ For C programs:
- Double negation is often harder to understand than no negation
at all.
+ - There are two schools of thought when it comes to comparison,
+ especially inside a loop. Some people prefer to have the less stable
+ value on the left hand side and the more stable value on the right hand
+ side, e.g. if you have a loop that counts variable i down to the
+ lower bound,
+
+ while (i > lower_bound) {
+ do something;
+ i--;
+ }
+
+ Other people prefer to have the textual order of values match the
+ actual order of values in their comparison, so that they can
+ mentally draw a number line from left to right and place these
+ values in order, i.e.
+
+ while (lower_bound < i) {
+ do something;
+ i--;
+ }
+
+ Both are valid, and we use both. However, the more "stable" the
+ stable side becomes, the more we tend to prefer the former
+ (comparison with a constant, "i > 0", is an extreme example).
+ Just do not mix styles in the same part of the code and mimic
+ existing styles in the neighbourhood.
+
+ - There are two schools of thought when it comes to splitting a long
+ logical line into multiple lines. Some people push the second and
+ subsequent lines far enough to the right with tabs and align them:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of ||
+ the_source_text) {
+ ...
+
+ while other people prefer to align the second and the subsequent
+ lines with the column immediately inside the opening parenthesis,
+ with tabs and spaces, following our "tabstop is always a multiple
+ of 8" convention:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of ||
+ the_source_text) {
+ ...
+
+ Both are valid, and we use both. Again, just do not mix styles in
+ the same part of the code and mimic existing styles in the
+ neighbourhood.
+
+ - When splitting a long logical line, some people change line before
+ a binary operator, so that the result looks like a parse tree when
+ you turn your head 90-degrees counterclockwise:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to
+ || span_more_than_a_single_line_of_the_source_text) {
+
+ while other people prefer to leave the operator at the end of the
+ line:
+
+ if (the_beginning_of_a_very_long_expression_that_has_to ||
+ span_more_than_a_single_line_of_the_source_text) {
+
+ Both are valid, but we tend to use the latter more, unless the
+ expression gets fairly complex, in which case the former tends to
+ be easier to read. Again, just do not mix styles in the same part
+ of the code and mimic existing styles in the neighbourhood.
+
+ - When splitting a long logical line, with everything else being
+ equal, it is preferable to split after the operator at higher
+ level in the parse tree. That is, this is more preferable:
+
+ if (a_very_long_variable * that_is_used_in +
+ a_very_long_expression) {
+ ...
+
+ than
+
+ if (a_very_long_variable *
+ that_is_used_in + a_very_long_expression) {
+ ...
+
- Some clever tricks, like using the !! operator with arithmetic
constructs, can be extremely confusing to others. Avoid them,
unless there is a compelling reason to use them.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index fc6b2cf..cea0e7a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -59,6 +59,7 @@ SP_ARTICLES += howto/recover-corrupted-blob-object
SP_ARTICLES += howto/recover-corrupted-object-harder
SP_ARTICLES += howto/rebuild-from-update-hook
SP_ARTICLES += howto/rebase-from-internal-branch
+SP_ARTICLES += howto/keep-canonical-history-correct
SP_ARTICLES += howto/maintain-git
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
SP_ARTICLES += $(API_DOCS)
diff --git a/Documentation/RelNotes/1.9.4.txt b/Documentation/RelNotes/1.9.4.txt
new file mode 100644
index 0000000..e1d1835
--- /dev/null
+++ b/Documentation/RelNotes/1.9.4.txt
@@ -0,0 +1,16 @@
+Git v1.9.4 Release Notes
+========================
+
+Fixes since v1.9.3
+------------------
+
+ * Commands that take pathspecs on the command line misbehaved when
+ the pathspec is given as an absolute pathname (which is a
+ practice not particularly encouraged) that points at a symbolic
+ link in the working tree.
+
+ * An earlier fix to the shell prompt script (in contrib/) for using
+ the PROMPT_COMMAND interface did not correctly check if the extra
+ code path needs to trigger, causing the branch name not to appear
+ when 'promptvars' option is disabled in bash or PROMPT_SUBST is
+ unset in zsh.
diff --git a/Documentation/RelNotes/2.0.0.txt b/Documentation/RelNotes/2.0.0.txt
index 6e628d4..2617372 100644
--- a/Documentation/RelNotes/2.0.0.txt
+++ b/Documentation/RelNotes/2.0.0.txt
@@ -44,7 +44,7 @@ with "git diff-files --diff-filter=d").
The default prefix for "git svn" has changed in Git 2.0. For a long
time, "git svn" created its remote-tracking branches directly under
refs/remotes, but it now places them under refs/remotes/origin/ unless
-it is told otherwise with its --prefix option.
+it is told otherwise with its "--prefix" option.
Updates since v1.9 series
@@ -53,7 +53,11 @@ Updates since v1.9 series
UI, Workflows & Features
* The "multi-mail" post-receive hook (in contrib/) has been updated
- to a more recent version from the upstream.
+ to a more recent version from upstream.
+
+ * The "remote-hg/bzr" remote-helper interfaces (used to be in
+ contrib/) are no more. They are now maintained separately as
+ third-party plug-ins in their own repositories.
* "git gc --aggressive" learned "--depth" option and
"gc.aggressiveDepth" configuration variable to allow use of a less
@@ -63,12 +67,13 @@ UI, Workflows & Features
single strand-of-pearls is broken in its output.
* The "rev-parse --parseopt" mechanism used by scripted Porcelains to
- parse command line options and to give help text learned to take
+ parse command-line options and to give help text learned to take
the argv-help (the placeholder string for an option parameter,
e.g. "key-id" in "--gpg-sign=<key-id>").
* The pattern to find where the function begins in C/C++ used in
- "diff" and "grep -p" has been updated to help C++ source better.
+ "diff" and "grep -p" has been updated to improve viewing C++
+ sources.
* "git rebase" learned to interpret a lone "-" as "@{-1}", the
branch that we were previously on.
@@ -79,7 +84,7 @@ UI, Workflows & Features
"--sort=version:refname".
* Discard the accumulated "heuristics" to guess from which branch the
- result wants to be pulled from and make sure what the end user
+ result wants to be pulled from and make sure that what the end user
specified is not second-guessed by "git request-pull", to avoid
mistakes. When you pushed out your 'master' branch to your public
repository as 'for-linus', use the new "master:for-linus" syntax to
@@ -88,9 +93,9 @@ UI, Workflows & Features
* "git grep" learned to behave in a way similar to native grep when
"-h" (no header) and "-c" (count) options are given.
- * "git push" via transport-helper interface (e.g. remote-hg) has
- been updated to allow forced ref updates in a way similar to the
- natively supported transports.
+ * "git push" via transport-helper interface has been updated to
+ allow forced ref updates in a way similar to the natively
+ supported transports.
* The "simple" mode is the default for "git push".
@@ -114,28 +119,28 @@ UI, Workflows & Features
* The progress indicators from various time-consuming commands have
been marked for i18n/l10n.
- * "git notes -C <blob>" diagnoses an attempt to use an object that
- is not a blob as an error.
+ * "git notes -C <blob>" diagnoses as an error an attempt to use an
+ object that is not a blob.
* "git config" learned to read from the standard input when "-" is
given as the value to its "--file" parameter (attempting an
- operation to update the configuration in the standard input of
- course is rejected).
+ operation to update the configuration in the standard input is
+ rejected, of course).
* Trailing whitespaces in .gitignore files, unless they are quoted
for fnmatch(3), e.g. "path\ ", are warned and ignored. Strictly
- speaking, this is a backward incompatible change, but very unlikely
+ speaking, this is a backward-incompatible change, but very unlikely
to bite any sane user and adjusting should be obvious and easy.
- * Many commands that create commits, e.g. "pull", "rebase",
- learned to take the --gpg-sign option on the command line.
+ * Many commands that create commits, e.g. "pull" and "rebase",
+ learned to take the "--gpg-sign" option on the command line.
* "git commit" can be told to always GPG sign the resulting commit
- by setting "commit.gpgsign" configuration variable to true (the
- command line option --no-gpg-sign should override it).
+ by setting the "commit.gpgsign" configuration variable to "true"
+ (the command-line option "--no-gpg-sign" should override it).
* "git pull" can be told to only accept fast-forward by setting the
- new "pull.ff" configuration.
+ new "pull.ff" configuration variable.
* "git reset" learned the "-N" option, which does not reset the index
fully for paths the index knows about but the tree-ish the command
@@ -152,7 +157,7 @@ Performance, Internal Implementation, etc.
* Uses of curl's "multi" interface and "easy" interface do not mix
well when we attempt to reuse outgoing connections. Teach the RPC
- over http code, used in the smart HTTP transport, not to use the
+ over HTTP code, used in the smart HTTP transport, not to use the
"easy" interface.
* The bitmap-index feature from JGit has been ported, which should
@@ -186,24 +191,19 @@ notes for details).
* The shell prompt script (in contrib/), when using the PROMPT_COMMAND
interface, used an unsafe construct when showing the branch name in
$PS1.
- (merge 8976500 rh/prompt-pcmode-avoid-eval-on-refname later to maint).
-
- * The remote-helper interface to fast-import/fast-export via the
- transport-helper has been tightened to avoid leaving the import
- marks file from a failed/crashed run, as such a file that is out of
- sync with the reality confuses a later invocation of itself.
+ (merge 1e4119c8 rh/prompt-pcmode-avoid-eval-on-refname later to maint).
- * "git rebase" used a POSIX shell construct FreeBSD /bin/sh does not
+ * "git rebase" used a POSIX shell construct FreeBSD's /bin/sh does not
work well with.
(merge 8cd6596 km/avoid-non-function-return-in-rebase later to maint).
* zsh prompt (in contrib/) leaked unnecessary error messages.
- * bash completion (in contrib/) did not complete the refs and remotes
+ * Bash completion (in contrib/) did not complete the refs and remotes
correctly given "git pu<TAB>" when "pu" is aliased to "push".
- * Some more Unicode codepoints defined in Unicode 6.3 as having zero
- width have been taught to our display column counting logic.
+ * Some more Unicode code points, defined in Unicode 6.3 as having zero
+ width, have been taught to our display column counting logic.
(merge d813ab9 tb/unicode-6.3-zero-width later to maint).
* Some tests used shell constructs that did not work well on FreeBSD
@@ -217,7 +217,7 @@ notes for details).
* "git diff --no-index -Mq a b" fell into an infinite loop.
(merge ad1c3fb jc/fix-diff-no-index-diff-opt-parse later to maint).
- * "git fetch --prune", when the right-hand-side of multiple fetch
+ * "git fetch --prune", when the right-hand side of multiple fetch
refspecs overlap (e.g. storing "refs/heads/*" to
"refs/remotes/origin/*", while storing "refs/frotz/*" to
"refs/remotes/origin/fr/*"), aggressively thought that lack of
@@ -272,7 +272,7 @@ notes for details).
(merge 3c3e6f5 rr/doc-merge-strategies later to maint).
* Serving objects from a shallow repository needs to write a
- new file to hold the temporary shallow boundaries but it was not
+ new file to hold the temporary shallow boundaries, but it was not
cleaned when we exit due to die() or a signal.
(merge 7839632 jk/shallow-update-fix later to maint).
@@ -295,19 +295,19 @@ notes for details).
".git" tells us where it is.
(merge fcfec8b da/difftool-git-files later to maint).
- * "git push" did not pay attention to branch.*.pushremote if it is
- defined earlier than remote.pushdefault; the order of these two
+ * "git push" did not pay attention to "branch.*.pushremote" if it is
+ defined earlier than "remote.pushdefault"; the order of these two
variables in the configuration file should not matter, but it did
by mistake.
(merge 98b406f jk/remote-pushremote-config-reading later to maint).
- * Codepaths that parse timestamps in commit objects have been
+ * Code paths that parse timestamps in commit objects have been
tightened.
(merge f80d1f9 jk/commit-dates-parsing-fix later to maint).
* "git diff --external-diff" incorrectly fed the submodule directory
- in the working tree to the external diff driver when it knew it is
- the same as one of the versions being compared.
+ in the working tree to the external diff driver when it knew that it
+ is the same as one of the versions being compared.
(merge aba4727 tr/diff-submodule-no-reuse-worktree later to maint).
* "git reset" needs to refresh the index when working in a working
@@ -318,7 +318,7 @@ notes for details).
* "git check-attr" when working on a repository with a working tree
did not work well when the working tree was specified via the
- --work-tree (and obviously with --git-dir) option.
+ "--work-tree" (and obviously with "--git-dir") option.
(merge cdbf623 jc/check-attr-honor-working-tree later to maint).
* "merge-recursive" was broken in 1.7.7 era and stopped working in
@@ -326,12 +326,12 @@ notes for details).
involved. This has been corrected.
(merge 6e2068a bk/refresh-missing-ok-in-merge-recursive later to maint.)
- * "git rev-parse" was loose in rejecting command line arguments
+ * "git rev-parse" was loose in rejecting command-line arguments
that do not make sense, e.g. "--default" without the required
value for that option.
(merge a43219f ds/rev-parse-required-args later to maint.)
- * include.path variable (or any variable that expects a path that
+ * "include.path" variable (or any variable that expects a path that
can use ~username expansion) in the configuration file is not a
boolean, but the code failed to check it.
(merge 67beb60 jk/config-path-include-fix later to maint.)
@@ -340,23 +340,23 @@ notes for details).
the pathspec is given as an absolute pathname (which is a
practice not particularly encouraged) that points at a symbolic
link in the working tree.
- (merge later 655ee9e mw/symlinks to maint.)
+ (merge 6127ff6 mw/symlinks later to maint.)
* "git diff --quiet -- pathspec1 pathspec2" sometimes did not return
- correct status value.
+ the correct status value.
(merge f34b205 nd/diff-quiet-stat-dirty later to maint.)
* Attempting to deepen a shallow repository by fetching over smart
- HTTP transport failed in the protocol exchange, when no-done
+ HTTP transport failed in the protocol exchange, when the no-done
extension was used. The fetching side waited for the list of
- shallow boundary commits after the sending end stopped talking to
+ shallow boundary commits after the sending side stopped talking to
it.
(merge 0232852 nd/http-fetch-shallow-fix later to maint.)
* Allow "git cmd path/", when the 'path' is where a submodule is
bound to the top-level working tree, to match 'path', despite the
extra and unnecessary trailing slash (such a slash is often
- given by command line completion).
+ given by command-line completion).
(merge 2e70c01 nd/submodule-pathspec-ending-with-slash later to maint.)
* Documentation and in-code comments had many instances of mistaken
diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.txt
new file mode 100644
index 0000000..5974734
--- /dev/null
+++ b/Documentation/RelNotes/2.1.0.txt
@@ -0,0 +1,200 @@
+Git v2.1 Release Notes
+======================
+
+Backward compatibility notes
+----------------------------
+
+ * The default value we give to the environment variable LESS has been
+ changed from "FRSX" to "FRX", losing "S" (chop long lines instead
+ of wrapping). Existing users who prefer not to see line-wrapped
+ output may want to set
+
+ $ git config core.pager "less -S"
+
+ to restore the traditional behaviour. It is expected that people
+ find output from the most subcommands easier to read with the new
+ default, except for "blame" which tends to produce really long
+ lines. To override the new default only for "git blame", you can
+ do this:
+
+ $ git config pager.blame "less -S"
+
+ * A few disused directories in contrib/ have been retired.
+
+
+Updates since v2.0
+------------------
+
+UI, Workflows & Features
+
+ * Since the very beginning of Git, we gave the LESS environment a
+ default value "FRSX" when we spawn "less" as the pager. "S" (chop
+ long lines instead of wrapping) has been removed from this default
+ set of options, because it is more or less a personal taste thing,
+ as opposed to others that have good justifications (i.e. "R" is
+ very much justified because many kinds of output we produce are
+ colored and "FX" is justified because output we produce is often
+ shorter than a page).
+
+ * The logic and data used to compute the display width needed for
+ UTF-8 strings have been updated to match Unicode 6.3 better.
+
+ * "git commit --date=<date>" option learned to read from more
+ timestamp formats, including "--date=now".
+
+ * The `core.commentChar` configuration variable is used to specify a
+ custom comment character other than the default "#" to be used in
+ the commit log editor. This can be set to `auto` to attempt to
+ choose a different character that does not conflict with what
+ already starts a line in the message being edited for cases like
+ "git commit --amend".
+
+ * "git grep" learned grep.fullname configuration variable to force
+ "--full-name" to be default. This may cause regressions on
+ scripted users that do not expect this new behaviour.
+
+ * "git imap-send" learned to ask the credential helper for auth
+ material.
+
+ * "git merge" without argument, even when there is an upstream
+ defined for the current branch, refused to run until
+ merge.defaultToUpstream is set to true. Flip the default of that
+ configuration variable to true.
+
+ * "git mergetool" learned to drive the vimdiff3 backend.
+
+ * mergetool.prompt used to default to 'true', always asking "do you
+ really want to run the tool on this path?". Among the two
+ purposes this prompt serves, ignore the use case to confirm that
+ the user wants to view particular path with the named tool, and
+ redefine the meaning of the prompt only to confirm the choice of
+ the tool made by the autodetection (for those who configured the
+ tool explicitly, the prompt shown for the latter purpose is
+ simply annoying).
+
+ Strictly speaking, this is a backward incompatible change and the
+ users need to explicitly set the variable to 'true' if they want
+ to resurrect the now-ignored use case.
+
+ * "git svn" learned to cope with malformed timestamps with only one
+ digit in the hour part, e.g. 2014-01-07T5:01:02.048176Z, emitted
+ by some broken subversion server implementations.
+
+ * "git tag" when editing the tag message shows the name of the tag
+ being edited as a comment in the editor.
+
+
+Performance, Internal Implementation, etc.
+
+ * Build procedure for 'subtree' (in contrib/) has been cleaned up.
+
+ * The `core.deltabasecachelimit` used to default to 16 MiB , but this
+ proved to be too small, and has been bumped to 96 MiB.
+
+ * "git blame" has been optimized greatly by reorganising the data
+ structure that is used to keep track of the work to be done.
+
+ * "git diff" that compares 3-or-more trees (e.g. parents and the
+ result of a merge) have been optimized.
+
+ * The API to update/delete references are being converted to handle
+ updates to multiple references in a transactional way. As an
+ example, "update-ref --stdin [-z]" has been updated to use this
+ API.
+
+
+Also contains various documentation updates and code clean-ups.
+
+
+Fixes since v2.0
+----------------
+
+Unless otherwise noted, all the fixes since v2.0 in the maintenance
+track are contained in this release (see the maintenance releases'
+notes for details).
+
+ * We used to unconditionally disable the pager in the pager process
+ we spawn to feed out output, but that prevented people who want to
+ run "less" within "less" from doing so.
+ (merge c0459ca je/pager-do-not-recurse later to maint).
+
+ * Tools that read diagnostic output in our standard error stream do
+ not want to see terminal control sequence (e.g. erase-to-eol).
+ Detect them by checking if the standard error stream is connected
+ to a tty.
+ (merge 38de156 mn/sideband-no-ansi later to maint).
+
+ * Mishandling of patterns in .gitignore that has trailing SPs quoted
+ with backslashes (e.g. ones that end with "\ ") have been
+ corrected.
+ (merge e61a6c1 pb/trim-trailing-spaces later to maint).
+
+ * "--ignore-space-change" option of "git apply" ignored the spaces
+ at the beginning of line too aggressively, which is inconsistent
+ with the option of the same name "diff" and "git diff" have.
+ (merge 14d3bb4 jc/apply-ignore-whitespace later to maint).
+
+ * "git blame" miscounted number of columns needed to show localized
+ timestamps, resulting in jaggy left-side-edge of the source code
+ lines in its output.
+ (merge dd75553 jx/blame-align-relative-time later to maint).
+
+ * "git blame" assigned the blame to the copy in the working-tree if
+ the repository is set to core.autocrlf=input and the file used CRLF
+ line endings.
+ (merge 4d4813a bc/blame-crlf-test later to maint).
+
+ * "git commit --allow-empty-messag -C $commit" did not work when the
+ commit did not have any log message.
+ (merge 076cbd6 jk/commit-C-pick-empty later to maint).
+
+ * "git grep -O" to show the lines that hit in the pager did not work
+ well with case insensitive search. We now spawn "less" with its
+ "-I" option when it is used as the pager (which is the default).
+ (merge f7febbe sk/spawn-less-case-insensitively-from-grep-O-i later to maint).
+
+ * We used to disable threaded "git index-pack" on platforms without
+ thread-safe pread(); use a different workaround for such
+ platforms to allow threaded "git index-pack".
+ (merge 3953949 nd/index-pack-one-fd-per-thread later to maint).
+
+ * The error reporting from "git index-pack" has been improved to
+ distinguish missing objects from type errors.
+ (merge 77583e7 jk/index-pack-report-missing later to maint).
+
+ * "git mailinfo" used to read beyond the end of header string while
+ parsing an incoming e-mail message to extract the patch.
+ (merge b1a013d rs/mailinfo-header-cmp later to maint).
+
+ * On a case insensitive filesystem, merge-recursive incorrectly
+ deleted the file that is to be renamed to a name that is the same
+ except for case differences.
+ (merge baa37bf dt/merge-recursive-case-insensitive later to maint).
+
+ * "git rerere forget" did not work well when merge.conflictstyle
+ was set to a non-default value.
+ (merge de3d8bb fc/rerere-conflict-style later to maint).
+
+ * "git log --exclude=<glob> --all | git shortlog" worked as expected,
+ but "git shortlog --exclude=<glob> --all", which is supposed to be
+ identical to the above pipeline, was not accepted at the command
+ line argument parser level.
+ (merge eb07774 jc/shortlog-ref-exclude later to maint).
+
+ * "git show -s" (i.e. show log message only) used to incorrectly emit
+ an extra blank line after a merge commit.
+ (merge ad2f725 mk/show-s-no-extra-blank-line-for-merges later to maint).
+
+ * "git status", even though it is a read-only operation, tries to
+ update the index with refreshed lstat(2) info to optimize future
+ accesses to the working tree opportunistically, but this could
+ race with a "read-write" operation that modify the index while it
+ is running. Detect such a race and avoid overwriting the index.
+ (merge 426ddee ym/fix-opportunistic-index-update-race later to maint).
+
+ * "git update-index --cacheinfo" in 2.0 release crashed on a
+ malformed command line.
+ (merge c8e1ee4 jc/rev-parse-argh-dashed-multi-words later to maint).
+
+ * The mode to run tests with HTTP server tests disabled was broken.
+ (merge afa53fe na/no-http-test-in-the-middle later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1932e9b..cd2d651 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -381,7 +381,7 @@ false), while all other repositories are assumed to be bare (bare
core.worktree::
Set the path to the root of the working tree.
This can be overridden by the GIT_WORK_TREE environment
- variable and the '--work-tree' command line option.
+ variable and the '--work-tree' command-line option.
The value can be an absolute path or relative to the path to
the .git directory, which is either specified by --git-dir
or GIT_DIR, or automatically discovered.
@@ -489,7 +489,7 @@ core.deltaBaseCacheLimit::
to avoid unpacking and decompressing frequently used base
objects multiple times.
+
-Default is 16 MiB on all platforms. This should be reasonable
+Default is 96 MiB on all platforms. This should be reasonable
for all users/operating systems, except on the largest projects.
You probably do not need to adjust this value.
+
@@ -523,7 +523,7 @@ core.askpass::
environment variable. If not set, fall back to the value of the
'SSH_ASKPASS' environment variable or, failing that, a simple password
prompt. The external program shall be given a suitable prompt as
- command line argument and write the password on its STDOUT.
+ command-line argument and write the password on its STDOUT.
core.attributesfile::
In addition to '.gitattributes' (per-directory) and
@@ -544,6 +544,9 @@ core.commentchar::
messages consider a line that begins with this character
commented, and removes them after the editor returns
(default '#').
++
+If set to "auto", `git-commit` would select a character that is not
+the beginning character of any line in existing commit messages.
sequence.editor::
Text editor used by `git rebase -i` for editing the rebase instruction file.
@@ -558,14 +561,19 @@ core.pager::
configuration, then `$PAGER`, and then the default chosen at
compile time (usually 'less').
+
-When the `LESS` environment variable is unset, Git sets it to `FRSX`
+When the `LESS` environment variable is unset, Git sets it to `FRX`
(if `LESS` environment variable is set, Git does not change it at
all). If you want to selectively override Git's default setting
-for `LESS`, you can set `core.pager` to e.g. `less -+S`. This will
+for `LESS`, you can set `core.pager` to e.g. `less -S`. This will
be passed to the shell by Git, which will translate the final
-command to `LESS=FRSX less -+S`. The environment tells the command
-to set the `S` option to chop long lines but the command line
-resets it to the default to fold long lines.
+command to `LESS=FRX less -S`. The environment does not set the
+`S` option but the command line does, instructing less to truncate
+long lines. Similarly, setting `core.pager` to `less -+F` will
+deactivate the `F` option specified by the environment from the
+command-line, deactivating the "quit if one screen" behavior of
+`less`. One can specifically activate some flags for particular
+commands: for example, setting `pager.blame` to `less -S` enables
+line truncation only for `git blame`.
+
Likewise, when the `LV` environment variable is unset, Git sets it
to `-c`. You can override this setting by exporting `LV` with
@@ -1324,7 +1332,7 @@ grep.extendedRegexp::
gpg.program::
Use this custom program instead of "gpg" found on $PATH when
making or verifying a PGP signature. The program must support the
- same command line interface as GPG, namely, to verify a detached
+ same command-line interface as GPG, namely, to verify a detached
signature, "gpg --verify $file - <$signature" is run, and the
program is expected to signal a good signature by exiting with
code 0, and to generate an ascii-armored detached signature, the
@@ -2295,7 +2303,7 @@ status.submodulesummary::
submodules when `diff.ignoreSubmodules` is set to 'all' or only
for those submodules where `submodule.<name>.ignore=all`. To
also view the summary for ignored submodules you can either use
- the --ignore-submodules=dirty command line option or the 'git
+ the --ignore-submodules=dirty command-line option or the 'git
submodule summary' command, which shows a similar output but does
not honor these settings.
@@ -2317,7 +2325,7 @@ submodule.<name>.branch::
submodule.<name>.fetchRecurseSubmodules::
This option can be used to control recursive fetching of this
submodule. It can be overridden by using the --[no-]recurse-submodules
- command line option to "git fetch" and "git pull".
+ command-line option to "git fetch" and "git pull".
This setting will override that from in the linkgit:gitmodules[5]
file.
diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index f07b451..b001779 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -76,7 +76,7 @@ diff.ignoreSubmodules::
this setting when reporting uncommitted changes. Setting it to
'all' disables the submodule summary normally shown by 'git commit'
and 'git status' when 'status.submodulesummary' is set unless it is
- overridden by using the --ignore-submodules command line option.
+ overridden by using the --ignore-submodules command-line option.
The 'git submodule' commands are not affected by this setting.
diff.mnemonicprefix::
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index f986c5c..4cb52a7 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -117,7 +117,7 @@ $ git bisect visualize
`view` may also be used as a synonym for `visualize`.
If the 'DISPLAY' environment variable is not set, 'git log' is used
-instead. You can also give command line options such as `-p` and
+instead. You can also give command-line options such as `-p` and
`--stat`.
------------
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index e9917b8..9dfa1a5 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -256,7 +256,7 @@ All writing options will per default write to the repository specific
configuration file. Note that this also affects options like '--replace-all'
and '--unset'. *'git config' will only ever change one file at a time*.
-You can override these rules either by command line options or by environment
+You can override these rules either by command-line options or by environment
variables. The '--global' and the '--system' options will limit the file used
to the global or system-wide file respectively. The GIT_CONFIG environment
variable has a similar effect, but you can specify any filename you want.
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 223f731..a69b361 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -169,7 +169,7 @@ Git configuration files in that directory are readable by `<user>`.
--forbid-override=<service>::
Allow/forbid overriding the site-wide default with per
repository configuration. By default, all the services
- are overridable.
+ may be overridden.
--[no-]informative-errors::
When informative errors are turned on, git-daemon will report
@@ -184,7 +184,7 @@ Git configuration files in that directory are readable by `<user>`.
Every time a client connects, first run an external command
specified by the <path> with service name (e.g. "upload-pack"),
path to the repository, hostname (%H), canonical hostname
- (%CH), ip address (%IP), and tcp port (%P) as its command line
+ (%CH), IP address (%IP), and TCP port (%P) as its command-line
arguments. The external command can decide to decline the
service by exiting with a non-zero status (or to allow it by
exiting with a zero status). It can also look at the $REMOTE_ADDR
@@ -204,7 +204,7 @@ SERVICES
--------
These services can be globally enabled/disabled using the
-command line options of this command. If a finer-grained
+command-line options of this command. If finer-grained
control is desired (e.g. to allow 'git archive' to be run
against only in a few selected repositories the daemon serves),
the per-repository configuration file can be used to enable or
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index fd22a9a..3ffa2fa 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -231,7 +231,7 @@ Date Formats
~~~~~~~~~~~~
The following date formats are supported. A frontend should select
the format it will use for this import by passing the format name
-in the \--date-format=<fmt> command line option.
+in the \--date-format=<fmt> command-line option.
`raw`::
This is the Git native format and is `<time> SP <offutc>`.
@@ -348,7 +348,7 @@ and control the current import process. More detailed discussion
`done`::
Marks the end of the stream. This command is optional
unless the `done` feature was requested using the
- `--done` command line option or `feature done` command.
+ `--done` command-line option or `feature done` command.
`cat-blob`::
Causes fast-import to print a blob in 'cat-file --batch'
@@ -437,7 +437,7 @@ the email address from the other fields in the line. Note that
of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded.
The time of the change is specified by `<when>` using the date format
-that was selected by the \--date-format=<fmt> command line option.
+that was selected by the \--date-format=<fmt> command-line option.
See ``Date Formats'' above for the set of supported formats, and
their syntax.
@@ -1085,7 +1085,7 @@ Option commands must be the first commands on the input (not counting
feature commands), to give an option command after any non-option
command is an error.
-The following commandline options change import semantics and may therefore
+The following command-line options change import semantics and may therefore
not be passed as option:
* date-format
@@ -1099,7 +1099,7 @@ not be passed as option:
If the `done` feature is not in use, treated as if EOF was read.
This can be used to tell fast-import to finish early.
-If the `--done` command line option or `feature done` command is
+If the `--done` command-line option or `feature done` command is
in use, the `done` command is mandatory and marks the end of the
stream.
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index f837334..31811f1 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -53,6 +53,9 @@ grep.extendedRegexp::
option is ignored when the 'grep.patternType' option is set to a value
other than 'default'.
+grep.fullName::
+ If set to true, enable '--full-name' option by default.
+
OPTIONS
-------
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index b21e9d7..3956525 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -80,9 +80,9 @@ CONFIGURATION VARIABLES
help.format
~~~~~~~~~~~
-If no command line option is passed, the 'help.format' configuration
+If no command-line option is passed, the 'help.format' configuration
variable will be checked. The following values are supported for this
-variable; they make 'git help' behave as their corresponding command
+variable; they make 'git help' behave as their corresponding command-
line option:
* "man" corresponds to '-m|--man',
@@ -93,15 +93,15 @@ help.browser, web.browser and browser.<tool>.path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also
-be checked if the 'web' format is chosen (either by command line
+be checked if the 'web' format is chosen (either by command-line
option or configuration variable). See '-w|--web' in the OPTIONS
section above and linkgit:git-web{litdd}browse[1].
man.viewer
~~~~~~~~~~
-The 'man.viewer' config variable will be checked if the 'man' format
-is chosen. The following values are currently supported:
+The 'man.viewer' configuration variable will be checked if the 'man'
+format is chosen. The following values are currently supported:
* "man": use the 'man' program as usual,
* "woman": use 'emacsclient' to launch the "woman" mode in emacs
@@ -124,7 +124,7 @@ For example, this configuration:
viewer = woman
------------------------------------------------
-will try to use konqueror first. But this may fail (for example if
+will try to use konqueror first. But this may fail (for example, if
DISPLAY is not set) and in that case emacs' woman mode will be tried.
If everything fails, or if no viewer is configured, the viewer specified
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index c0856a6..e26f01f 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -185,15 +185,15 @@ specifies the format of exclude patterns.
These exclude patterns come from these places, in order:
- 1. The command line flag --exclude=<pattern> specifies a
+ 1. The command-line flag --exclude=<pattern> specifies a
single pattern. Patterns are ordered in the same order
they appear in the command line.
- 2. The command line flag --exclude-from=<file> specifies a
+ 2. The command-line flag --exclude-from=<file> specifies a
file containing a list of patterns. Patterns are ordered
in the same order they appear in the file.
- 3. The command line flag --exclude-per-directory=<name> specifies
+ 3. The command-line flag --exclude-per-directory=<name> specifies
a name of the file in each directory 'git ls-files'
examines, normally `.gitignore`. Files in deeper
directories take precedence. Patterns are ordered in the
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index a3c1fa3..cf2c374 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -101,9 +101,8 @@ commit or stash your changes before running 'git merge'.
Specifying more than one commit will create a merge with
more than two parents (affectionately called an Octopus merge).
+
-If no commit is given from the command line, and if `merge.defaultToUpstream`
-configuration variable is set, merge the remote-tracking branches
-that the current branch is configured to use as its upstream.
+If no commit is given from the command line, merge the remote-tracking
+branches that the current branch is configured to use as its upstream.
See also the configuration section of this manual page.
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index 07137f2..e846c2e 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -71,11 +71,13 @@ success of the resolution after the custom tool has exited.
--no-prompt::
Don't prompt before each invocation of the merge resolution
program.
+ This is the default if the merge resolution program is
+ explicitly specified with the `--tool` option or with the
+ `merge.tool` configuration variable.
--prompt::
- Prompt before each invocation of the merge resolution program.
- This is the default behaviour; the option is provided to
- override any configuration settings.
+ Prompt before each invocation of the merge resolution program
+ to give the user a chance to skip the path.
TEMPORARY FILES
---------------
diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
index 312c3b1..31efc58 100644
--- a/Documentation/git-patch-id.txt
+++ b/Documentation/git-patch-id.txt
@@ -8,14 +8,14 @@ git-patch-id - Compute unique ID for a patch
SYNOPSIS
--------
[verse]
-'git patch-id' < <patch>
+'git patch-id' [--stable | --unstable] < <patch>
DESCRIPTION
-----------
-A "patch ID" is nothing but a SHA-1 of the diff associated with a patch, with
-whitespace and line numbers ignored. As such, it's "reasonably stable", but at
-the same time also reasonably unique, i.e., two patches that have the same "patch
-ID" are almost guaranteed to be the same thing.
+A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a
+patch, with whitespace and line numbers ignored. As such, it's "reasonably
+stable", but at the same time also reasonably unique, i.e., two patches that
+have the same "patch ID" are almost guaranteed to be the same thing.
IOW, you can use this thing to look for likely duplicate commits.
@@ -27,6 +27,33 @@ This can be used to make a mapping from patch ID to commit ID.
OPTIONS
-------
+
+--stable::
+ Use a "stable" sum of hashes as the patch ID. With this option:
+ - Reordering file diffs that make up a patch does not affect the ID.
+ In particular, two patches produced by comparing the same two trees
+ with two different settings for "-O<orderfile>" result in the same
+ patch ID signature, thereby allowing the computed result to be used
+ as a key to index some meta-information about the change between
+ the two trees;
+
+ - Result is different from the value produced by git 1.9 and older
+ or produced when an "unstable" hash (see --unstable below) is
+ configured - even when used on a diff output taken without any use
+ of "-O<orderfile>", thereby making existing databases storing such
+ "unstable" or historical patch-ids unusable.
+
+ This is the default if patchid.stable is set to true.
+
+--unstable::
+ Use an "unstable" hash as the patch ID. With this option,
+ the result produced is compatible with the patch-id value produced
+ by git 1.9 and older. Users with pre-existing databases storing
+ patch-ids produced by git 1.9 and older (who do not deal with reordered
+ patches) may want to use this option.
+
+ This is the default.
+
<patch>::
The diff to create the ID of.
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 056c0db..fa1d557 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -283,7 +283,7 @@ merge. The different stages represent the "result tree" (stage 0, aka
you are trying to merge (stage 2 and 3 respectively).
The order of stages 1, 2 and 3 (hence the order of three
-<tree-ish> command line arguments) are significant when you
+<tree-ish> command-line arguments) are significant when you
start a 3-way merge with an index file that is already
populated. Here is an outline of how the algorithm works:
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index 0a02f70..61461b9 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -9,6 +9,7 @@ SYNOPSIS
--------
[verse]
'git replace' [-f] <object> <replacement>
+'git replace' [-f] --edit <object>
'git replace' -d <object>...
'git replace' [--format=<format>] [-l [<pattern>]]
@@ -63,6 +64,15 @@ OPTIONS
--delete::
Delete existing replace refs for the given objects.
+--edit <object>::
+ Edit an object's content interactively. The existing content
+ for <object> is pretty-printed into a temporary file, an
+ editor is launched on the file, and the result is parsed to
+ create a new object of the same type as <object>. A
+ replacement ref is then created to replace <object> with the
+ newly created object. See linkgit:git-var[1] for details about
+ how the editor will be chosen.
+
-l <pattern>::
--list <pattern>::
List replace refs for objects that match the given pattern (or
@@ -92,7 +102,9 @@ CREATING REPLACEMENT OBJECTS
linkgit:git-filter-branch[1], linkgit:git-hash-object[1] and
linkgit:git-rebase[1], among other git commands, can be used to create
-replacement objects from existing objects.
+replacement objects from existing objects. The `--edit` option can
+also be used with 'git replace' to create a replacement object by
+editing an existing object.
If you want to replace many blobs, trees or commits that are part of a
string of commits, you may just want to create a replacement string of
@@ -117,6 +129,8 @@ linkgit:git-filter-branch[1]
linkgit:git-rebase[1]
linkgit:git-tag[1]
linkgit:git-branch[1]
+linkgit:git-commit[1]
+linkgit:git-var[1]
linkgit:git[1]
GIT
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index f0e57a5..d0fa18a 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -20,7 +20,7 @@ files in the directory), or directly as a revision list. In the
last case, any format accepted by linkgit:git-format-patch[1] can
be passed to git send-email.
-The header of the email is configurable by command line options. If not
+The header of the email is configurable via command-line options. If not
specified on the command line, the user will be prompted with a ReadLine
enabled interface to provide the necessary information.
@@ -68,7 +68,7 @@ The --cc option must be repeated for each user you want on the cc list.
When '--compose' is used, git send-email will use the From, Subject, and
In-Reply-To headers specified in the message. If the body of the message
(what you type after the headers and a blank line) only contains blank
-(or Git: prefixed) lines the summary won't be sent, but From, Subject,
+(or Git: prefixed) lines, the summary won't be sent, but From, Subject,
and In-Reply-To headers will be used unless they are removed.
+
Missing From or In-Reply-To headers will be prompted for.
@@ -78,7 +78,7 @@ See the CONFIGURATION section for 'sendemail.multiedit'.
--from=<address>::
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
+ 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".
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index fce5853..44c970c 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -148,8 +148,8 @@ the same local time zone.
[verse]
config key: svn-remote.<name>.ignore-paths
+
-If the ignore-paths config key is set and the command line option is
-also given, both regular expressions will be used.
+If the ignore-paths configuration key is set, and the command-line
+option is also given, both regular expressions will be used.
+
Examples:
+
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index 0a0a551..c8f5ae5 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -68,7 +68,12 @@ performs all modifications together. Specify commands of the form:
option SP <opt> LF
Quote fields containing whitespace as if they were strings in C source
-code. Alternatively, use `-z` to specify commands without quoting:
+code; i.e., surrounded by double-quotes and with backslash escapes.
+Use 40 "0" characters or the empty string to specify a zero value. To
+specify a missing value, omit the value and its preceding SP entirely.
+
+Alternatively, use `-z` to specify in NUL-terminated format, without
+quoting:
update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL
create SP <ref> NUL <newvalue> NUL
@@ -76,8 +81,12 @@ code. Alternatively, use `-z` to specify commands without quoting:
verify SP <ref> NUL [<oldvalue>] NUL
option SP <opt> NUL
-Lines of any other format or a repeated <ref> produce an error.
-Command meanings are:
+In this format, use 40 "0" to specify a zero value, and use the empty
+string to specify a missing value.
+
+In either format, values can be specified in any form that Git
+recognizes as an object name. Commands in any other format or a
+repeated <ref> produce an error. Command meanings are:
update::
Set <ref> to <newvalue> after verifying <oldvalue>, if given.
@@ -102,9 +111,6 @@ option::
The only valid option is `no-deref` to avoid dereferencing
a symbolic ref.
-Use 40 "0" or the empty string to specify a zero value, except that
-with `-z` an empty <oldvalue> is considered missing.
-
If all <ref>s can be locked with matching <oldvalue>s
simultaneously, all modifications are performed. Otherwise, no
modifications are performed. Note that while each individual
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index 2de575f..16ede5b 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -62,7 +62,7 @@ CONF.VAR (from -c option) and web.browser
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The web browser can be specified using a configuration variable passed
-with the -c (or --config) command line option, or the 'web.browser'
+with the -c (or --config) command-line option, or the 'web.browser'
configuration variable if the former is not used.
browser.<tool>.path
@@ -87,7 +87,7 @@ the URLs passed as arguments.
Note about konqueror
--------------------
-When 'konqueror' is specified by a command line option or a
+When 'konqueror' is specified by a command-line option or a
configuration variable, we launch 'kfmclient' to try to open the HTML
man page on an already opened konqueror in a new tab if possible.
diff --git a/Documentation/git.txt b/Documentation/git.txt
index a041cd0..3bd68b0 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -29,7 +29,7 @@ in-depth introduction.
After you mastered the basic concepts, you can come back to this
page to learn what commands Git offers. You can learn more about
individual Git commands with "git help command". linkgit:gitcli[7]
-manual page gives you an overview of the command line command syntax.
+manual page gives you an overview of the command-line command syntax.
Formatted and hyperlinked version of the latest Git documentation
can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
@@ -39,13 +39,19 @@ ifdef::stalenotes[]
============
You are reading the documentation for the latest (possibly
-unreleased) version of Git, that is available from 'master'
+unreleased) version of Git, that is available from the 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v1.9.3/git.html[documentation for release 1.9.3]
+* link:v2.0.0/git.html[documentation for release 2.0]
* release notes for
+ link:RelNotes/2.0.0.txt[2.0.0].
+
+* link:v1.9.4/git.html[documentation for release 1.9.4]
+
+* release notes for
+ link:RelNotes/1.9.4.txt[1.9.4],
link:RelNotes/1.9.3.txt[1.9.3],
link:RelNotes/1.9.2.txt[1.9.2],
link:RelNotes/1.9.1.txt[1.9.1],
@@ -749,7 +755,7 @@ Git so take care if using Cogito etc.
'GIT_WORK_TREE'::
Set the path to the root of the working tree.
- This can also be controlled by the '--work-tree' command line
+ This can also be controlled by the '--work-tree' command-line
option and the core.worktree configuration variable.
'GIT_NAMESPACE'::
@@ -874,7 +880,7 @@ for further details.
'GIT_ASKPASS'::
If this environment variable is set, then Git commands which need to
acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
- will call this program with a suitable prompt as command line argument
+ will call this program with a suitable prompt as command-line argument
and read the password from its STDOUT. See also the 'core.askpass'
option in linkgit:git-config[1].
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 1c3e109..dfe7d83 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -3,7 +3,7 @@ gitcli(7)
NAME
----
-gitcli - Git command line interface and conventions
+gitcli - Git command-line interface and conventions
SYNOPSIS
--------
@@ -66,13 +66,13 @@ you will.
Here are the rules regarding the "flags" that you should follow when you are
scripting Git:
- * it's preferred to use the non dashed form of Git commands, which means that
+ * it's preferred to use the non-dashed form of Git commands, which means that
you should prefer `git foo` to `git-foo`.
* splitting short options to separate words (prefer `git foo -a -b`
to `git foo -ab`, the latter may not even work).
- * when a command line option takes an argument, use the 'stuck' form. In
+ * when a command-line option takes an argument, use the 'stuck' form. In
other words, write `git foo -oArg` instead of `git foo -o Arg` for short
options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg`
for long options. An option that takes optional option-argument must be
@@ -103,7 +103,7 @@ Here is a list of the facilities provided by this option parser.
Magic Options
~~~~~~~~~~~~~
Commands which have the enhanced option parser activated all understand a
-couple of magic command line options:
+couple of magic command-line options:
-h::
gives a pretty printed usage of the command.
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 7e03fcc..7ae50aa 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -27,7 +27,7 @@ gitk-specific options.
gitk generally only understands options with arguments in the
'sticked' form (see linkgit:gitcli[7]) due to limitations in the
-command line parser.
+command-line parser.
rev-list options and arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 952f503..ebe7a6c 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -904,7 +904,7 @@ the following in your GITWEB_CONFIG file:
$feature{'snapshot'}{'override'} = 1;
If you allow overriding for the snapshot feature, you can specify which
-snapshot formats are globally disabled. You can also add any command line
+snapshot formats are globally disabled. You can also add any command-line
options you want (such as setting the compression level). For instance, you
can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by
adding the following lines to your gitweb configuration file:
diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt
new file mode 100644
index 0000000..35d48ef
--- /dev/null
+++ b/Documentation/howto/keep-canonical-history-correct.txt
@@ -0,0 +1,216 @@
+From: Junio C Hamano <gitster@pobox.com>
+Date: Wed, 07 May 2014 13:15:39 -0700
+Subject: Beginner question on "Pull is mostly evil"
+Abstract: This how-to explains a method for keeping a
+ project's history correct when using git pull.
+Content-type: text/asciidoc
+
+Keep authoritative canonical history correct with git pull
+==========================================================
+
+Sometimes a new project integrator will end up with project history
+that appears to be "backwards" from what other project developers
+expect. This howto presents a suggested integration workflow for
+maintaining a central repository.
+
+Suppose that that central repository has this history:
+
+------------
+ ---o---o---A
+------------
+
+which ends at commit `A` (time flows from left to right and each node
+in the graph is a commit, lines between them indicating parent-child
+relationship).
+
+Then you clone it and work on your own commits, which leads you to
+have this history in *your* repository:
+
+------------
+ ---o---o---A---B---C
+------------
+
+Imagine your coworker did the same and built on top of `A` in *his*
+repository in the meantime, and then pushed it to the
+central repository:
+
+------------
+ ---o---o---A---X---Y---Z
+------------
+
+Now, if you `git push` at this point, because your history that leads
+to `C` lacks `X`, `Y` and `Z`, it will fail. You need to somehow make
+the tip of your history a descendant of `Z`.
+
+One suggested way to solve the problem is "fetch and then merge", aka
+`git pull`. When you fetch, your repository will have a history like
+this:
+
+------------
+ ---o---o---A---B---C
+ \
+ X---Y---Z
+------------
+
+Once you run merge after that, while still on *your* branch, i.e. `C`,
+you will create a merge `M` and make the history look like this:
+
+------------
+ ---o---o---A---B---C---M
+ \ /
+ X---Y---Z
+------------
+
+`M` is a descendant of `Z`, so you can push to update the central
+repository. Such a merge `M` does not lose any commit in both
+histories, so in that sense it may not be wrong, but when people want
+to talk about "the authoritative canonical history that is shared
+among the project participants", i.e. "the trunk", they often view
+it as "commits you see by following the first-parent chain", and use
+this command to view it:
+
+------------
+ $ git log --first-parent
+------------
+
+For all other people who observed the central repository after your
+coworker pushed `Z` but before you pushed `M`, the commit on the trunk
+used to be `o-o-A-X-Y-Z`. But because you made `M` while you were on
+`C`, `M`'s first parent is `C`, so by pushing `M` to advance the
+central repository, you made `X-Y-Z` a side branch, not on the trunk.
+
+You would rather want to have a history of this shape:
+
+------------
+ ---o---o---A---X---Y---Z---M'
+ \ /
+ B-----------C
+------------
+
+so that in the first-parent chain, it is clear that the project first
+did `X` and then `Y` and then `Z` and merged a change that consists of
+two commits `B` and `C` that achieves a single goal. You may have
+worked on fixing the bug #12345 with these two patches, and the merge
+`M'` with swapped parents can say in its log message "Merge
+fix-bug-12345". Having a way to tell `git pull` to create a merge
+but record the parents in reverse order may be a way to do so.
+
+Note that I said "achieves a single goal" above, because this is
+important. "Swapping the merge order" only covers a special case
+where the project does not care too much about having unrelated
+things done on a single merge but cares a lot about first-parent
+chain.
+
+There are multiple schools of thought about the "trunk" management.
+
+ 1. Some projects want to keep a completely linear history without any
+ merges. Obviously, swapping the merge order would not match their
+ taste. You would need to flatten your history on top of the
+ updated upstream to result in a history of this shape instead:
++
+------------
+ ---o---o---A---X---Y---Z---B---C
+------------
++
+with `git pull --rebase` or something.
+
+ 2. Some projects tolerate merges in their history, but do not worry
+ too much about the first-parent order, and allow fast-forward
+ merges. To them, swapping the merge order does not hurt, but
+ it is unnecessary.
+
+ 3. Some projects want each commit on the "trunk" to do one single
+ thing. The output of `git log --first-parent` in such a project
+ would show either a merge of a side branch that completes a single
+ theme, or a single commit that completes a single theme by itself.
+ If your two commits `B` and `C` (or they may even be two groups of
+ commits) were solving two independent issues, then the merge `M'`
+ we made in the earlier example by swapping the merge order is
+ still not up to the project standard. It merges two unrelated
+ efforts `B` and `C` at the same time.
+
+For projects in the last category (Git itself is one of them),
+individual developers would want to prepare a history more like
+this:
+
+------------
+ C0--C1--C2 topic-c
+ /
+ ---o---o---A master
+ \
+ B0--B1--B2 topic-b
+------------
+
+That is, keeping separate topics on separate branches, perhaps like
+so:
+
+------------
+ $ git clone $URL work && cd work
+ $ git checkout -b topic-b master
+ $ ... work to create B0, B1 and B2 to complete one theme
+ $ git checkout -b topic-c master
+ $ ... same for the theme of topic-c
+------------
+
+And then
+
+------------
+ $ git checkout master
+ $ git pull --ff-only
+------------
+
+would grab `X`, `Y` and `Z` from the upstream and advance your master
+branch:
+
+------------
+ C0--C1--C2 topic-c
+ /
+ ---o---o---A---X---Y---Z master
+ \
+ B0--B1--B2 topic-b
+------------
+
+And then you would merge these two branches separately:
+
+------------
+ $ git merge topic-b
+ $ git merge topic-c
+------------
+
+to result in
+
+------------
+ C0--C1---------C2
+ / \
+ ---o---o---A---X---Y---Z---M---N
+ \ /
+ B0--B1-----B2
+------------
+
+and push it back to the central repository.
+
+It is very much possible that while you are merging topic-b and
+topic-c, somebody again advanced the history in the central repository
+to put `W` on top of `Z`, and make your `git push` fail.
+
+In such a case, you would rewind to discard `M` and `N`, update the
+tip of your 'master' again and redo the two merges:
+
+------------
+ $ git reset --hard origin/master
+ $ git pull --ff-only
+ $ git merge topic-b
+ $ git merge topic-c
+------------
+
+The procedure will result in a history that looks like this:
+
+------------
+ C0--C1--------------C2
+ / \
+ ---o---o---A---X---Y---Z---W---M'--N'
+ \ /
+ B0--B1---------B2
+------------
+
+See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt
index 6de4f3c..f44e5e9 100644
--- a/Documentation/howto/setup-git-server-over-http.txt
+++ b/Documentation/howto/setup-git-server-over-http.txt
@@ -181,7 +181,7 @@ On Debian:
Most tests should pass.
-A command line tool to test WebDAV is cadaver. If you prefer GUIs, for
+A command-line tool to test WebDAV is cadaver. If you prefer GUIs, for
example, konqueror can open WebDAV URLs as "webdav://..." or
"webdavs://...".
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 5a286d0..0796118 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -94,7 +94,9 @@ some output processing may assume ref names in UTF-8.
'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}')
refers to the branch that the branch specified by branchname is set to build on
- top of. A missing branchname defaults to the current one.
+ top of (configured with `branch.<name>.remote` and
+ `branch.<name>.merge`). A missing branchname defaults to the
+ current one.
'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
A suffix '{caret}' to a revision parameter means the first parent of
diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt
index e3d6e7a..22a39b9 100644
--- a/Documentation/technical/api-builtin.txt
+++ b/Documentation/technical/api-builtin.txt
@@ -22,11 +22,14 @@ Git:
where options is the bitwise-or of:
`RUN_SETUP`::
-
- Make sure there is a Git directory to work on, and if there is a
- work tree, chdir to the top of it if the command was invoked
- in a subdirectory. If there is no work tree, no chdir() is
- done.
+ If there is not a Git directory to work on, abort. If there
+ is a work tree, chdir to the top of it if the command was
+ invoked in a subdirectory. If there is no work tree, no
+ chdir() is done.
+
+`RUN_SETUP_GENTLY`::
+ If there is a Git directory, chdir as per RUN_SETUP, otherwise,
+ don't chdir anywhere.
`USE_PAGER`::
diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt
index 42ca234..b977ae8 100644
--- a/Documentation/technical/api-hashmap.txt
+++ b/Documentation/technical/api-hashmap.txt
@@ -166,7 +166,6 @@ Usage example
-------------
Here's a simple usage example that maps long keys to double values.
-[source,c]
------------
struct hashmap map;
diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt
index 3350d97..4396be9 100644
--- a/Documentation/technical/api-strbuf.txt
+++ b/Documentation/technical/api-strbuf.txt
@@ -121,10 +121,19 @@ Functions
* Related to the contents of the buffer
+`strbuf_trim`::
+
+ Strip whitespace from the beginning and end of a string.
+ Equivalent to performing `strbuf_rtrim()` followed by `strbuf_ltrim()`.
+
`strbuf_rtrim`::
Strip whitespace from the end of a string.
+`strbuf_ltrim`::
+
+ Strip whitespace from the beginning of a string.
+
`strbuf_cmp`::
Compare two buffers. Returns an integer less than, equal to, or greater
diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
index 20525d9..59be59b 100644
--- a/Documentation/technical/http-protocol.txt
+++ b/Documentation/technical/http-protocol.txt
@@ -374,7 +374,7 @@ C: Send one `$GIT_URL/git-upload-pack` request:
C: 0000
The stream is organized into "commands", with each command
-appearing by itself in a pkt-line. Within a command line
+appearing by itself in a pkt-line. Within a command line,
the text leading up to the first space is the command name,
and the remainder of the line to the first LF is the value.
Command lines are terminated with an LF as the last byte of
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 022e74e..d33f884 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -4231,9 +4231,9 @@ Most of what `git rev-list` did is contained in `revision.c` and
controls how and what revisions are walked, and more.
The original job of `git rev-parse` is now taken by the function
-`setup_revisions()`, which parses the revisions and the common command line
+`setup_revisions()`, which parses the revisions and the common command-line
options for the revision walker. This information is stored in the struct
-`rev_info` for later consumption. You can do your own command line option
+`rev_info` for later consumption. You can do your own command-line option
parsing after calling `setup_revisions()`. After that, you have to call
`prepare_revision_walk()` for initialization, and then you can get the
commits one by one with the function `get_revision()`.