summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingGuidelines5
-rw-r--r--Documentation/Makefile1
-rw-r--r--Documentation/RelNotes/2.10.0.txt590
-rw-r--r--Documentation/RelNotes/2.10.1.txt120
-rw-r--r--Documentation/RelNotes/2.11.0.txt298
-rw-r--r--Documentation/RelNotes/2.3.10.txt2
-rw-r--r--Documentation/RelNotes/2.4.10.txt2
-rw-r--r--Documentation/RelNotes/2.5.4.txt2
-rw-r--r--Documentation/RelNotes/2.6.1.txt2
-rw-r--r--Documentation/RelNotes/2.9.1.txt89
-rw-r--r--Documentation/RelNotes/2.9.2.txt13
-rw-r--r--Documentation/RelNotes/2.9.3.txt170
-rw-r--r--Documentation/RelNotes/2.9.4.txt83
-rw-r--r--Documentation/SubmittingPatches10
-rw-r--r--Documentation/config.txt194
-rw-r--r--Documentation/diff-config.txt11
-rw-r--r--Documentation/diff-format.txt8
-rw-r--r--Documentation/diff-generate-patch.txt6
-rw-r--r--Documentation/diff-options.txt23
-rw-r--r--Documentation/fetch-options.txt6
-rw-r--r--Documentation/git-add.txt7
-rw-r--r--Documentation/git-am.txt7
-rw-r--r--Documentation/git-bisect.txt2
-rw-r--r--Documentation/git-branch.txt6
-rw-r--r--Documentation/git-cat-file.txt50
-rw-r--r--Documentation/git-check-ref-format.txt4
-rw-r--r--Documentation/git-checkout.txt16
-rw-r--r--Documentation/git-cherry-pick.txt2
-rw-r--r--Documentation/git-clean.txt2
-rw-r--r--Documentation/git-clone.txt10
-rw-r--r--Documentation/git-commit-tree.txt2
-rw-r--r--Documentation/git-commit.txt4
-rw-r--r--Documentation/git-config.txt31
-rw-r--r--Documentation/git-credential-store.txt2
-rw-r--r--Documentation/git-cvsimport.txt14
-rw-r--r--Documentation/git-cvsserver.txt12
-rw-r--r--Documentation/git-daemon.txt8
-rw-r--r--Documentation/git-describe.txt2
-rw-r--r--Documentation/git-diff-index.txt4
-rw-r--r--Documentation/git-diff-tree.txt20
-rw-r--r--Documentation/git-difftool.txt2
-rw-r--r--Documentation/git-fast-import.txt4
-rw-r--r--Documentation/git-fetch-pack.txt4
-rw-r--r--Documentation/git-fetch.txt51
-rw-r--r--Documentation/git-filter-branch.txt6
-rw-r--r--Documentation/git-for-each-ref.txt2
-rw-r--r--Documentation/git-format-patch.txt8
-rw-r--r--Documentation/git-fsck.txt11
-rw-r--r--Documentation/git-grep.txt10
-rw-r--r--Documentation/git-gui.txt2
-rw-r--r--Documentation/git-help.txt6
-rw-r--r--Documentation/git-http-push.txt4
-rw-r--r--Documentation/git-index-pack.txt2
-rw-r--r--Documentation/git-interpret-trailers.txt2
-rw-r--r--Documentation/git-log.txt4
-rw-r--r--Documentation/git-ls-files.txt5
-rw-r--r--Documentation/git-ls-tree.txt8
-rw-r--r--Documentation/git-mailsplit.txt7
-rw-r--r--Documentation/git-mktree.txt2
-rw-r--r--Documentation/git-mv.txt4
-rw-r--r--Documentation/git-notes.txt2
-rw-r--r--Documentation/git-p4.txt22
-rw-r--r--Documentation/git-pack-objects.txt4
-rw-r--r--Documentation/git-push.txt15
-rw-r--r--Documentation/git-rebase.txt10
-rw-r--r--Documentation/git-receive-pack.txt3
-rw-r--r--Documentation/git-remote-fd.txt2
-rw-r--r--Documentation/git-remote.txt10
-rw-r--r--Documentation/git-repack.txt23
-rw-r--r--Documentation/git-revert.txt4
-rw-r--r--Documentation/git-send-email.txt24
-rw-r--r--Documentation/git-send-pack.txt10
-rw-r--r--Documentation/git-shell.txt4
-rw-r--r--Documentation/git-show-branch.txt2
-rw-r--r--Documentation/git-show-ref.txt6
-rw-r--r--Documentation/git-status.txt133
-rw-r--r--Documentation/git-svn.txt29
-rw-r--r--Documentation/git-tag.txt2
-rw-r--r--Documentation/git-unpack-objects.txt3
-rw-r--r--Documentation/git-update-index.txt14
-rw-r--r--Documentation/git-web--browse.txt2
-rw-r--r--Documentation/git-worktree.txt46
-rw-r--r--Documentation/git.txt24
-rw-r--r--Documentation/gitattributes.txt72
-rw-r--r--Documentation/gitcore-tutorial.txt2
-rw-r--r--Documentation/gitcvs-migration.txt6
-rw-r--r--Documentation/gitdiffcore.txt4
-rw-r--r--Documentation/githooks.txt18
-rw-r--r--Documentation/gitk.txt4
-rw-r--r--Documentation/gitmodules.txt7
-rw-r--r--Documentation/gitremote-helpers.txt10
-rw-r--r--Documentation/gitrevisions.txt6
-rw-r--r--Documentation/gitweb.conf.txt21
-rw-r--r--Documentation/howto/new-command.txt2
-rw-r--r--Documentation/pretty-formats.txt12
-rw-r--r--Documentation/rev-list-options.txt50
-rw-r--r--Documentation/revisions.txt151
-rw-r--r--Documentation/technical/api-hashmap.txt5
-rw-r--r--Documentation/technical/pack-protocol.txt12
-rw-r--r--Documentation/technical/protocol-capabilities.txt9
-rw-r--r--Documentation/technical/protocol-common.txt6
-rw-r--r--Documentation/technical/signature-format.txt186
102 files changed, 2493 insertions, 468 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 7f4769a02c..4cd95da6b1 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -527,12 +527,13 @@ Writing Documentation:
or commands:
Literal examples (e.g. use of command-line options, command names,
- configuration and environment variables) must be typeset in monospace (i.e.
- wrapped with backticks):
+ branch names, configuration and environment variables) must be
+ typeset in monospace (i.e. wrapped with backticks):
`--pretty=oneline`
`git rev-list`
`remote.pushDefault`
`GIT_DIR`
+ `HEAD`
An environment variable must be prefixed with "$" only when referring to its
value and not when referring to the variable itself, in this case there is
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 35c1385ef7..b43d66eae6 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -76,6 +76,7 @@ TECH_DOCS += technical/protocol-common
TECH_DOCS += technical/racy-git
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
+TECH_DOCS += technical/signature-format
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.txt
index 63499b7c0e..f4da28ab66 100644
--- a/Documentation/RelNotes/2.10.0.txt
+++ b/Documentation/RelNotes/2.10.0.txt
@@ -28,6 +28,107 @@ UI, Workflows & Features
that they are shown with "remote: " prefix to avoid confusing the
users.
+ * "git add -i/-p" learned to honor diff.compactionHeuristic
+ experimental knob, so that the user can work on the same hunk split
+ as "git diff" output.
+
+ * "upload-pack" allows a custom "git pack-objects" replacement when
+ responding to "fetch/clone" via the uploadpack.packObjectsHook.
+ (merge b738396 jk/upload-pack-hook later to maint).
+
+ * Teach format-patch and mailsplit (hence "am") how a line that
+ happens to begin with "From " in the e-mail message is quoted with
+ ">", so that these lines can be restored to their original shape.
+ (merge d9925d1 ew/mboxrd-format-am later to maint).
+
+ * "git repack" learned the "--keep-unreachable" option, which sends
+ loose unreachable objects to a pack instead of leaving them loose.
+ This helps heuristics based on the number of loose objects
+ (e.g. "gc --auto").
+ (merge e26a8c4 jk/repack-keep-unreachable later to maint).
+
+ * "log --graph --format=" learned that "%>|(N)" specifies the width
+ relative to the terminal's left edge, not relative to the area to
+ draw text that is to the right of the ancestry-graph section. It
+ also now accepts negative N that means the column limit is relative
+ to the right border.
+
+ * A careless invocation of "git send-email directory/" after editing
+ 0001-change.patch with an editor often ends up sending both
+ 0001-change.patch and its backup file, 0001-change.patch~, causing
+ embarrassment and a minor confusion. Detect such an input and
+ offer to skip the backup files when sending the patches out.
+ (merge 531220b jc/send-email-skip-backup later to maint).
+
+ * "git submodule update" that drives many "git clone" could
+ eventually hit flaky servers/network conditions on one of the
+ submodules; the command learned to retry the attempt.
+
+ * The output coloring scheme learned two new attributes, italic and
+ strike, in addition to existing bold, reverse, etc.
+
+ * "git log" learns log.showSignature configuration variable, and a
+ command line option "--no-show-signature" to countermand it.
+ (merge fce04c3 mj/log-show-signature-conf later to maint).
+
+ * More markings of messages for i18n, with updates to various tests
+ to pass GETTEXT_POISON tests.
+
+ * "git archive" learned to handle files that are larger than 8GB and
+ commits far in the future than expressible by the traditional US-TAR
+ format.
+ (merge 560b0e8 jk/big-and-future-archive-tar later to maint).
+
+
+ * A new configuration variable core.sshCommand has been added to
+ specify what value for GIT_SSH_COMMAND to use per repository.
+
+ * "git worktree prune" protected worktrees that are marked as
+ "locked" by creating a file in a known location. "git worktree"
+ command learned a dedicated command pair to create and remove such
+ a file, so that the users do not have to do this with editor.
+
+ * A handful of "git svn" updates.
+
+ * "git push" learned to accept and pass extra options to the
+ receiving end so that hooks can read and react to them.
+
+ * "git status" learned to suggest "merge --abort" during a conflicted
+ merge, just like it already suggests "rebase --abort" during a
+ conflicted rebase.
+
+ * "git jump" script (in contrib/) has been updated a bit.
+ (merge a91e692 jk/git-jump later to maint).
+
+ * "git push" and "git clone" learned to give better progress meters
+ to the end user who is waiting on the terminal.
+
+ * An entry "git log --decorate" for the tip of the current branch is
+ shown as "HEAD -> name" (where "name" is the name of the branch);
+ the arrow is now painted in the same color as "HEAD", not in the
+ color for commits.
+
+ * "git format-patch" learned format.from configuration variable to
+ specify the default settings for its "--from" option.
+
+ * "git am -3" calls "git merge-recursive" when it needs to fall back
+ to a three-way merge; this call has been turned into an internal
+ subroutine call instead of spawning a separate subprocess.
+
+ * The command line completion scripts (in contrib/) now knows about
+ "git branch --delete/--move [--remote]".
+ (merge 2703c22 vs/completion-branch-fully-spelled-d-m-r later to maint).
+
+ * "git rev-parse --git-path hooks/<hook>" learned to take
+ core.hooksPath configuration variable (introduced during 2.9 cycle)
+ into account.
+ (merge 9445b49 ab/hooks later to maint).
+
+ * "git log --show-signature" and other commands that display the
+ verification status of PGP signature now shows the longer key-id,
+ as 32-bit key-id is so last century.
+
+
Performance, Internal Implementation, Development Support etc.
* "git fast-import" learned the same performance trick to avoid
@@ -38,15 +139,182 @@ Performance, Internal Implementation, Development Support etc.
connection from a client that silently goes offline can hang around
for a long time, wasting resources. The socket-level KEEPALIVE has
been enabled to allow the OS to notice such failed connections.
- (merge a43b68a ew/daemon-socket-keepalive later to maint).
* "git upload-pack" command has been updated to use the parse-options
API.
- * The "git apply" standalone program is being libified; this is the
- first step to move many state variables into a structure that can
- be explicitly (re)initialized to make the machinery callable more
- than once.
+ * The "git apply" standalone program is being libified; the first
+ step to move many state variables into a structure that can be
+ explicitly (re)initialized to make the machinery callable more
+ than once has been merged.
+
+ * HTTP transport gained an option to produce more detailed debugging
+ trace.
+ (merge 73e57aa ep/http-curl-trace later to maint).
+
+ * Instead of taking advantage of the fact that a struct string_list
+ that is allocated with all NULs happens to be the INIT_NODUP kind,
+ the users of string_list structures are taught to initialize them
+ explicitly as such, to document their behaviour better.
+ (merge 2721ce2 jk/string-list-static-init later to maint).
+
+ * HTTPd tests learned to show the server error log to help diagnosing
+ a failing tests.
+ (merge 44f243d nd/test-lib-httpd-show-error-log-in-verbose later to maint).
+
+ * The ownership rule for the piece of memory that hold references to
+ be fetched in "git fetch" was screwy, which has been cleaned up.
+
+ * "git bisect" makes an internal call to "git diff-tree" when
+ bisection finds the culprit, but this call did not initialize the
+ data structure to pass to the diff-tree API correctly.
+
+ * Further preparatory clean-up for "worktree" feature continues.
+ (merge 0409e0b nd/worktree-cleanup-post-head-protection later to maint).
+
+ * Formats of the various data (and how to validate them) where we use
+ GPG signature have been documented.
+
+ * A new run-command API function pipe_command() is introduced to
+ sanely feed data to the standard input while capturing data from
+ the standard output and the standard error of an external process,
+ which is cumbersome to hand-roll correctly without deadlocking.
+
+ * The codepath to sign data in a prepared buffer with GPG has been
+ updated to use this API to read from the status-fd to check for
+ errors (instead of relying on GPG's exit status).
+ (merge efee955 jk/gpg-interface-cleanup later to maint).
+
+ * Allow t/perf framework to use the features from the most recent
+ version of Git even when testing an older installed version.
+
+ * The commands in the "log/diff" family have had an FILE* pointer in the
+ data structure they pass around for a long time, but some codepaths
+ used to always write to the standard output. As a preparatory step
+ to make "git format-patch" available to the internal callers, these
+ codepaths have been updated to consistently write into that FILE*
+ instead.
+
+ * Conversion from unsigned char sha1[20] to struct object_id
+ continues.
+
+ * Improve the look of the way "git fetch" reports what happened to
+ each ref that was fetched.
+
+ * The .c/.h sources are marked as such in our .gitattributes file so
+ that "git diff -W" and friends would work better.
+
+ * Code clean-up to avoid using a variable string that compilers may
+ feel untrustable as printf-style format given to write_file()
+ helper function.
+
+ * "git p4" used a location outside $GIT_DIR/refs/ to place its
+ temporary branches, which has been moved to refs/git-p4-tmp/.
+
+ * Existing autoconf generated test for the need to link with pthread
+ library did not check all the functions from pthread libraries;
+ recent FreeBSD has some functions in libc but not others, and we
+ mistakenly thought linking with libc is enough when it is not.
+
+ * When "git fsck" reports a broken link (e.g. a tree object contains
+ a blob that does not exist), both containing object and the object
+ that is referred to were reported with their 40-hex object names.
+ The command learned the "--name-objects" option to show the path to
+ the containing object from existing refs (e.g. "HEAD~24^2:file.txt").
+
+ * Allow http daemon tests in Travis CI tests.
+
+ * Makefile assumed that -lrt is always available on platforms that
+ want to use clock_gettime() and CLOCK_MONOTONIC, which is not a
+ case for recent Mac OS X. The necessary symbols are often found in
+ libc on many modern systems and having -lrt on the command line, as
+ long as the library exists, had no effect, but when the platform
+ removes librt.a that is a different matter--having -lrt will break
+ the linkage.
+
+ This change could be seen as a regression for those who do need to
+ specify -lrt, as they now specifically ask for NEEDS_LIBRT when
+ building. Hopefully they are in the minority these days.
+
+ * Further preparatory work on the refs API before the pluggable
+ backend series can land.
+
+ * Error handling in the codepaths that updates refs has been
+ improved.
+
+ * The API to iterate over all the refs (i.e. for_each_ref(), etc.)
+ has been revamped.
+
+ * The handling of the "text=auto" attribute has been corrected.
+ $ echo "* text=auto eol=crlf" >.gitattributes
+ used to have the same effect as
+ $ echo "* text eol=crlf" >.gitattributes
+ i.e. declaring all files are text (ignoring "auto"). The
+ combination has been fixed to be equivalent to doing
+ $ git config core.autocrlf true
+
+ * Documentation has been updated to show better example usage
+ of the updated "text=auto" attribute.
+
+ * A few tests that specifically target "git rebase -i" have been
+ added.
+
+ * Dumb http transport on the client side has been optimized.
+ (merge ecba195 ew/http-walker later to maint).
+
+ * Users of the parse_options_concat() API function need to allocate
+ extra slots in advance and fill them with OPT_END() when they want
+ to decide the set of supported options dynamically, which makes the
+ code error-prone and hard to read. This has been corrected by tweaking
+ the API to allocate and return a new copy of "struct option" array.
+
+ * "git fetch" exchanges batched have/ack messages between the sender
+ and the receiver, initially doubling every time and then falling
+ back to enlarge the window size linearly. The "smart http"
+ transport, being an half-duplex protocol, outgrows the preset limit
+ too quickly and becomes inefficient when interacting with a large
+ repository. The internal mechanism learned to grow the window size
+ more aggressively when working with the "smart http" transport.
+
+ * Tests for "git svn" have been taught to reuse the lib-httpd test
+ infrastructure when testing the subversion integration that
+ interacts with subversion repositories served over the http://
+ protocol.
+ (merge a8a5d25 ew/git-svn-http-tests later to maint).
+
+ * "git pack-objects" has a few options that tell it not to pack
+ objects found in certain packfiles, which require it to scan .idx
+ files of all available packs. The codepaths involved in these
+ operations have been optimized for a common case of not having any
+ non-local pack and/or any .kept pack.
+
+ * The t3700 test about "add --chmod=-x" have been made a bit more
+ robust and generally cleaned up.
+ (merge 766cdc4 ib/t3700-add-chmod-x-updates later to maint).
+
+ * The build procedure learned PAGER_ENV knob that lists what default
+ environment variable settings to export for popular pagers. This
+ mechanism is used to tweak the default settings to MORE on FreeBSD.
+ (merge 995bc22 ew/build-time-pager-tweaks later to maint).
+
+ * The http-backend (the server-side component of smart-http
+ transport) used to trickle the HTTP header one at a time. Now
+ these write(2)s are batched.
+ (merge b36045c ew/http-backend-batch-headers later to maint).
+
+ * When "git rebase" tries to compare set of changes on the updated
+ upstream and our own branch, it computes patch-id for all of these
+ changes and attempts to find matches. This has been optimized by
+ lazily computing the full patch-id (which is expensive) to be
+ compared only for changes that touch the same set of paths.
+ (merge ba67504 kw/patch-ids-optim later to maint).
+
+ * A handful of tests that were broken under gettext-poison build have
+ been fixed.
+
+ * The recent i18n patch we added during this cycle did a bit too much
+ refactoring of the messages to avoid word-legos; the repetition has
+ been reduced to help translators.
Also contains various documentation updates and code clean-ups.
@@ -64,70 +332,344 @@ notes for details).
--no-color or with --color=auto when the output is not connected to
a tty; this was corrected to make the format truly behave as
"auto".
- (merge b15a3e0 et/pretty-format-c-auto later to maint).
* "git rev-list --count" whose walk-length is limited with "-n"
option did not work well with the counting optimized to look at the
bitmap index.
- (merge fb85db8 jk/rev-list-count-with-bitmap later to maint).
* "git show -W" (extend hunks to cover the entire function, delimited
by lines that match the "funcname" pattern) used to show the entire
file when a change added an entire function at the end of the file,
which has been fixed.
- (merge 6f8d9bc rs/xdiff-hunk-with-func-line later to maint).
* The documentation set has been updated so that literal commands,
configuration variables and environment variables are consistently
typeset in fixed-width font and bold in manpages.
- (merge ae9f631 tr/doc-tt later to maint).
* "git svn propset" subcommand that was added in 2.3 days is
documented now.
- (merge 19a7f24 ap/git-svn-propset-doc later to maint).
* The documentation tries to consistently spell "GPG"; when
referring to the specific program name, "gpg" is used.
- (merge bc91316 dn/gpg-doc later to maint).
* "git reflog" stopped upon seeing an entry that denotes a branch
creation event (aka "unborn"), which made it appear as if the
reflog was truncated.
- (merge 71abeb7 sg/reflog-past-root later to maint).
* The git-prompt scriptlet (in contrib/) was not friendly with those
who uses "set -u", which has been fixed.
- (merge 34d8f5a vs/prompt-avoid-unset-variable later to maint).
* compat/regex code did not cleanly compile.
- (merge bd8f005 rj/compat-regex-size-max-fix later to maint).
* A codepath that used alloca(3) to place an unbounded amount of data
on the stack has been updated to avoid doing so.
- (merge b8ba412 jk/avoid-unbounded-alloca later to maint).
* "git update-index --add --chmod=+x file" may be usable as an escape
hatch, but not a friendly thing to force for people who do need to
use it regularly. "git add --chmod=+x file" can be used instead.
- (merge 4e55ed3 et/add-chmod-x later to maint).
* Build improvements for gnome-keyring (in contrib/)
- (merge 3cddb00 nb/gnome-keyring-build later to maint).
* "git status" used to say "working directory" when it meant "working
tree".
- (merge 2a0e6cd lv/status-say-working-tree-not-directory later to maint).
* Comments about misbehaving FreeBSD shells have been clarified with
the version number (9.x and before are broken, newer ones are OK).
- (merge 9b35cad em/newer-freebsd-shells-are-fine-with-returns later to maint).
* "git cherry-pick A" worked on an unborn branch, but "git
cherry-pick A..B" didn't.
- (merge 0f974e2 mg/cherry-pick-multi-on-unborn later to maint).
+
+ * Fix an unintended regression in v2.9 that breaks "clone --depth"
+ that recurses down to submodules by forcing the submodules to also
+ be cloned shallowly, which many server instances that host upstream
+ of the submodules are not prepared for.
+
+ * Fix unnecessarily waste in the idiomatic use of ': ${VAR=default}'
+ to set the default value, without enclosing it in double quotes.
+
+ * Some platform-specific code had non-ANSI strict declarations of C
+ functions that do not take any parameters, which has been
+ corrected.
+
+ * The internal code used to show local timezone offset is not
+ prepared to handle timestamps beyond year 2100, and gave a
+ bogus offset value to the caller. Use a more benign looking
+ +0000 instead and let "git log" going in such a case, instead
+ of aborting.
+
+ * One among four invocations of readlink(1) in our test suite has
+ been rewritten so that the test can run on systems without the
+ command (others are in valgrind test framework and t9802).
+
+ * t/perf needs /usr/bin/time with GNU extension; the invocation of it
+ is updated to "gtime" on Darwin.
+
+ * A bug, which caused "git p4" while running under verbose mode to
+ report paths that are omitted due to branch prefix incorrectly, has
+ been fixed; the command said "Ignoring file outside of prefix" for
+ paths that are _inside_.
+
+ * The top level documentation "git help git" still pointed at the
+ documentation set hosted at now-defunct google-code repository.
+ Update it to point to https://git.github.io/htmldocs/git.html
+ instead.
+
+ * A helper function that takes the contents of a commit object and
+ finds its subject line did not ignore leading blank lines, as is
+ commonly done by other codepaths. Make it ignore leading blank
+ lines to match.
+
+ * For a long time, we carried an in-code comment that said our
+ colored output would work only when we use fprintf/fputs on
+ Windows, which no longer is the case for the past few years.
+
+ * "gc.autoPackLimit" when set to 1 should not trigger a repacking
+ when there is only one pack, but the code counted poorly and did
+ so.
+
+ * Add a test to specify the desired behaviour that currently is not
+ available in "git rebase -Xsubtree=...".
+
+ * More mark-up updates to typeset strings that are expected to
+ literally typed by the end user in fixed-width font.
+
+ * "git commit --amend --allow-empty-message -S" for a commit without
+ any message body could have misidentified where the header of the
+ commit object ends.
+
+ * "git rebase -i --autostash" did not restore the auto-stashed change
+ when the operation was aborted.
+
+ * Git does not know what the contents in the index should be for a
+ path added with "git add -N" yet, so "git grep --cached" should not
+ show hits (or show lack of hits, with -L) in such a path, but that
+ logic does not apply to "git grep", i.e. searching in the working
+ tree files. But we did so by mistake, which has been corrected.
+
+ * "git blame -M" missed a single line that was moved within the file.
+
+ * Fix recently introduced codepaths that are involved in parallel
+ submodule operations, which gave up on reading too early, and
+ could have wasted CPU while attempting to write under a corner
+ case condition.
+
+ * "git grep -i" has been taught to fold case in non-ascii locales
+ correctly.
+
+ * A test that unconditionally used "mktemp" learned that the command
+ is not necessarily available everywhere.
+
+ * There are certain house-keeping tasks that need to be performed at
+ the very beginning of any Git program, and programs that are not
+ built-in commands had to do them exactly the same way as "git"
+ potty does. It was easy to make mistakes in one-off standalone
+ programs (like test helpers). A common "main()" function that
+ calls cmd_main() of individual program has been introduced to
+ make it harder to make mistakes.
+ (merge de61ceb jk/common-main later to maint).
+
+ * The test framework learned a new helper test_match_signal to
+ check an exit code from getting killed by an expected signal.
+
+ * General code clean-up around a helper function to write a
+ single-liner to a file.
+ (merge 7eb6e10 jk/write-file later to maint).
+
+ * One part of "git am" had an oddball helper function that called
+ stuff from outside "his" as opposed to calling what we have "ours",
+ which was not gender-neutral and also inconsistent with the rest of
+ the system where outside stuff is usuall called "theirs" in
+ contrast to "ours".
+
+ * "git blame file" allowed the lineage of lines in the uncommitted,
+ unadded contents of "file" to be inspected, but it refused when
+ "file" did not appear in the current commit. When "file" was
+ created by renaming an existing file (but the change has not been
+ committed), this restriction was unnecessarily tight.
+
+ * "git add -N dir/file && git write-tree" produced an incorrect tree
+ when there are other paths in the same directory that sorts after
+ "file".
+
+ * "git fetch http://user:pass@host/repo..." scrubbed the userinfo
+ part, but "git push" didn't.
+
+ * "git merge" with renormalization did not work well with
+ merge-recursive, due to "safer crlf" conversion kicking in when it
+ shouldn't.
+ (merge 1335d76 jc/renormalize-merge-kill-safer-crlf later to maint).
+
+ * The use of strbuf in "git rm" to build filename to remove was a bit
+ suboptimal, which has been fixed.
+
+ * An age old bug that caused "git diff --ignore-space-at-eol"
+ misbehave has been fixed.
+
+ * "git notes merge" had a code to see if a path exists (and fails if
+ it does) and then open the path for writing (when it doesn't).
+ Replace it with open with O_EXCL.
+
+ * "git pack-objects" and "git index-pack" mostly operate with off_t
+ when talking about the offset of objects in a packfile, but there
+ were a handful of places that used "unsigned long" to hold that
+ value, leading to an unintended truncation.
+
+ * Recent update to "git daemon" tries to enable the socket-level
+ KEEPALIVE, but when it is spawned via inetd, the standard input
+ file descriptor may not necessarily be connected to a socket.
+ Suppress an ENOTSOCK error from setsockopt().
+
+ * Recent FreeBSD stopped making perl available at /usr/bin/perl;
+ switch the default the built-in path to /usr/local/bin/perl on not
+ too ancient FreeBSD releases.
+
+ * "git commit --help" said "--no-verify" is only about skipping the
+ pre-commit hook, and failed to say that it also skipped the
+ commit-msg hook.
+
+ * "git merge" in Git v2.9 was taught to forbid merging an unrelated
+ lines of history by default, but that is exactly the kind of thing
+ the "--rejoin" mode of "git subtree" (in contrib/) wants to do.
+ "git subtree" has been taught to use the "--allow-unrelated-histories"
+ option to override the default.
+
+ * The build procedure for "git persistent-https" helper (in contrib/)
+ has been updated so that it can be built with more recent versions
+ of Go.
+
+ * There is an optimization used in "git diff $treeA $treeB" to borrow
+ an already checked-out copy in the working tree when it is known to
+ be the same as the blob being compared, expecting that open/mmap of
+ such a file is faster than reading it from the object store, which
+ involves inflating and applying delta. This however kicked in even
+ when the checked-out copy needs to go through the convert-to-git
+ conversion (including the clean filter), which defeats the whole
+ point of the optimization. The optimization has been disabled when
+ the conversion is necessary.
+
+ * "git -c grep.patternType=extended log --basic-regexp" misbehaved
+ because the internal API to access the grep machinery was not
+ designed well.
+
+ * Windows port was failing some tests in t4130, due to the lack of
+ inum in the returned values by its lstat(2) emulation.
+
+ * The reflog output format is documented better, and a new format
+ --date=unix to report the seconds-since-epoch (without timezone)
+ has been added.
+ (merge 442f6fd jk/reflog-date later to maint).
+
+ * "git difftool <paths>..." started in a subdirectory failed to
+ interpret the paths relative to that directory, which has been
+ fixed.
+
+ * The characters in the label shown for tags/refs for commits in
+ "gitweb" output are now properly escaped for proper HTML output.
+
+ * FreeBSD can lie when asked mtime of a directory, which made the
+ untracked cache code to fall back to a slow-path, which in turn
+ caused tests in t7063 to fail because it wanted to verify the
+ behaviour of the fast-path.
+
+ * Squelch compiler warnings for nedmalloc (in compat/) library.
+
+ * A small memory leak in the command line parsing of "git blame"
+ has been plugged.
+
+ * The API documentation for hashmap was unclear if hashmap_entry
+ can be safely discarded without any other consideration. State
+ that it is safe to do so.
+
+ * Not-so-recent rewrite of "git am" that started making internal
+ calls into the commit machinery had an unintended regression, in
+ that no matter how many seconds it took to apply many patches, the
+ resulting committer timestamp for the resulting commits were all
+ the same.
+
+ * "git push --force-with-lease" already had enough logic to allow
+ ensuring that such a push results in creation of a ref (i.e. the
+ receiving end did not have another push from sideways that would be
+ discarded by our force-pushing), but didn't expose this possibility
+ to the users. It does so now.
+ (merge 9eed4f3 jk/push-force-with-lease-creation later to maint).
+
+ * The mechanism to limit the pack window memory size, when packing is
+ done using multiple threads (which is the default), is per-thread,
+ but this was not documented clearly.
+ (merge 954176c ms/document-pack-window-memory-is-per-thread later to maint).
+
+ * "import-tars" fast-import script (in contrib/) used to ignore a
+ hardlink target and replaced it with an empty file, which has been
+ corrected to record the same blob as the other file the hardlink is
+ shared with.
+ (merge 04e0869 js/import-tars-hardlinks later to maint).
+
+ * "git mv dir non-existing-dir/" did not work in some environments
+ the same way as existing mainstream platforms. The code now moves
+ "dir" to "non-existing-dir", without relying on rename("A", "B/")
+ that strips the trailing slash of '/'.
+ (merge 189d035 js/mv-dir-to-new-directory later to maint).
+
+ * The "t/" hierarchy is prone to get an unusual pathname; "make test"
+ has been taught to make sure they do not contain paths that cannot
+ be checked out on Windows (and the mechanism can be reusable to
+ catch pathnames that are not portable to other platforms as need
+ arises).
+ (merge c2cafd3 js/test-lint-pathname later to maint).
+
+ * When "git merge-recursive" works on history with many criss-cross
+ merges in "verbose" mode, the names the command assigns to the
+ virtual merge bases could have overwritten each other by unintended
+ reuse of the same piece of memory.
+ (merge 5447a76 rs/pull-signed-tag later to maint).
+
+ * "git checkout --detach <branch>" used to give the same advice
+ message as that is issued when "git checkout <tag>" (or anything
+ that is not a branch name) is given, but asking with "--detach" is
+ an explicit enough sign that the user knows what is going on. The
+ advice message has been squelched in this case.
+ (merge 779b88a sb/checkout-explit-detach-no-advice later to maint).
+
+ * "git difftool" by default ignores the error exit from the backend
+ commands it spawns, because often they signal that they found
+ differences by exiting with a non-zero status code just like "diff"
+ does; the exit status codes 126 and above however are special in
+ that they are used to signal that the command is not executable,
+ does not exist, or killed by a signal. "git difftool" has been
+ taught to notice these exit status codes.
+ (merge 45a4f5d jk/difftool-command-not-found later to maint).
+
+ * On Windows, help.browser configuration variable used to be ignored,
+ which has been corrected.
+ (merge 6db5967 js/no-html-bypass-on-windows later to maint).
+
+ * The "git -c var[=val] cmd" facility to append a configuration
+ variable definition at the end of the search order was described in
+ git(1) manual page, but not in git-config(1), which was more likely
+ place for people to look for when they ask "can I make a one-shot
+ override, and if so how?"
+ (merge ae1f709 dg/document-git-c-in-git-config-doc later to maint).
+
+ * The tempfile (hence its user lockfile) API lets the caller to open
+ a file descriptor to a temporary file, write into it and then
+ finalize it by first closing the filehandle and then either
+ removing or renaming the temporary file. When the process spawns a
+ subprocess after obtaining the file descriptor, and if the
+ subprocess has not exited when the attempt to remove or rename is
+ made, the last step fails on Windows, because the subprocess has
+ the file descriptor still open. Open tempfile with O_CLOEXEC flag
+ to avoid this (on Windows, this is mapped to O_NOINHERIT).
+ (merge 05d1ed6 bw/mingw-avoid-inheriting-fd-to-lockfile later to maint).
+
+ * Correct an age-old calco (is that a typo-like word for calc)
+ in the documentation.
+ (merge 7841c48 ls/packet-line-protocol-doc-fix later to maint).
* Other minor clean-ups and documentation updates
- (merge 3a39f61 pc/occurred later to maint).
- (merge 9e70233 jk/fetch-prune-doc later to maint).
- (merge ed008d7 pb/strbuf-read-file-doc later to maint).
- (merge 31da121 jc/deref-tag later to maint).
+ (merge 02a8cfa rs/merge-add-strategies-simplification later to maint).
+ (merge af4941d rs/merge-recursive-string-list-init later to maint).
+ (merge 1eb47f1 rs/use-strbuf-add-unique-abbrev later to maint).
+ (merge ddd0bfa jk/tighten-alloc later to maint).
+ (merge ecf30b2 rs/mailinfo-lib later to maint).
+ (merge 0eb75ce sg/reflog-past-root later to maint).
+ (merge 4369523 hv/doc-commit-reference-style later to maint).
diff --git a/Documentation/RelNotes/2.10.1.txt b/Documentation/RelNotes/2.10.1.txt
new file mode 100644
index 0000000000..73f3b978cf
--- /dev/null
+++ b/Documentation/RelNotes/2.10.1.txt
@@ -0,0 +1,120 @@
+Git v2.10.1 Release Notes
+=========================
+
+Fixes since v2.10
+-----------------
+
+ * Clarify various ways to specify the "revision ranges" in the
+ documentation.
+
+ * "diff-highlight" script (in contrib/) learned to work better with
+ "git log -p --graph" output.
+
+ * The test framework left the number of tests and success/failure
+ count in the t/test-results directory, keyed by the name of the
+ test script plus the process ID. The latter however turned out not
+ to serve any useful purpose. The process ID part of the filename
+ has been removed.
+
+ * Having a submodule whose ".git" repository is somehow corrupt
+ caused a few commands that recurse into submodules loop forever.
+
+ * "git symbolic-ref -d HEAD" happily removes the symbolic ref, but
+ the resulting repository becomes an invalid one. Teach the command
+ to forbid removal of HEAD.
+
+ * A test spawned a short-lived background process, which sometimes
+ prevented the test directory from getting removed at the end of the
+ script on some platforms.
+
+ * Update a few tests that used to use GIT_CURL_VERBOSE to use the
+ newer GIT_TRACE_CURL.
+
+ * Update Japanese translation for "git-gui".
+
+ * "git fetch http::/site/path" did not die correctly and segfaulted
+ instead.
+
+ * "git commit-tree" stopped reading commit.gpgsign configuration
+ variable that was meant for Porcelain "git commit" in Git 2.9; we
+ forgot to update "git gui" to look at the configuration to match
+ this change.
+
+ * "git log --cherry-pick" used to include merge commits as candidates
+ to be matched up with other commits, resulting a lot of wasted time.
+ The patch-id generation logic has been updated to ignore merges to
+ avoid the wastage.
+
+ * The http transport (with curl-multi option, which is the default
+ these days) failed to remove curl-easy handle from a curlm session,
+ which led to unnecessary API failures.
+
+ * "git diff -W" output needs to extend the context backward to
+ include the header line of the current function and also forward to
+ include the body of the entire current function up to the header
+ line of the next one. This process may have to merge to adjacent
+ hunks, but the code forgot to do so in some cases.
+
+ * Performance tests done via "t/perf" did not use the same set of
+ build configuration if the user relied on autoconf generated
+ configuration.
+
+ * "git format-patch --base=..." feature that was recently added
+ showed the base commit information after "-- " e-mail signature
+ line, which turned out to be inconvenient. The base information
+ has been moved above the signature line.
+
+ * Even when "git pull --rebase=preserve" (and the underlying "git
+ rebase --preserve") can complete without creating any new commit
+ (i.e. fast-forwards), it still insisted on having a usable ident
+ information (read: user.email is set correctly), which was less
+ than nice. As the underlying commands used inside "git rebase"
+ would fail with a more meaningful error message and advice text
+ when the bogus ident matters, this extra check was removed.
+
+ * "git gc --aggressive" used to limit the delta-chain length to 250,
+ which is way too deep for gaining additional space savings and is
+ detrimental for runtime performance. The limit has been reduced to
+ 50.
+
+ * Documentation for individual configuration variables to control use
+ of color (like `color.grep`) said that their default value is
+ 'false', instead of saying their default is taken from `color.ui`.
+ When we updated the default value for color.ui from 'false' to
+ 'auto' quite a while ago, all of them broke. This has been
+ corrected.
+
+ * A shell script example in check-ref-format documentation has been
+ fixed.
+
+ * "git checkout <word>" does not follow the usual disambiguation
+ rules when the <word> can be both a rev and a path, to allow
+ checking out a branch 'foo' in a project that happens to have a
+ file 'foo' in the working tree without having to disambiguate.
+ This was poorly documented and the check was incorrect when the
+ command was run from a subdirectory.
+
+ * Some codepaths in "git diff" used regexec(3) on a buffer that was
+ mmap(2)ed, which may not have a terminating NUL, leading to a read
+ beyond the end of the mapped region. This was fixed by introducing
+ a regexec_buf() helper that takes a <ptr,len> pair with REG_STARTEND
+ extension.
+
+ * The procedure to build Git on Mac OS X for Travis CI hardcoded the
+ internal directory structure we assumed HomeBrew uses, which was a
+ no-no. The procedure has been updated to ask HomeBrew things we
+ need to know to fix this.
+
+ * When "git rebase -i" is given a broken instruction, it told the
+ user to fix it with "--edit-todo", but didn't say what the step
+ after that was (i.e. "--continue").
+
+ * "git add --chmod=+x" added recently lacked documentation, which has
+ been corrected.
+
+ * "git add --chmod=+x <pathspec>" added recently only toggled the
+ executable bit for paths that are either new or modified. This has
+ been corrected to flip the executable bit for all paths that match
+ the given pathspec.
+
+Also contains minor documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.11.0.txt b/Documentation/RelNotes/2.11.0.txt
new file mode 100644
index 0000000000..cfe94b9918
--- /dev/null
+++ b/Documentation/RelNotes/2.11.0.txt
@@ -0,0 +1,298 @@
+Git 2.11 Release Notes
+======================
+
+Updates since v2.10
+-------------------
+
+UI, Workflows & Features
+
+ * "git format-patch --cover-letter HEAD^" to format a single patch
+ with a separate cover letter now numbers the output as [PATCH 0/1]
+ and [PATCH 1/1] by default.
+
+ * An incoming "git push" that attempts to push too many bytes can now
+ be rejected by setting a new configuration variable at the receiving
+ end.
+
+ * "git nosuchcommand --help" said "No manual entry for gitnosuchcommand",
+ which was not intuitive, given that "git nosuchcommand" said "git:
+ 'nosuchcommand' is not a git command".
+
+ * "git clone --resurse-submodules --reference $path $URL" is a way to
+ reduce network transfer cost by borrowing objects in an existing
+ $path repository when cloning the superproject from $URL; it
+ learned to also peek into $path for presense of corresponding
+ repositories of submodules and borrow objects from there when able.
+
+ * The "git diff --submodule={short,log}" mechanism has been enhanced
+ to allow "--submodule=diff" to show the patch between the submodule
+ commits bound to the superproject.
+
+ * Even though "git hash-objects", which is a tool to take an
+ on-filesystem data stream and put it into the Git object store,
+ allowed to perform the "outside-world-to-Git" conversions (e.g.
+ end-of-line conversions and application of the clean-filter), and
+ it had the feature on by default from very early days, its reverse
+ operation "git cat-file", which takes an object from the Git object
+ store and externalize for the consumption by the outside world,
+ lacked an equivalent mechanism to run the "Git-to-outside-world"
+ conversion. The command learned the "--filters" option to do so.
+
+ * Output from "git diff" can be made easier to read by selecting
+ which lines are common and which lines are added/deleted
+ intelligently when the lines before and after the changed section
+ are the same. A command line option is added to help with the
+ experiment to find a good heuristics.
+
+ * In some projects, it is common to use "[RFC PATCH]" as the subject
+ prefix for a patch meant for discussion rather than application. A
+ new option "--rfc" was a short-hand for "--subject-prefix=RFC PATCH"
+ to help the participants of such projects.
+
+ * "git add --chmod=+x <pathspec>" added recently only toggled the
+ executable bit for paths that are either new or modified. This has
+ been corrected to flip the executable bit for all paths that match
+ the given pathspec.
+
+ * When "git format-patch --stdout" output is placed as an in-body
+ header and it uses the RFC2822 header folding, "git am" failed to
+ put the header line back into a single logical line. The
+ underlying "git mailinfo" was taught to handle this properly.
+
+
+Performance, Internal Implementation, Development Support etc.
+
+ * The delta-base-cache mechanism has been a key to the performance in
+ a repository with a tightly packed packfile, but it did not scale
+ well even with a larger value of core.deltaBaseCacheLimit.
+
+ * Enhance "git status --porcelain" output by collecting more data on
+ the state of the index and the working tree files, which may
+ further be used to teach git-prompt (in contrib/) to make fewer
+ calls to git.
+
+ * Extract a small helper out of the function that reads the authors
+ script file "git am" internally uses.
+ (merge a77598e jc/am-read-author-file later to maint).
+
+ * Lifts calls to exit(2) and die() higher in the callchain in
+ sequencer.c files so that more helper functions in it can be used
+ by callers that want to handle error conditions themselves.
+
+ * "git am" has been taught to make an internal call to "git apply"'s
+ innards without spawning the latter as a separate process.
+
+ * The ref-store abstraction was introduced to the refs API so that we
+ can plug in different backends to store references.
+
+ * The "unsigned char sha1[20]" to "struct object_id" conversion
+ continues. Notable changes in this round includes that ce->sha1,
+ i.e. the object name recorded in the cache_entry, turns into an
+ object_id.
+
+ * JGit can show a fake ref "capabilities^{}" to "git fetch" when it
+ does not advertise any refs, but "git fetch" was not prepared to
+ see such an advertisement. When the other side disconnects without
+ giving any ref advertisement, we used to say "there may not be a
+ repository at that URL", but we may have seen other advertisement
+ like "shallow" and ".have" in which case we definitely know that a
+ repository is there. The code to detect this case has also been
+ updated.
+
+ * Some codepaths in "git pack-objects" were not ready to use an
+ existing pack bitmap; now they are and as the result they have
+ become faster.
+
+
+Also contains various documentation updates and code clean-ups.
+
+
+Fixes since v2.10
+-----------------
+
+Unless otherwise noted, all the fixes since v2.9 in the maintenance
+track are contained in this release (see the maintenance releases'
+notes for details).
+
+ * Clarify various ways to specify the "revision ranges" in the
+ documentation.
+
+ * "diff-highlight" script (in contrib/) learned to work better with
+ "git log -p --graph" output.
+
+ * The test framework left the number of tests and success/failure
+ count in the t/test-results directory, keyed by the name of the
+ test script plus the process ID. The latter however turned out not
+ to serve any useful purpose. The process ID part of the filename
+ has been removed.
+
+ * Having a submodule whose ".git" repository is somehow corrupt
+ caused a few commands that recurse into submodules loop forever.
+
+ * "git symbolic-ref -d HEAD" happily removes the symbolic ref, but
+ the resulting repository becomes an invalid one. Teach the command
+ to forbid removal of HEAD.
+
+ * A test spawned a short-lived background process, which sometimes
+ prevented the test directory from getting removed at the end of the
+ script on some platforms.
+
+ * Update a few tests that used to use GIT_CURL_VERBOSE to use the
+ newer GIT_TRACE_CURL.
+
+ * "git pack-objects --include-tag" was taught that when we know that
+ we are sending an object C, we want a tag B that directly points at
+ C but also a tag A that points at the tag B. We used to miss the
+ intermediate tag B in some cases.
+ (merge b773dde jk/pack-tag-of-tag later to maint).
+
+ * Update Japanese translation for "git-gui".
+ (merge 02748bc sy/git-gui-i18n-ja later to maint).
+
+ * "git fetch http::/site/path" did not die correctly and segfaulted
+ instead.
+ (merge d63ed6e jk/fix-remote-curl-url-wo-proto later to maint).
+
+ * "git commit-tree" stopped reading commit.gpgsign configuration
+ variable that was meant for Porcelain "git commit" in Git 2.9; we
+ forgot to update "git gui" to look at the configuration to match
+ this change.
+ (merge f14a310 js/git-gui-commit-gpgsign later to maint).
+
+ * "git add --chmod=+x" added recently lacked documentation, which has
+ been corrected.
+ (merge 7ef7903 et/add-chmod-x later to maint).
+
+ * "git log --cherry-pick" used to include merge commits as candidates
+ to be matched up with other commits, resulting a lot of wasted time.
+ The patch-id generation logic has been updated to ignore merges to
+ avoid the wastage.
+ (merge 7c81040 jk/patch-ids-no-merges later to maint).
+
+ * The http transport (with curl-multi option, which is the default
+ these days) failed to remove curl-easy handle from a curlm session,
+ which led to unnecessary API failures.
+ (merge 2abc848 ew/http-do-not-forget-to-call-curl-multi-remove-handle later to maint).
+
+ * There were numerous corner cases in which the configuration files
+ are read and used or not read at all depending on the directory a
+ Git command was run, leading to inconsistent behaviour. The code
+ to set-up repository access at the beginning of a Git process has
+ been updated to fix them.
+ (merge 4d0efa1 jk/setup-sequence-update later to maint).
+
+ * "git diff -W" output needs to extend the context backward to
+ include the header line of the current function and also forward to
+ include the body of the entire current function up to the header
+ line of the next one. This process may have to merge to adjacent
+ hunks, but the code forgot to do so in some cases.
+ (merge 45d2f75 rs/xdiff-merge-overlapping-hunks-for-W-context later to maint).
+
+ * Performance tests done via "t/perf" did not use the same set of
+ build configuration if the user relied on autoconf generated
+ configuration.
+ (merge cd5c281 ks/perf-build-with-autoconf later to maint).
+
+ * "git format-patch --base=..." feature that was recently added
+ showed the base commit information after "-- " e-mail signature
+ line, which turned out to be inconvenient. The base information
+ has been moved above the signature line.
+ (merge 480871e jt/format-patch-base-info-above-sig later to maint).
+
+ * More i18n.
+ (merge 43073f8 va/i18n later to maint).
+
+ * Even when "git pull --rebase=preserve" (and the underlying "git
+ rebase --preserve") can complete without creating any new commit
+ (i.e. fast-forwards), it still insisted on having a usable ident
+ information (read: user.email is set correctly), which was less
+ than nice. As the underlying commands used inside "git rebase"
+ would fail with a more meaningful error message and advice text
+ when the bogus ident matters, this extra check was removed.
+ (merge 1e461c4 jk/rebase-i-drop-ident-check later to maint).
+
+ * "git gc --aggressive" used to limit the delta-chain length to 250,
+ which is way too deep for gaining additional space savings and is
+ detrimental for runtime performance. The limit has been reduced to
+ 50.
+ (merge 07e7dbf jk/reduce-gc-aggressive-depth later to maint).
+
+ * Documentation for individual configuration variables to control use
+ of color (like `color.grep`) said that their default value is
+ 'false', instead of saying their default is taken from `color.ui`.
+ When we updated the default value for color.ui from 'false' to
+ 'auto' quite a while ago, all of them broke. This has been
+ corrected.
+ (merge 14d16e2 mm/config-color-ui-default-to-auto later to maint).
+
+ * The pretty-format specifier "%C(auto)" used by the "log" family of
+ commands to enable coloring of the output is taught to also issue a
+ color-reset sequence to the output.
+ (merge c99ad27 rs/c-auto-resets-attributes later to maint).
+
+ * A shell script example in check-ref-format documentation has been
+ fixed.
+ (merge 92dece7 ep/doc-check-ref-format-example later to maint).
+
+ * "git checkout <word>" does not follow the usual disambiguation
+ rules when the <word> can be both a rev and a path, to allow
+ checking out a branch 'foo' in a project that happens to have a
+ file 'foo' in the working tree without having to disambiguate.
+ This was poorly documented and the check was incorrect when the
+ command was run from a subdirectory.
+ (merge b829b94 nd/checkout-disambiguation later to maint).
+
+ * Some codepaths in "git diff" used regexec(3) on a buffer that was
+ mmap(2)ed, which may not have a terminating NUL, leading to a read
+ beyond the end of the mapped region. This was fixed by introducing
+ a regexec_buf() helper that takes a <ptr,len> pair with REG_STARTEND
+ extension.
+ (merge b7d36ff js/regexec-buf later to maint).
+
+ * The procedure to build Git on Mac OS X for Travis CI hardcoded the
+ internal directory structure we assumed HomeBrew uses, which was a
+ no-no. The procedure has been updated to ask HomeBrew things we
+ need to know to fix this.
+ (merge f86f49b ls/travis-homebrew-path-fix later to maint).
+
+ * When "git rebase -i" is given a broken instruction, it told the
+ user to fix it with "--edit-todo", but didn't say what the step
+ after that was (i.e. "--continue").
+ (merge 37875b4 rt/rebase-i-broken-insn-advise later to maint).
+
+ * Documentation around tools to import from CVS was fairly outdated.
+ (merge 106b672 jk/doc-cvs-update later to maint).
+
+ * "git clone --recurse-submodules" lost the progress eye-candy in
+ recent update, which has been corrected.
+
+ * A low-level function verify_packfile() was meant to show errors
+ that were detected without dying itself, but under some conditions
+ it didn't and died instead, which has been fixed.
+ (merge a9445d859e jk/verify-packfile-gently later to maint).
+
+ * When "git fetch" tries to find where the history of the repository
+ it runs in has diverged from what the other side has, it has a
+ mechanism to avoid digging too deep into irrelevant side branches.
+ This however did not work well over the "smart-http" transport due
+ to a design bug, which has been fixed.
+ (merge 06b3d386e0 jt/fetch-pack-in-vain-count-with-stateless later to maint).
+
+ * In the codepath that comes up with the hostname to be used in an
+ e-mail when the user didn't tell us, we looked at ai_canonname
+ field in struct addrinfo without making sure it is not NULL first.
+ (merge c375a7efa3 jk/ident-ai-canonname-could-be-null later to maint).
+
+ * "git worktree", even though it used the default_abbrev setting that
+ ought to be affected by core.abbrev configuration variable, ignored
+ the variable setting. The command has been taught to read the
+ default set of configuration variables to correct this.
+ (merge d49028e6e7 jc/worktree-config later to maint).
+
+ * Other minor doc, test and build updates and code cleanups.
+ (merge e78d57e bw/pathspec-remove-unused-extern-decl later to maint).
+ (merge ce25e4c rs/checkout-some-states-are-const later to maint).
+ (merge a8342a4 rs/strbuf-remove-fix later to maint).
+ (merge b56aa5b rs/unpack-trees-reduce-file-scope-global later to maint).
+ (merge 5efc60c mr/vcs-svn-printf-ulong later to maint).
+ (merge a22ae75 rs/cocci later to maint).
diff --git a/Documentation/RelNotes/2.3.10.txt b/Documentation/RelNotes/2.3.10.txt
index 9d425d814d..20c2d2cacc 100644
--- a/Documentation/RelNotes/2.3.10.txt
+++ b/Documentation/RelNotes/2.3.10.txt
@@ -7,7 +7,7 @@ Fixes since v2.3.9
* xdiff code we use to generate diffs is not prepared to handle
extremely large files. It uses "int" in many places, which can
overflow if we have a very large number of lines or even bytes in
- our input files, for example. Cap the input size to soemwhere
+ our input files, for example. Cap the input size to somewhere
around 1GB for now.
* Some protocols (like git-remote-ext) can execute arbitrary code
diff --git a/Documentation/RelNotes/2.4.10.txt b/Documentation/RelNotes/2.4.10.txt
index 8621199bc6..702d8d4e22 100644
--- a/Documentation/RelNotes/2.4.10.txt
+++ b/Documentation/RelNotes/2.4.10.txt
@@ -7,7 +7,7 @@ Fixes since v2.4.9
* xdiff code we use to generate diffs is not prepared to handle
extremely large files. It uses "int" in many places, which can
overflow if we have a very large number of lines or even bytes in
- our input files, for example. Cap the input size to soemwhere
+ our input files, for example. Cap the input size to somewhere
around 1GB for now.
* Some protocols (like git-remote-ext) can execute arbitrary code
diff --git a/Documentation/RelNotes/2.5.4.txt b/Documentation/RelNotes/2.5.4.txt
index a5e8477a4a..b8a2f93ee7 100644
--- a/Documentation/RelNotes/2.5.4.txt
+++ b/Documentation/RelNotes/2.5.4.txt
@@ -7,7 +7,7 @@ Fixes since v2.5.4
* xdiff code we use to generate diffs is not prepared to handle
extremely large files. It uses "int" in many places, which can
overflow if we have a very large number of lines or even bytes in
- our input files, for example. Cap the input size to soemwhere
+ our input files, for example. Cap the input size to somewhere
around 1GB for now.
* Some protocols (like git-remote-ext) can execute arbitrary code
diff --git a/Documentation/RelNotes/2.6.1.txt b/Documentation/RelNotes/2.6.1.txt
index 1e51363e3c..f37ea89cda 100644
--- a/Documentation/RelNotes/2.6.1.txt
+++ b/Documentation/RelNotes/2.6.1.txt
@@ -7,7 +7,7 @@ Fixes since v2.6
* xdiff code we use to generate diffs is not prepared to handle
extremely large files. It uses "int" in many places, which can
overflow if we have a very large number of lines or even bytes in
- our input files, for example. Cap the input size to soemwhere
+ our input files, for example. Cap the input size to somewhere
around 1GB for now.
* Some protocols (like git-remote-ext) can execute arbitrary code
diff --git a/Documentation/RelNotes/2.9.1.txt b/Documentation/RelNotes/2.9.1.txt
index ed2bca038b..338394097e 100644
--- a/Documentation/RelNotes/2.9.1.txt
+++ b/Documentation/RelNotes/2.9.1.txt
@@ -24,5 +24,94 @@ Fixes since v2.9
file when a change added an entire function at the end of the file,
which has been fixed.
+ * The documentation set has been updated so that literal commands,
+ configuration variables and environment variables are consistently
+ typeset in fixed-width font and bold in manpages.
+
+ * "git svn propset" subcommand that was added in 2.3 days is
+ documented now.
+
+ * The documentation tries to consistently spell "GPG"; when
+ referring to the specific program name, "gpg" is used.
+
+ * "git reflog" stopped upon seeing an entry that denotes a branch
+ creation event (aka "unborn"), which made it appear as if the
+ reflog was truncated.
+
+ * The git-prompt scriptlet (in contrib/) was not friendly with those
+ who uses "set -u", which has been fixed.
+
+ * A codepath that used alloca(3) to place an unbounded amount of data
+ on the stack has been updated to avoid doing so.
+
+ * "git update-index --add --chmod=+x file" may be usable as an escape
+ hatch, but not a friendly thing to force for people who do need to
+ use it regularly. "git add --chmod=+x file" can be used instead.
+
+ * Build improvements for gnome-keyring (in contrib/)
+
+ * "git status" used to say "working directory" when it meant "working
+ tree".
+
+ * Comments about misbehaving FreeBSD shells have been clarified with
+ the version number (9.x and before are broken, newer ones are OK).
+
+ * "git cherry-pick A" worked on an unborn branch, but "git
+ cherry-pick A..B" didn't.
+
+ * "git add -i/-p" learned to honor diff.compactionHeuristic
+ experimental knob, so that the user can work on the same hunk split
+ as "git diff" output.
+
+ * "log --graph --format=" learned that "%>|(N)" specifies the width
+ relative to the terminal's left edge, not relative to the area to
+ draw text that is to the right of the ancestry-graph section. It
+ also now accepts negative N that means the column limit is relative
+ to the right border.
+
+ * The ownership rule for the piece of memory that hold references to
+ be fetched in "git fetch" was screwy, which has been cleaned up.
+
+ * "git bisect" makes an internal call to "git diff-tree" when
+ bisection finds the culprit, but this call did not initialize the
+ data structure to pass to the diff-tree API correctly.
+
+ * Formats of the various data (and how to validate them) where we use
+ GPG signature have been documented.
+
+ * Fix an unintended regression in v2.9 that breaks "clone --depth"
+ that recurses down to submodules by forcing the submodules to also
+ be cloned shallowly, which many server instances that host upstream
+ of the submodules are not prepared for.
+
+ * Fix unnecessarily waste in the idiomatic use of ': ${VAR=default}'
+ to set the default value, without enclosing it in double quotes.
+
+ * Some platform-specific code had non-ANSI strict declarations of C
+ functions that do not take any parameters, which has been
+ corrected.
+
+ * The internal code used to show local timezone offset is not
+ prepared to handle timestamps beyond year 2100, and gave a
+ bogus offset value to the caller. Use a more benign looking
+ +0000 instead and let "git log" going in such a case, instead
+ of aborting.
+
+ * One among four invocations of readlink(1) in our test suite has
+ been rewritten so that the test can run on systems without the
+ command (others are in valgrind test framework and t9802).
+
+ * t/perf needs /usr/bin/time with GNU extension; the invocation of it
+ is updated to "gtime" on Darwin.
+
+ * A bug, which caused "git p4" while running under verbose mode to
+ report paths that are omitted due to branch prefix incorrectly, has
+ been fixed; the command said "Ignoring file outside of prefix" for
+ paths that are _inside_.
+
+ * The top level documentation "git help git" still pointed at the
+ documentation set hosted at now-defunct google-code repository.
+ Update it to point to https://git.github.io/htmldocs/git.html
+ instead.
Also contains minor documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.9.2.txt b/Documentation/RelNotes/2.9.2.txt
new file mode 100644
index 0000000000..2620003dcf
--- /dev/null
+++ b/Documentation/RelNotes/2.9.2.txt
@@ -0,0 +1,13 @@
+Git v2.9.2 Release Notes
+========================
+
+Fixes since v2.9.1
+------------------
+
+ * A fix merged to v2.9.1 had a few tests that are not meant to be
+ run on platforms without 64-bit long, which caused unnecessary
+ test failures on them because we didn't detect the platform and
+ skip them. These tests are now skipped on platforms that they
+ are not applicable to.
+
+No other change is included in this update.
diff --git a/Documentation/RelNotes/2.9.3.txt b/Documentation/RelNotes/2.9.3.txt
new file mode 100644
index 0000000000..695b86f612
--- /dev/null
+++ b/Documentation/RelNotes/2.9.3.txt
@@ -0,0 +1,170 @@
+Git v2.9.3 Release Notes
+========================
+
+Fixes since v2.9.2
+------------------
+
+ * A helper function that takes the contents of a commit object and
+ finds its subject line did not ignore leading blank lines, as is
+ commonly done by other codepaths. Make it ignore leading blank
+ lines to match.
+
+ * Git does not know what the contents in the index should be for a
+ path added with "git add -N" yet, so "git grep --cached" should not
+ show hits (or show lack of hits, with -L) in such a path, but that
+ logic does not apply to "git grep", i.e. searching in the working
+ tree files. But we did so by mistake, which has been corrected.
+
+ * "git rebase -i --autostash" did not restore the auto-stashed change
+ when the operation was aborted.
+
+ * "git commit --amend --allow-empty-message -S" for a commit without
+ any message body could have misidentified where the header of the
+ commit object ends.
+
+ * More mark-up updates to typeset strings that are expected to
+ literally typed by the end user in fixed-width font.
+
+ * For a long time, we carried an in-code comment that said our
+ colored output would work only when we use fprintf/fputs on
+ Windows, which no longer is the case for the past few years.
+
+ * "gc.autoPackLimit" when set to 1 should not trigger a repacking
+ when there is only one pack, but the code counted poorly and did
+ so.
+
+ * One part of "git am" had an oddball helper function that called
+ stuff from outside "his" as opposed to calling what we have "ours",
+ which was not gender-neutral and also inconsistent with the rest of
+ the system where outside stuff is usuall called "theirs" in
+ contrast to "ours".
+
+ * The test framework learned a new helper test_match_signal to
+ check an exit code from getting killed by an expected signal.
+
+ * "git blame -M" missed a single line that was moved within the file.
+
+ * Fix recently introduced codepaths that are involved in parallel
+ submodule operations, which gave up on reading too early, and
+ could have wasted CPU while attempting to write under a corner
+ case condition.
+
+ * "git grep -i" has been taught to fold case in non-ascii locales
+ correctly.
+
+ * A test that unconditionally used "mktemp" learned that the command
+ is not necessarily available everywhere.
+
+ * "git blame file" allowed the lineage of lines in the uncommitted,
+ unadded contents of "file" to be inspected, but it refused when
+ "file" did not appear in the current commit. When "file" was
+ created by renaming an existing file (but the change has not been
+ committed), this restriction was unnecessarily tight.
+
+ * "git add -N dir/file && git write-tree" produced an incorrect tree
+ when there are other paths in the same directory that sorts after
+ "file".
+
+ * "git fetch http://user:pass@host/repo..." scrubbed the userinfo
+ part, but "git push" didn't.
+
+ * An age old bug that caused "git diff --ignore-space-at-eol"
+ misbehave has been fixed.
+
+ * "git notes merge" had a code to see if a path exists (and fails if
+ it does) and then open the path for writing (when it doesn't).
+ Replace it with open with O_EXCL.
+
+ * "git pack-objects" and "git index-pack" mostly operate with off_t
+ when talking about the offset of objects in a packfile, but there
+ were a handful of places that used "unsigned long" to hold that
+ value, leading to an unintended truncation.
+
+ * Recent update to "git daemon" tries to enable the socket-level
+ KEEPALIVE, but when it is spawned via inetd, the standard input
+ file descriptor may not necessarily be connected to a socket.
+ Suppress an ENOTSOCK error from setsockopt().
+
+ * Recent FreeBSD stopped making perl available at /usr/bin/perl;
+ switch the default the built-in path to /usr/local/bin/perl on not
+ too ancient FreeBSD releases.
+
+ * "git status" learned to suggest "merge --abort" during a conflicted
+ merge, just like it already suggests "rebase --abort" during a
+ conflicted rebase.
+
+ * The .c/.h sources are marked as such in our .gitattributes file so
+ that "git diff -W" and friends would work better.
+
+ * Existing autoconf generated test for the need to link with pthread
+ library did not check all the functions from pthread libraries;
+ recent FreeBSD has some functions in libc but not others, and we
+ mistakenly thought linking with libc is enough when it is not.
+
+ * Allow http daemon tests in Travis CI tests.
+
+ * Users of the parse_options_concat() API function need to allocate
+ extra slots in advance and fill them with OPT_END() when they want
+ to decide the set of supported options dynamically, which makes the
+ code error-prone and hard to read. This has been corrected by tweaking
+ the API to allocate and return a new copy of "struct option" array.
+
+ * The use of strbuf in "git rm" to build filename to remove was a bit
+ suboptimal, which has been fixed.
+
+ * "git commit --help" said "--no-verify" is only about skipping the
+ pre-commit hook, and failed to say that it also skipped the
+ commit-msg hook.
+
+ * "git merge" in Git v2.9 was taught to forbid merging an unrelated
+ lines of history by default, but that is exactly the kind of thing
+ the "--rejoin" mode of "git subtree" (in contrib/) wants to do.
+ "git subtree" has been taught to use the "--allow-unrelated-histories"
+ option to override the default.
+
+ * The build procedure for "git persistent-https" helper (in contrib/)
+ has been updated so that it can be built with more recent versions
+ of Go.
+
+ * There is an optimization used in "git diff $treeA $treeB" to borrow
+ an already checked-out copy in the working tree when it is known to
+ be the same as the blob being compared, expecting that open/mmap of
+ such a file is faster than reading it from the object store, which
+ involves inflating and applying delta. This however kicked in even
+ when the checked-out copy needs to go through the convert-to-git
+ conversion (including the clean filter), which defeats the whole
+ point of the optimization. The optimization has been disabled when
+ the conversion is necessary.
+
+ * "git -c grep.patternType=extended log --basic-regexp" misbehaved
+ because the internal API to access the grep machinery was not
+ designed well.
+
+ * Windows port was failing some tests in t4130, due to the lack of
+ inum in the returned values by its lstat(2) emulation.
+
+ * The characters in the label shown for tags/refs for commits in
+ "gitweb" output are now properly escaped for proper HTML output.
+
+ * FreeBSD can lie when asked mtime of a directory, which made the
+ untracked cache code to fall back to a slow-path, which in turn
+ caused tests in t7063 to fail because it wanted to verify the
+ behaviour of the fast-path.
+
+ * Squelch compiler warnings for netmalloc (in compat/) library.
+
+ * The API documentation for hashmap was unclear if hashmap_entry
+ can be safely discarded without any other consideration. State
+ that it is safe to do so.
+
+ * Not-so-recent rewrite of "git am" that started making internal
+ calls into the commit machinery had an unintended regression, in
+ that no matter how many seconds it took to apply many patches, the
+ resulting committer timestamp for the resulting commits were all
+ the same.
+
+ * "git difftool <paths>..." started in a subdirectory failed to
+ interpret the paths relative to that directory, which has been
+ fixed.
+
+Also contains minor documentation updates and code clean-ups.
diff --git a/Documentation/RelNotes/2.9.4.txt b/Documentation/RelNotes/2.9.4.txt
new file mode 100644
index 0000000000..01e864278b
--- /dev/null
+++ b/Documentation/RelNotes/2.9.4.txt
@@ -0,0 +1,83 @@
+Git v2.9.4 Release Notes
+========================
+
+Fixes since v2.9.3
+------------------
+
+ * There are certain house-keeping tasks that need to be performed at
+ the very beginning of any Git program, and programs that are not
+ built-in commands had to do them exactly the same way as "git"
+ potty does. It was easy to make mistakes in one-off standalone
+ programs (like test helpers). A common "main()" function that
+ calls cmd_main() of individual program has been introduced to
+ make it harder to make mistakes.
+
+ * "git merge" with renormalization did not work well with
+ merge-recursive, due to "safer crlf" conversion kicking in when it
+ shouldn't.
+
+ * The reflog output format is documented better, and a new format
+ --date=unix to report the seconds-since-epoch (without timezone)
+ has been added.
+
+ * "git push --force-with-lease" already had enough logic to allow
+ ensuring that such a push results in creation of a ref (i.e. the
+ receiving end did not have another push from sideways that would be
+ discarded by our force-pushing), but didn't expose this possibility
+ to the users. It does so now.
+
+ * "import-tars" fast-import script (in contrib/) used to ignore a
+ hardlink target and replaced it with an empty file, which has been
+ corrected to record the same blob as the other file the hardlink is
+ shared with.
+
+ * "git mv dir non-existing-dir/" did not work in some environments
+ the same way as existing mainstream platforms. The code now moves
+ "dir" to "non-existing-dir", without relying on rename("A", "B/")
+ that strips the trailing slash of '/'.
+
+ * The "t/" hierarchy is prone to get an unusual pathname; "make test"
+ has been taught to make sure they do not contain paths that cannot
+ be checked out on Windows (and the mechanism can be reusable to
+ catch pathnames that are not portable to other platforms as need
+ arises).
+
+ * When "git merge-recursive" works on history with many criss-cross
+ merges in "verbose" mode, the names the command assigns to the
+ virtual merge bases could have overwritten each other by unintended
+ reuse of the same piece of memory.
+
+ * "git checkout --detach <branch>" used to give the same advice
+ message as that is issued when "git checkout <tag>" (or anything
+ that is not a branch name) is given, but asking with "--detach" is
+ an explicit enough sign that the user knows what is going on. The
+ advice message has been squelched in this case.
+
+ * "git difftool" by default ignores the error exit from the backend
+ commands it spawns, because often they signal that they found
+ differences by exiting with a non-zero status code just like "diff"
+ does; the exit status codes 126 and above however are special in
+ that they are used to signal that the command is not executable,
+ does not exist, or killed by a signal. "git difftool" has been
+ taught to notice these exit status codes.
+
+ * On Windows, help.browser configuration variable used to be ignored,
+ which has been corrected.
+
+ * The "git -c var[=val] cmd" facility to append a configuration
+ variable definition at the end of the search order was described in
+ git(1) manual page, but not in git-config(1), which was more likely
+ place for people to look for when they ask "can I make a one-shot
+ override, and if so how?"
+
+ * The tempfile (hence its user lockfile) API lets the caller to open
+ a file descriptor to a temporary file, write into it and then
+ finalize it by first closing the filehandle and then either
+ removing or renaming the temporary file. When the process spawns a
+ subprocess after obtaining the file descriptor, and if the
+ subprocess has not exited when the attempt to remove or rename is
+ made, the last step fails on Windows, because the subprocess has
+ the file descriptor still open. Open tempfile with O_CLOEXEC flag
+ to avoid this (on Windows, this is mapped to O_NOINHERIT).
+
+Also contains minor documentation updates and code clean-ups.
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e8ad978824..08352deaae 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -121,6 +121,16 @@ its behaviour. Try to make sure your explanation can be understood
without external resources. Instead of giving a URL to a mailing list
archive, summarize the relevant points of the discussion.
+If you want to reference a previous commit in the history of a stable
+branch, use the format "abbreviated sha1 (subject, date)",
+with the subject enclosed in a pair of double-quotes, like this:
+
+ Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
+ noticed that ...
+
+The "Copy commit summary" command of gitk can be used to obtain this
+format.
+
(3) Generate your patch using Git tools out of your commits.
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 626243f61a..e78293b6db 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -140,7 +140,7 @@ boolean::
false;; Boolean false can be spelled as `no`, `off`,
`false`, or `0`.
+
-When converting value to the canonical form using '--bool' type
+When converting value to the canonical form using `--bool` type
specifier; 'git config' will ensure that the output is "true" or
"false" (spelled in lowercase).
@@ -150,27 +150,34 @@ integer::
1024", "by 1024x1024", etc.
color::
- The value for a variables that takes a color is a list of
- colors (at most two) and attributes (at most one), separated
- by spaces. The colors accepted are `normal`, `black`,
- `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and
- `white`; the attributes are `bold`, `dim`, `ul`, `blink` and
- `reverse`. The first color given is the foreground; the
- second is the background. The position of the attribute, if
- any, doesn't matter. Attributes may be turned off specifically
- by prefixing them with `no` (e.g., `noreverse`, `noul`, etc).
-+
-Colors (foreground and background) may also be given as numbers between
-0 and 255; these use ANSI 256-color mode (but note that not all
-terminals may support this). If your terminal supports it, you may also
-specify 24-bit RGB values as hex, like `#ff0ab3`.
-+
-The attributes are meant to be reset at the beginning of each item
-in the colored output, so setting color.decorate.branch to `black`
-will paint that branch name in a plain `black`, even if the previous
-thing on the same output line (e.g. opening parenthesis before the
-list of branch names in `log --decorate` output) is set to be
-painted with `bold` or some other attribute.
+ The value for a variable that takes a color is a list of
+ colors (at most two, one for foreground and one for background)
+ and attributes (as many as you want), separated by spaces.
++
+The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`,
+`blue`, `magenta`, `cyan` and `white`. The first color given is the
+foreground; the second is the background.
++
+Colors may also be given as numbers between 0 and 255; these use ANSI
+256-color mode (but note that not all terminals may support this). If
+your terminal supports it, you may also specify 24-bit RGB values as
+hex, like `#ff0ab3`.
++
+The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`,
+`italic`, and `strike` (for crossed-out or "strikethrough" letters).
+The position of any attributes with respect to the colors
+(before, after, or in between), doesn't matter. Specific attributes may
+be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`,
+`no-ul`, etc).
++
+For git's pre-defined color slots, the attributes are meant to be reset
+at the beginning of each item in the colored output. So setting
+`color.decorate.branch` to `black` will paint that branch name in a
+plain `black`, even if the previous thing on the same output line (e.g.
+opening parenthesis before the list of branch names in `log --decorate`
+output) is set to be painted with `bold` or some other attribute.
+However, custom log formats may do more complicated and layered
+coloring, and the negated forms may be useful there.
pathname::
A variable that takes a pathname value can be given a
@@ -405,13 +412,11 @@ file with mixed line endings would be reported by the `core.safecrlf`
mechanism.
core.autocrlf::
- Setting this variable to "true" is almost the same as setting
- the `text` attribute to "auto" on all files except that text
- files are not guaranteed to be normalized: files that contain
- `CRLF` in the repository will not be touched. Use this
- setting if you want to have `CRLF` line endings in your
- working directory even though the repository does not have
- normalized line endings. This variable can be set to 'input',
+ Setting this variable to "true" is the same as setting
+ the `text` attribute to "auto" on all files and core.eol to "crlf".
+ Set to true if you want to have `CRLF` line endings in your
+ working directory and the repository has LF line endings.
+ This variable can be set to 'input',
in which case no output conversion is performed.
core.symlinks::
@@ -443,6 +448,13 @@ specify that no proxy be used for a given domain pattern.
This is useful for excluding servers inside a firewall from
proxy use, while defaulting to a common proxy for external domains.
+core.sshCommand::
+ If this variable is set, `git fetch` and `git push` will
+ use the specified command instead of `ssh` when they need to
+ connect to a remote system. The command is in the same form as
+ the `GIT_SSH_COMMAND` environment variable and is overridden
+ when the environment variable is set.
+
core.ignoreStat::
If true, Git will avoid using lstat() calls to detect if files have
changed by setting the "assume-unchanged" bit for those tracked files
@@ -481,7 +493,7 @@ core.worktree::
If `GIT_COMMON_DIR` environment variable is set, core.worktree
is ignored and not used for determining the root of 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.
@@ -779,7 +791,7 @@ core.abbrev::
add.ignoreErrors::
add.ignore-errors (deprecated)::
Tells 'git add' to continue adding files when some files cannot be
- added due to indexing errors. Equivalent to the '--ignore-errors'
+ added due to indexing errors. Equivalent to the `--ignore-errors`
option of linkgit:git-add[1]. `add.ignore-errors` is deprecated,
as it does not follow the usual naming convention for configuration
variables.
@@ -805,9 +817,9 @@ from the original current directory. See linkgit:git-rev-parse[1].
am.keepcr::
If true, git-am will call git-mailsplit for patches in mbox format
- with parameter '--keep-cr'. In this case git-mailsplit will
+ with parameter `--keep-cr`. In this case git-mailsplit will
not remove `\r` from lines ending with `\r\n`. Can be overridden
- by giving '--no-keep-cr' from the command line.
+ by giving `--no-keep-cr` from the command line.
See linkgit:git-am[1], linkgit:git-mailsplit[1].
am.threeWay::
@@ -820,7 +832,7 @@ am.threeWay::
apply.ignoreWhitespace::
When set to 'change', tells 'git apply' to ignore changes in
- whitespace, in the same way as the '--ignore-space-change'
+ whitespace, in the same way as the `--ignore-space-change`
option.
When set to one of: no, none, never, false tells 'git apply' to
respect all whitespace differences.
@@ -828,7 +840,7 @@ apply.ignoreWhitespace::
apply.whitespace::
Tells 'git apply' how to handle whitespaces, in the same way
- as the '--whitespace' option. See linkgit:git-apply[1].
+ as the `--whitespace` option. See linkgit:git-apply[1].
branch.autoSetupMerge::
Tells 'git branch' and 'git checkout' to set up new branches
@@ -930,7 +942,7 @@ browser.<tool>.cmd::
browser.<tool>.path::
Override the path for the given tool that may be used to
- browse HTML help (see '-w' option in linkgit:git-help[1]) or a
+ browse HTML help (see `-w` option in linkgit:git-help[1]) or a
working repository in gitweb (see linkgit:git-instaweb[1]).
clean.requireForce::
@@ -941,7 +953,8 @@ color.branch::
A boolean to enable/disable color in the output of
linkgit:git-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.
+ only when the output is to a terminal. If unset, then the
+ value of `color.ui` is used (`auto` by default).
color.branch.<slot>::
Use customized color for branch coloration. `<slot>` is one of
@@ -956,7 +969,8 @@ color.diff::
linkgit:git-log[1], and linkgit:git-show[1] will use color
for all patches. If it is set to `true` or `auto`, those
commands will only use color when output is to the terminal.
- Defaults to false.
+ If unset, then the value of `color.ui` is used (`auto` by
+ default).
+
This does not affect linkgit:git-format-patch[1] or the
'git-diff-{asterisk}' plumbing commands. Can be overridden on the
@@ -979,7 +993,8 @@ color.decorate.<slot>::
color.grep::
When set to `always`, always highlight matches. When `false` (or
`never`), never. When set to `true` or `auto`, use color only
- when the output is written to the terminal. Defaults to `false`.
+ when the output is written to the terminal. If unset, then the
+ value of `color.ui` is used (`auto` by default).
color.grep.<slot>::
Use customized color for grep colorization. `<slot>` specifies which
@@ -1012,7 +1027,8 @@ color.interactive::
and displays (such as those used by "git-add --interactive" and
"git-clean --interactive"). When false (or `never`), never.
When set to `true` or `auto`, use colors only when the output is
- to the terminal. Defaults to false.
+ to the terminal. If unset, then the value of `color.ui` is
+ used (`auto` by default).
color.interactive.<slot>::
Use customized color for 'git add --interactive' and 'git clean
@@ -1028,13 +1044,15 @@ color.showBranch::
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.
+ only when the output is to a terminal. If unset, then the
+ value of `color.ui` is used (`auto` by default).
color.status::
A boolean to enable/disable color in the output of
linkgit:git-status[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.
+ only when the output is to a terminal. If unset, then the
+ value of `color.ui` is used (`auto` by default).
color.status.<slot>::
Use customized color for status colorization. `<slot>` is
@@ -1229,6 +1247,11 @@ fetch.prune::
If true, fetch will automatically behave as if the `--prune`
option was given on the command line. See also `remote.<name>.prune`.
+fetch.output::
+ Control how ref update status is printed. Valid values are
+ `full` and `compact`. Default value is `full`. See section
+ OUTPUT in linkgit:git-fetch[1] for detail.
+
format.attach::
Enable multipart/mixed attachments as the default for
'format-patch'. The value can also be a double quoted string
@@ -1236,6 +1259,16 @@ format.attach::
value as the boundary. See the --attach option in
linkgit:git-format-patch[1].
+format.from::
+ Provides the default value for the `--from` option to format-patch.
+ Accepts a boolean value, or a name and email address. If false,
+ format-patch defaults to `--no-from`, using commit authors directly in
+ the "From:" field of patch mails. If true, format-patch defaults to
+ `--from`, using your committer identity in the "From:" field of patch
+ mails and including a "From:" field in the body of the patch mail if
+ different. If set to a non-boolean value, format-patch uses that
+ value instead of your committer identity. Defaults to false.
+
format.numbered::
A boolean which can enable or disable sequence numbers in patch
subjects. It defaults to "auto" which enables it only if there
@@ -1339,7 +1372,7 @@ fsck.skipList::
gc.aggressiveDepth::
The depth parameter used in the delta compression
algorithm used by 'git gc --aggressive'. This defaults
- to 250.
+ to 50.
gc.aggressiveWindow::
The window size parameter used in the delta compression
@@ -1429,9 +1462,9 @@ gitcvs.logFile::
gitcvs.usecrlfattr::
If true, the server will look up the end-of-line conversion
- attributes for files to determine the '-k' modes to use. If
+ attributes for files to determine the `-k` modes to use. If
the attributes force Git to treat a file as text,
- the '-k' mode will be left blank so CVS clients will
+ the `-k` mode will be left blank so CVS clients will
treat it as text. If they suppress text conversion, the file
will be set with '-kb' mode, which suppresses any newline munging
the client might otherwise do. If the attributes do not allow
@@ -1501,16 +1534,16 @@ gitweb.snapshot::
See linkgit:gitweb.conf[5] for description.
grep.lineNumber::
- If set to true, enable '-n' option by default.
+ If set to true, enable `-n` option by default.
grep.patternType::
Set the default matching behavior. Using a value of 'basic', 'extended',
- 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp',
- '--fixed-strings', or '--perl-regexp' option accordingly, while the
+ 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
+ `--fixed-strings`, or `--perl-regexp` option accordingly, while the
value 'default' will return to the default matching behavior.
grep.extendedRegexp::
- If set to true, enable '--extended-regexp' option by default. This
+ If set to true, enable `--extended-regexp` option by default. This
option is ignored when the `grep.patternType` option is set to a value
other than 'default'.
@@ -1967,7 +2000,7 @@ log.decorate::
specified, the full ref name (including prefix) will be printed.
If 'auto' is specified, then if the output is going to a terminal,
the ref names are shown as if 'short' were given, otherwise no ref
- names are shown. This is the same as the '--decorate' option
+ names are shown. This is the same as the `--decorate` option
of the `git log`.
log.follow::
@@ -2350,16 +2383,16 @@ new default).
--
push.followTags::
- If set to true enable '--follow-tags' option by default. You
+ If set to true enable `--follow-tags` option by default. You
may override this configuration at time of push by specifying
- '--no-follow-tags'.
+ `--no-follow-tags`.
push.gpgSign::
May be set to a boolean value, or the string 'if-asked'. A true
- value causes all pushes to be GPG signed, as if '--signed' is
+ value causes all pushes to be GPG signed, as if `--signed` is
passed to linkgit:git-push[1]. The string 'if-asked' causes
pushes to be signed if the server supports it, as if
- '--signed=if-asked' is passed to 'git push'. A false value may
+ `--signed=if-asked` is passed to 'git push'. A false value may
override a value from a lower-priority config file. An explicit
command-line flag always overrides this config option.
@@ -2382,7 +2415,7 @@ rebase.stat::
rebase. False by default.
rebase.autoSquash::
- If set to true enable '--autosquash' option by default.
+ If set to true enable `--autosquash` option by default.
rebase.autoStash::
When set to true, automatically create a temporary stash
@@ -2410,8 +2443,13 @@ rebase.instructionFormat
receive.advertiseAtomic::
By default, git-receive-pack will advertise the atomic push
- capability to its clients. If you don't want to this capability
- to be advertised, set this variable to false.
+ capability to its clients. If you don't want to advertise this
+ capability, set this variable to false.
+
+receive.advertisePushOptions::
+ By default, git-receive-pack will advertise the push options
+ capability to its clients. If you don't want to advertise this
+ capability, set this variable to false.
receive.autogc::
By default, git-receive-pack will run "git-gc --auto" after
@@ -2466,6 +2504,15 @@ receive.fsck.skipList::
can be safely ignored such as invalid committer email addresses.
Note: corrupt objects cannot be skipped with this setting.
+receive.keepAlive::
+ After receiving the pack from the client, `receive-pack` may
+ produce no output (if `--quiet` was specified) while processing
+ the pack, causing some networks to drop the TCP connection.
+ With this option set, if `receive-pack` does not transmit
+ any data in this phase for `receive.keepAlive` seconds, it will
+ send a short keepalive packet. The default is 5 seconds; set
+ to 0 to disable keepalives entirely.
+
receive.unpackLimit::
If the number of objects received in a push is below this
limit then the objects will be unpacked into loose object
@@ -2476,6 +2523,12 @@ receive.unpackLimit::
especially on slow filesystems. If not set, the value of
`transfer.unpackLimit` is used instead.
+receive.maxInputSize::
+ If the size of the incoming pack stream is larger than this
+ limit, then git-receive-pack will error out, instead of
+ accepting the pack file. If not set or set to 0, then the size
+ is unlimited.
+
receive.denyDeletes::
If set to true, git-receive-pack will deny a ref update that deletes
the ref. Use this to prevent such a ref deletion via a push.
@@ -2806,6 +2859,18 @@ submodule.fetchJobs::
in parallel. A value of 0 will give some reasonable default.
If unset, it defaults to 1.
+submodule.alternateLocation::
+ Specifies how the submodules obtain alternates when submodules are
+ cloned. Possible values are `no`, `superproject`.
+ By default `no` is assumed, which doesn't add references. When the
+ value is set to `superproject` the submodule to be cloned computes
+ its alternates location relative to the superprojects alternate.
+
+submodule.alternateErrorStrategy
+ Specifies how to treat errors with the alternates for a submodule
+ as computed via `submodule.alternateLocation`. Possible values are
+ `ignore`, `info`, `die`. Default is `die`.
+
tag.forceSignAnnotated::
A boolean to specify whether annotated tags created should be GPG signed.
If `--annotate` is specified on the command line, it takes
@@ -2892,6 +2957,21 @@ uploadpack.keepAlive::
`uploadpack.keepAlive` seconds. Setting this option to 0
disables keepalive packets entirely. The default is 5 seconds.
+uploadpack.packObjectsHook::
+ If this option is set, when `upload-pack` would run
+ `git pack-objects` to create a packfile for a client, it will
+ run this shell command instead. The `pack-objects` command and
+ arguments it _would_ have run (including the `git pack-objects`
+ at the beginning) are appended to the shell command. The stdin
+ and stdout of the hook are treated as if `pack-objects` itself
+ was run. I.e., `upload-pack` will feed input intended for
+ `pack-objects` to the hook, and expects a completed packfile on
+ stdout.
++
+Note that this configuration variable is ignored if it is seen in the
+repository-level config (this is a safety measure against fetching from
+untrusted repositories).
+
url.<base>.insteadOf::
Any URL that starts with this value will be rewritten to
start, instead, with <base>. In cases where some site serves a
diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index ad368acda6..b27a38f896 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -105,7 +105,7 @@ diff.orderFile::
diff.renameLimit::
The number of files to consider when performing the copy/rename
- detection; equivalent to the 'git diff' option '-l'.
+ detection; equivalent to the 'git diff' option `-l`.
diff.renames::
Whether and how Git detects renames. If set to "false",
@@ -122,10 +122,11 @@ diff.suppressBlankEmpty::
diff.submodule::
Specify the format in which differences in submodules are
- shown. The "log" format lists the commits in the range like
- linkgit:git-submodule[1] `summary` does. The "short" format
- format just shows the names of the commits at the beginning
- and end of the range. Defaults to short.
+ shown. The "short" format just shows the names of the commits
+ at the beginning and end of the range. The "log" format lists
+ the commits in the range like linkgit:git-submodule[1] `summary`
+ does. The "diff" format shows an inline diff of the changed
+ contents of the submodule. Defaults to "short".
diff.wordRegex::
A POSIX Extended Regular Expression used to determine what is a "word"
diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index 85b08909ce..cf5262622f 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -46,11 +46,11 @@ That is, from the left to the right:
. sha1 for "dst"; 0\{40\} if creation, unmerged or "look at work tree".
. a space.
. status, followed by optional "score" number.
-. a tab or a NUL when '-z' option is used.
+. a tab or a NUL when `-z` option is used.
. path for "src"
-. a tab or a NUL when '-z' option is used; only exists for C or R.
+. a tab or a NUL when `-z` option is used; only exists for C or R.
. path for "dst"; only exists for C or R.
-. an LF or a NUL when '-z' option is used, to terminate the record.
+. an LF or a NUL when `-z` option is used, to terminate the record.
Possible status letters are:
@@ -86,7 +86,7 @@ diff format for merges
----------------------
"git-diff-tree", "git-diff-files" and "git-diff --raw"
-can take '-c' or '--cc' option
+can take `-c` or `--cc` option
to generate diff output also for merge commits. The output differs
from the format described above in the following way:
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index c91afee21c..d2a7ff56e8 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -2,7 +2,7 @@ Generating patches with -p
--------------------------
When "git-diff-index", "git-diff-tree", or "git-diff-files" are run
-with a '-p' option, "git diff" without the '--raw' option, or
+with a `-p` option, "git diff" without the `--raw` option, or
"git log" with the "-p" option, they
do not produce the output described above; instead they produce a
patch file. You can customize the creation of such patches via the
@@ -114,11 +114,11 @@ index fabadb8,cc95eb0..4866510
------------
1. It is preceded with a "git diff" header, that looks like
- this (when '-c' option is used):
+ this (when `-c` option is used):
diff --combined file
+
-or like this (when '--cc' option is used):
+or like this (when `--cc` option is used):
diff --cc file
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 0364061a4a..2d77a19626 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -205,13 +205,16 @@ any of those replacements occurred.
of the `--diff-filter` option on what the status letters mean.
--submodule[=<format>]::
- Specify how differences in submodules are shown. When `--submodule`
- or `--submodule=log` is given, the 'log' format is used. This format lists
- the commits in the range like linkgit:git-submodule[1] `summary` does.
- Omitting the `--submodule` option or specifying `--submodule=short`,
- uses the 'short' format. This format just shows the names of the commits
- at the beginning and end of the range. Can be tweaked via the
- `diff.submodule` configuration variable.
+ Specify how differences in submodules are shown. When specifying
+ `--submodule=short` the 'short' format is used. This format just
+ shows the names of the commits at the beginning and end of the range.
+ When `--submodule` or `--submodule=log` is specified, the 'log'
+ format is used. This format lists the commits in the range like
+ linkgit:git-submodule[1] `summary` does. When `--submodule=diff`
+ is specified, the 'diff' format is used. This format shows an
+ inline diff of the changes in the submodule contents between the
+ commit range. Defaults to `diff.submodule` or the 'short' format
+ if the config option is unset.
--color[=<when>]::
Show colored diff.
@@ -414,6 +417,9 @@ ifndef::git-format-patch[]
paths are selected if there is any file that matches
other criteria in the comparison; if there is no file
that matches other criteria, nothing is selected.
++
+Also, these upper-case letters can be downcased to exclude. E.g.
+`--diff-filter=ad` excludes added and deleted paths.
-S<string>::
Look for differences that change the number of occurrences of
@@ -561,5 +567,8 @@ endif::git-format-patch[]
--no-prefix::
Do not show any source or destination prefix.
+--line-prefix=<prefix>::
+ Prepend an additional prefix to every line of output.
+
For more detailed explanation on these common options, see also
linkgit:gitdiffcore[7].
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index b05a8341e8..9eab1f5fa4 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -88,7 +88,7 @@ ifndef::git-pull[]
to whatever else would otherwise be fetched. Using this
option alone does not subject tags to pruning, even if --prune
is used (though tags may be pruned anyway if they are also the
- destination of an explicit refspec; see '--prune').
+ destination of an explicit refspec; see `--prune`).
--recurse-submodules[=yes|on-demand|no]::
This option controls if and under what conditions new commits of
@@ -110,7 +110,7 @@ ifndef::git-pull[]
--no-recurse-submodules::
Disable recursive fetching of submodules (this has the same effect as
- using the '--recurse-submodules=no' option).
+ using the `--recurse-submodules=no` option).
--submodule-prefix=<path>::
Prepend <path> to paths printed in informative messages
@@ -137,7 +137,7 @@ endif::git-pull[]
--upload-pack <upload-pack>::
When given, and the repository to fetch from is handled
- by 'git fetch-pack', '--exec=<upload-pack>' is passed to
+ by 'git fetch-pack', `--exec=<upload-pack>` is passed to
the command to specify non-default path for the command
run on the other end.
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 6a96a669c2..7ed63dce0b 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -11,7 +11,7 @@ SYNOPSIS
'git add' [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
[--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]
[--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]
- [--] [<pathspec>...]
+ [--chmod=(+|-)x] [--] [<pathspec>...]
DESCRIPTION
-----------
@@ -165,6 +165,11 @@ for "git add --no-all <pathspec>...", i.e. ignored removed files.
be ignored, no matter if they are already present in the work
tree or not.
+--chmod=(+|-)x::
+ Override the executable bit of the added files. The executable
+ bit is only changed in the index, the files on disk are left
+ unchanged.
+
\--::
This option can be used to separate command-line options from
the list of files, (useful when filenames might be mistaken
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 13cdd7f3b6..12879e4029 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -116,7 +116,8 @@ default. You can use `--no-utf8` to override this.
By default the command will try to detect the patch format
automatically. This option allows the user to bypass the automatic
detection and specify the patch format that the patch(es) should be
- interpreted as. Valid formats are mbox, stgit, stgit-series and hg.
+ interpreted as. Valid formats are mbox, mboxrd,
+ stgit, stgit-series and hg.
-i::
--interactive::
@@ -198,12 +199,12 @@ When initially invoking `git am`, you give it the names of the mailboxes
to process. Upon seeing the first patch that does not apply, it
aborts in the middle. You can recover from this in one of two ways:
-. skip the current patch by re-running the command with the '--skip'
+. skip the current patch by re-running the command with the `--skip`
option.
. hand resolve the conflict in the working directory, and update
the index file to bring it into a state that the patch should
- have produced. Then run the command with the '--continue' option.
+ have produced. Then run the command with the `--continue` option.
The command refuses to process new mailboxes until the current
operation is finished, so if you decide to start over from scratch,
diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index d9f960b509..2bb9a577a2 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -358,7 +358,7 @@ OPTIONS
--no-checkout::
+
Do not checkout the new working tree at each iteration of the bisection
-process. Instead just update a special reference named 'BISECT_HEAD' to make
+process. Instead just update a special reference named `BISECT_HEAD` to make
it point to the commit that should be tested.
+
This option may be useful when the test you would perform in each step
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 4a7037f1c8..1fe73448f3 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -39,10 +39,10 @@ named commit). With `--merged`, only branches merged into the named
commit (i.e. the branches whose tip commits are reachable from the named
commit) will be listed. With `--no-merged` only branches not merged into
the named commit will be listed. If the <commit> argument is missing it
-defaults to 'HEAD' (i.e. the tip of the current branch).
+defaults to `HEAD` (i.e. the tip of the current branch).
The command's second form creates a new branch head named <branchname>
-which points to the current 'HEAD', or <start-point> if given.
+which points to the current `HEAD`, or <start-point> if given.
Note that this will create the new branch, but it will not switch the
working tree to it; use "git checkout <newbranch>" to switch to the
@@ -172,7 +172,7 @@ This option is only applicable in non-verbose mode.
+
This behavior is the default when the start point is a remote-tracking branch.
Set the branch.autoSetupMerge configuration variable to `false` if you
-want `git checkout` and `git branch` to always behave as if '--no-track'
+want `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-tracking branch.
diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index eb3d6945a9..204541c690 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -9,18 +9,22 @@ git-cat-file - Provide content or type and size information for repository objec
SYNOPSIS
--------
[verse]
-'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv ) <object>
-'git cat-file' (--batch | --batch-check) [--follow-symlinks]
+'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object>
+'git cat-file' (--batch | --batch-check) [ --textconv | --filters ] [--follow-symlinks]
DESCRIPTION
-----------
In its first form, the command provides the content or the type of an object in
-the repository. The type is required unless '-t' or '-p' is used to find the
-object type, or '-s' is used to find the object size, or '--textconv' is used
-(which implies type "blob").
+the repository. The type is required unless `-t` or `-p` is used to find the
+object type, or `-s` is used to find the object size, or `--textconv` or
+`--filters` is used (which imply type "blob").
In the second form, a list of objects (separated by linefeeds) is provided on
-stdin, and the SHA-1, type, and size of each object is printed on stdout.
+stdin, and the SHA-1, type, and size of each object is printed on stdout. The
+output format can be overridden using the optional `<format>` argument. If
+either `--textconv` or `--filters` was specified, the input is expected to
+list the object names followed by the path name, separated by a single white
+space, so that the appropriate drivers can be determined.
OPTIONS
-------
@@ -54,19 +58,35 @@ OPTIONS
--textconv::
Show the content as transformed by a textconv filter. In this case,
- <object> has be of the form <tree-ish>:<path>, or :<path> in order
- to apply the filter to the content recorded in the index at <path>.
+ <object> has to be of the form <tree-ish>:<path>, or :<path> in
+ order to apply the filter to the content recorded in the index at
+ <path>.
+
+--filters::
+ Show the content as converted by the filters configured in
+ the current working tree for the given <path> (i.e. smudge filters,
+ end-of-line conversion, etc). In this case, <object> has to be of
+ the form <tree-ish>:<path>, or :<path>.
+
+--path=<path>::
+ For use with --textconv or --filters, to allow specifying an object
+ name and a path separately, e.g. when it is difficult to figure out
+ the revision from which the blob came.
--batch::
--batch=<format>::
Print object information and contents for each object provided
- on stdin. May not be combined with any other options or arguments.
- See the section `BATCH OUTPUT` below for details.
+ on stdin. May not be combined with any other options or arguments
+ except `--textconv` or `--filters`, in which case the input lines
+ also need to specify the path, separated by white space. See the
+ section `BATCH OUTPUT` below for details.
--batch-check::
--batch-check=<format>::
Print object information for each object provided on stdin. May
- not be combined with any other options or arguments. See the
+ not be combined with any other options or arguments except
+ `--textconv` or `--filters`, in which case the input lines also
+ need to specify the path, separated by white space. See the
section `BATCH OUTPUT` below for details.
--batch-all-objects::
@@ -144,13 +164,13 @@ respectively print:
OUTPUT
------
-If '-t' is specified, one of the <type>.
+If `-t` is specified, one of the <type>.
-If '-s' is specified, the size of the <object> in bytes.
+If `-s` is specified, the size of the <object> in bytes.
-If '-e' is specified, no output.
+If `-e` is specified, no output.
-If '-p' is specified, the contents of <object> are pretty-printed.
+If `-p` is specified, the contents of <object> are pretty-printed.
If <type> is specified, the raw (though uncompressed) contents of the <object>
will be returned.
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index 91a3622ee4..8611a99120 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -118,8 +118,8 @@ $ git check-ref-format --branch @{-1}
* Determine the reference name to use for a new branch:
+
------------
-$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") ||
-die "we do not like '$newbranch' as a branch name."
+$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
+{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }
------------
GIT
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 5e5273e073..8e2c0662dd 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -157,7 +157,7 @@ of it").
When creating a new branch, set up "upstream" configuration. See
"--track" in linkgit:git-branch[1] for details.
+
-If no '-b' option is given, the name of the new branch will be
+If no `-b` option is given, the name of the new branch will be
derived from the remote-tracking branch, by looking at the local part of
the refspec configured for the corresponding remote, and then stripping
the initial part up to the "*".
@@ -165,7 +165,7 @@ This would tell us to use "hack" as the local branch when branching
off of "origin/hack" (or "remotes/origin/hack", or even
"refs/remotes/origin/hack"). If the given name has no slash, or the above
guessing results in an empty name, the guessing is aborted. You can
-explicitly give a name with '-b' in such a case.
+explicitly give a name with `-b` in such a case.
--no-track::
Do not set up "upstream" configuration, even if the
@@ -419,6 +419,18 @@ $ git reflog -2 HEAD # or
$ git log -g -2 HEAD
------------
+ARGUMENT DISAMBIGUATION
+-----------------------
+
+When there is only one argument given and it is not `--` (e.g. "git
+checkout abc"), and when the argument is both a valid `<tree-ish>`
+(e.g. a branch "abc" exists) and a valid `<pathspec>` (e.g. a file
+or a directory whose name is "abc" exists), Git would usually ask
+you to disambiguate. Because checking out a branch is so common an
+operation, however, "git checkout abc" takes "abc" as a `<tree-ish>`
+in such a situation. Use `git checkout -- <pathspec>` if you want
+to checkout these paths out of the index.
+
EXAMPLES
--------
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index c104a594af..d35d771fc8 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -47,7 +47,7 @@ OPTIONS
For a more complete list of ways to spell commits, see
linkgit:gitrevisions[7].
Sets of commits can be passed but no traversal is done by
- default, as if the '--no-walk' option was specified, see
+ default, as if the `--no-walk` option was specified, see
linkgit:git-rev-list[1]. Note that specifying a range will
feed all <commit>... arguments to a single revision walk
(see a later example that uses 'maint master..next').
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index 51a7e26a8e..03056dad0d 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -16,7 +16,7 @@ DESCRIPTION
Cleans the working tree by recursively removing files that are not
under version control, starting from the current directory.
-Normally, only files unknown to Git are removed, but if the '-x'
+Normally, only files unknown to Git are removed, but if the `-x`
option is specified, ignored files are also removed. This can, for
example, be useful to remove all build products.
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 1b15cd7b16..e316c4bd51 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -90,13 +90,16 @@ If you want to break the dependency of a repository cloned with `-s` on
its source repository, you can simply run `git repack -a` to copy all
objects from the source repository into a pack in the cloned repository.
---reference <repository>::
+--reference[-if-able] <repository>::
If the reference repository is on the local machine,
automatically setup `.git/objects/info/alternates` to
obtain objects from the reference repository. Using
an already existing repository as an alternate will
require fewer objects to be copied from the repository
being cloned, reducing network and local storage costs.
+ When using the `--reference-if-able`, a non existing
+ directory is skipped with a warning instead of aborting
+ the clone.
+
*NOTE*: see the NOTE for the `--shared` option, and also the
`--dissociate` option.
@@ -191,9 +194,8 @@ objects from the source repository into a pack in the cloned repository.
Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the
- tips of all branches. This implies `--shallow-submodules`. If
- you want to have a shallow superproject clone, but full submodules,
- also pass `--no-shallow-submodules`.
+ tips of all branches. If you want to clone submodules shallowly,
+ also pass `--shallow-submodules`.
--[no-]single-branch::
Clone only the history leading to the tip of a single branch,
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index cb69faab68..002dae625e 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -44,7 +44,7 @@ OPTIONS
An existing tree object
-p <parent>::
- Each '-p' indicates the id of a parent commit object.
+ Each `-p` indicates the id of a parent commit object.
-m <message>::
A paragraph in the commit log message. This can be given more than
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index e7049537d9..b0a294d3b5 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -75,7 +75,7 @@ OPTIONS
-c <commit>::
--reedit-message=<commit>::
- Like '-C', but with '-c' the editor is invoked, so that
+ Like '-C', but with `-c` the editor is invoked, so that
the user can further edit the commit message.
--fixup=<commit>::
@@ -260,7 +260,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
staged for other paths. This is the default mode of operation of
'git commit' if any paths are given on the command line,
in which case this option can be omitted.
- If this option is specified together with '--amend', then
+ If this option is specified together with `--amend`, then
no paths need to be specified, which can be used to amend
the last commit without committing changes that have
already been staged.
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index a89c304916..83f86b9231 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -31,29 +31,29 @@ You can query/set/replace/unset options with this command. The name is
actually the section and the key separated by a dot, and the value will be
escaped.
-Multiple lines can be added to an option by using the '--add' option.
+Multiple lines can be added to an option by using the `--add` option.
If you want to update or unset an option which can occur on multiple
lines, a POSIX regexp `value_regex` needs to be given. Only the
existing values that match the regexp are updated or unset. If
you want to handle the lines that do *not* match the regex, just
prepend a single exclamation mark in front (see also <<EXAMPLES>>).
-The type specifier can be either '--int' or '--bool', to make
+The type specifier can be either `--int` or `--bool`, to make
'git config' ensure that the variable(s) are of the given type and
convert the value to the canonical form (simple decimal number for int,
-a "true" or "false" string for bool), or '--path', which does some
-path expansion (see '--path' below). If no type specifier is passed, no
+a "true" or "false" string for bool), or `--path`, which does some
+path expansion (see `--path` below). If no type specifier is passed, no
checks or transformations are performed on the value.
When reading, the values are read from the system, global and
repository local configuration files by default, and options
-'--system', '--global', '--local' and '--file <filename>' can be
+`--system`, `--global`, `--local` and `--file <filename>` can be
used to tell the command to read from only that location (see <<FILES>>).
When writing, the new value is written to the repository local
-configuration file by default, and options '--system', '--global',
-'--file <filename>' can be used to tell the command to write to
-that location (you can say '--local' but that is the default).
+configuration file by default, and options `--system`, `--global`,
+`--file <filename>` can be used to tell the command to write to
+that location (you can say `--local` but that is the default).
This command will fail with non-zero status upon error. Some exit
codes are:
@@ -138,7 +138,7 @@ See also <<FILES>>.
Use the given config file instead of the one specified by GIT_CONFIG.
--blob blob::
- Similar to '--file' but use the given blob instead of a file. E.g.
+ Similar to `--file` but use the given blob instead of a file. E.g.
you can use 'master:.gitmodules' to read values from the file
'.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
section in linkgit:gitrevisions[7] for a more complete list of
@@ -220,7 +220,7 @@ See also <<FILES>>.
-e::
--edit::
Opens an editor to modify the specified config file; either
- '--system', '--global', or repository (default).
+ `--system`, `--global`, or repository (default).
--[no-]includes::
Respect `include.*` directives in config files when looking up
@@ -232,7 +232,7 @@ See also <<FILES>>.
FILES
-----
-If not set explicitly with '--file', there are four files where
+If not set explicitly with `--file`, there are four files where
'git config' will search for configuration options:
$(prefix)/etc/gitconfig::
@@ -263,12 +263,15 @@ The files are read in the order given above, with last value found taking
precedence over values read earlier. When multiple values are taken then all
values of a key from all files will be used.
+You may override individual configuration parameters when running any git
+command by using the `-c` option. See linkgit:git[1] for details.
+
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*.
+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
-variables. The '--global' and the '--system' options will limit the file used
+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-credential-store.txt b/Documentation/git-credential-store.txt
index e3c8f276b1..25fb963f4b 100644
--- a/Documentation/git-credential-store.txt
+++ b/Documentation/git-credential-store.txt
@@ -44,7 +44,7 @@ OPTIONS
FILES
-----
-If not set explicitly with '--file', there are two files where
+If not set explicitly with `--file`, there are two files where
git-credential-store will search for credentials in order of precedence:
~/.git-credentials::
diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
index 00a0679a28..de1ebed67d 100644
--- a/Documentation/git-cvsimport.txt
+++ b/Documentation/git-cvsimport.txt
@@ -22,7 +22,7 @@ DESCRIPTION
deprecated; it does not work with cvsps version 3 and later. If you are
performing a one-shot import of a CVS repository consider using
http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or
-https://github.com/BartMassey/parsecvs[parsecvs].
+http://www.catb.org/esr/cvs-fast-export/[cvs-fast-export].
Imports a CVS repository into Git. It will either create a new
repository, or incrementally import into an existing one.
@@ -74,10 +74,10 @@ OPTIONS
akin to the way 'git clone' uses 'origin' by default.
-o <branch-for-HEAD>::
- When no remote is specified (via -r) the 'HEAD' branch
+ When no remote is specified (via -r) the `HEAD` branch
from CVS is imported to the 'origin' branch within the Git
- repository, as 'HEAD' already has a special meaning for Git.
- When a remote is specified the 'HEAD' branch is named
+ repository, as `HEAD` already has a special meaning for Git.
+ When a remote is specified the `HEAD` branch is named
remotes/<remote>/master mirroring 'git clone' behaviour.
Use this option if you want to import into a different
branch.
@@ -103,7 +103,7 @@ the old cvs2git tool.
-p <options-for-cvsps>::
Additional options for cvsps.
- The options '-u' and '-A' are implicit and should not be used here.
+ The options `-u` and '-A' are implicit and should not be used here.
+
If you need to pass multiple options, separate them with a comma.
@@ -122,7 +122,7 @@ If you need to pass multiple options, separate them with a comma.
-M <regex>::
Attempt to detect merges based on the commit message with a custom
- regex. It can be used with '-m' to enable the default regexes
+ regex. It can be used with `-m` to enable the default regexes
as well. You must escape forward slashes.
+
The regex must capture the source branch name in $1.
@@ -186,7 +186,7 @@ messages, bug-tracking systems, email archives, and the like.
OUTPUT
------
-If '-v' is specified, the script reports what it is doing.
+If `-v` is specified, the script reports what it is doing.
Otherwise, success is indicated the Unix way, i.e. by simply exiting with
a zero exit status.
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index db4d7a917c..a336ae5f6f 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -54,7 +54,7 @@ Print usage information and exit
You can specify a list of allowed directories. If no directories
are given, all are allowed. This is an additional restriction, gitcvs
access still needs to be enabled by the `gitcvs.enabled` config option
-unless '--export-all' was given, too.
+unless `--export-all` was given, too.
DESCRIPTION
@@ -332,7 +332,7 @@ To get a checkout with the Eclipse CVS client:
3. Browse the 'modules' available. It will give you a list of the heads in
the repository. You will not be able to browse the tree from there. Only
the heads.
-4. Pick 'HEAD' when it asks what branch/tag to check out. Untick the
+4. Pick `HEAD` when it asks what branch/tag to check out. Untick the
"launch commit wizard" to avoid committing the .project file.
Protocol notes: If you are using anonymous access via pserver, just select that.
@@ -402,12 +402,12 @@ Exports and tagging (tags and branches) are not supported at this stage.
CRLF Line Ending Conversions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By default the server leaves the '-k' mode blank for all files,
+By default the server leaves the `-k` mode blank for all files,
which causes the CVS client to treat them as a text files, subject
to end-of-line conversion on some platforms.
You can make the server use the end-of-line conversion attributes to
-set the '-k' modes for files by setting the `gitcvs.usecrlfattr`
+set the `-k` modes for files by setting the `gitcvs.usecrlfattr`
config variable. See linkgit:gitattributes[5] for more information
about end-of-line conversion.
@@ -415,9 +415,9 @@ Alternatively, if `gitcvs.usecrlfattr` config is not enabled
or the attributes do not allow automatic detection for a filename, then
the server uses the `gitcvs.allBinary` config for the default setting.
If `gitcvs.allBinary` is set, then file not otherwise
-specified will default to '-kb' mode. Otherwise the '-k' mode
+specified will default to '-kb' mode. Otherwise the `-k` mode
is left blank. But if `gitcvs.allBinary` is set to "guess", then
-the correct '-k' mode will be guessed based on the contents of
+the correct `-k` mode will be guessed based on the contents of
the file.
For best consistency with 'cvs', it is probably best to override the
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index dc20275825..3c91db7bed 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -30,7 +30,7 @@ that service if it is enabled.
It verifies that the directory has the magic file "git-daemon-export-ok", and
it will refuse to export any Git directory that hasn't explicitly been marked
-for export this way (unless the '--export-all' parameter is specified). If you
+for export this way (unless the `--export-all` parameter is specified). If you
pass some directory paths as 'git daemon' arguments, you can further restrict
the offers to a whitelist comprising of those.
@@ -90,10 +90,10 @@ OPTIONS
is not supported, then --listen=hostname is also not supported and
--listen must be given an IPv4 address.
Can be given more than once.
- Incompatible with '--inetd' option.
+ Incompatible with `--inetd` option.
--port=<n>::
- Listen on an alternative port. Incompatible with '--inetd' option.
+ Listen on an alternative port. Incompatible with `--inetd` option.
--init-timeout=<n>::
Timeout (in seconds) between the moment the connection is established
@@ -296,7 +296,7 @@ they correspond to these IP addresses.
selectively enable/disable services per repository::
To enable 'git archive --remote' and disable 'git fetch' against
a repository, have the following in the configuration file in the
- repository (that is the file 'config' next to 'HEAD', 'refs' and
+ repository (that is the file 'config' next to `HEAD`, 'refs' and
'objects').
+
----------------------------------------------------------------
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index c8f28c8c86..e4ac448ff5 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -154,7 +154,7 @@ is found, its name will be output and searching will stop.
If an exact match was not found, 'git describe' will walk back
through the commit history to locate an ancestor commit which
has been tagged. The ancestor's tag will be output along with an
-abbreviation of the input commit-ish's SHA-1. If '--first-parent' was
+abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
specified then the walk will only consider the first parent of each
commit.
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index a86cf62e68..a171506952 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -40,13 +40,13 @@ include::diff-format.txt[]
Operating Modes
---------------
You can choose whether you want to trust the index file entirely
-(using the '--cached' flag) or ask the diff logic to show any files
+(using the `--cached` flag) or ask the diff logic to show any files
that don't match the stat state as being "tentatively changed". Both
of these operations are very useful indeed.
Cached Mode
-----------
-If '--cached' is specified, it allows you to ask:
+If `--cached` is specified, it allows you to ask:
show me the differences between HEAD and the current index
contents (the ones I'd write using 'git write-tree')
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 1439486e40..7870e175b7 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -43,11 +43,11 @@ include::diff-options.txt[]
show tree entry itself as well as subtrees. Implies -r.
--root::
- When '--root' is specified the initial commit will be shown as a big
+ When `--root` is specified the initial commit will be shown as a big
creation event. This is equivalent to a diff against the NULL tree.
--stdin::
- When '--stdin' is specified, the command does not take
+ When `--stdin` is specified, the command does not take
<tree-ish> arguments from the command line. Instead, it
reads lines containing either two <tree>, one <commit>, or a
list of <commit> from its standard input. (Use a single space
@@ -70,13 +70,13 @@ commits (but not trees).
By default, 'git diff-tree --stdin' does not show
differences for merge commits. With this flag, it shows
differences to that commit from all of its parents. See
- also '-c'.
+ also `-c`.
-s::
By default, 'git diff-tree --stdin' shows differences,
- either in machine-readable form (without '-p') or in patch
- form (with '-p'). This output can be suppressed. It is
- only useful with '-v' flag.
+ either in machine-readable form (without `-p`) or in patch
+ form (with `-p`). This output can be suppressed. It is
+ only useful with `-v` flag.
-v::
This flag causes 'git diff-tree --stdin' to also show
@@ -91,17 +91,17 @@ include::pretty-options.txt[]
-c::
This flag changes the way a merge commit is displayed
(which means it is useful only when the command is given
- one <tree-ish>, or '--stdin'). It shows the differences
+ one <tree-ish>, or `--stdin`). It shows the differences
from each of the parents to the merge result simultaneously
instead of showing pairwise diff between a parent and the
- result one at a time (which is what the '-m' option does).
+ result one at a time (which is what the `-m` option does).
Furthermore, it lists only files which were modified
from all parents.
--cc::
This flag changes the way a merge commit patch is displayed,
- in a similar way to the '-c' option. It implies the '-c'
- and '-p' options and further compresses the patch output
+ in a similar way to the `-c` option. It implies the `-c`
+ and `-p` options and further compresses the patch output
by omitting uninteresting hunks whose the contents in the parents
have only two variants and the merge result picks one of them
without modification. When all hunks are uninteresting, the commit
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 333cf6ff91..224fb3090b 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -98,7 +98,7 @@ instead. `--no-symlinks` is the default on Windows.
invoked diff tool returns a non-zero exit code.
+
'git-difftool' will forward the exit code of the invoked tool when
-'--trust-exit-code' is used.
+`--trust-exit-code` is used.
See linkgit:git-diff[1] for the full list of supported options.
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 644df993f9..2b762654bf 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -1056,7 +1056,7 @@ relative-marks::
no-relative-marks::
force::
Act as though the corresponding command-line option with
- a leading '--' was passed on the command line
+ a leading `--` was passed on the command line
(see OPTIONS, above).
import-marks::
@@ -1107,7 +1107,7 @@ options the user may specify to git fast-import itself.
The `<option>` part of the command may contain any of the options
listed in the OPTIONS section that do not change import semantics,
-without the leading '--' and is treated in the same way.
+without the leading `--` and is treated in the same way.
Option commands must be the first commands on the input (not counting
feature commands), to give an option command after any non-option
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index 239623cc24..24417ee3a6 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -41,13 +41,13 @@ OPTIONS
option, then the refs from stdin are processed after those
on the command line.
+
-If '--stateless-rpc' is specified together with this option then
+If `--stateless-rpc` is specified together with this option then
the list of refs must be in packet format (pkt-line). Each ref must
be in a separate packet, and the list must end with a flush packet.
-q::
--quiet::
- Pass '-q' flag to 'git unpack-objects'; this makes the
+ Pass `-q` flag to 'git unpack-objects'; this makes the
cloning process less verbose.
-k::
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index efe56e0808..9e4216999d 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -99,6 +99,57 @@ The latter use of the `remote.<repository>.fetch` values can be
overridden by giving the `--refmap=<refspec>` parameter(s) on the
command line.
+OUTPUT
+------
+
+The output of "git fetch" depends on the transport method used; this
+section describes the output when fetching over the Git protocol
+(either locally or via ssh) and Smart HTTP protocol.
+
+The status of the fetch is output in tabular form, with each line
+representing the status of a single ref. Each line is of the form:
+
+-------------------------------
+ <flag> <summary> <from> -> <to> [<reason>]
+-------------------------------
+
+The status of up-to-date refs is shown only if the --verbose option is
+used.
+
+In compact output mode, specified with configuration variable
+fetch.output, if either entire `<from>` or `<to>` is found in the
+other string, it will be substituted with `*` in the other string. For
+example, `master -> origin/master` becomes `master -> origin/*`.
+
+flag::
+ A single character indicating the status of the ref:
+(space);; for a successfully fetched fast-forward;
+`+`;; for a successful forced update;
+`-`;; for a successfully pruned ref;
+`t`;; for a successful tag update;
+`*`;; for a successfully fetched new ref;
+`!`;; for a ref that was rejected or failed to update; and
+`=`;; for a ref that was up to date and did not need fetching.
+
+summary::
+ For a successfully fetched ref, the summary shows the old and new
+ values of the ref in a form suitable for using as an argument to
+ `git log` (this is `<old>..<new>` in most cases, and
+ `<old>...<new>` for forced non-fast-forward updates).
+
+from::
+ The name of the remote ref being fetched from, minus its
+ `refs/<type>/` prefix. In the case of deletion, the name of
+ the remote ref is "(none)".
+
+to::
+ The name of the local ref being updated, minus its
+ `refs/<type>/` prefix.
+
+reason::
+ A human-readable explanation. In the case of successfully fetched
+ refs, no explanation is needed. For a failed ref, the reason for
+ failure is described.
EXAMPLES
--------
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index bd560d38d9..0a09698c03 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -52,7 +52,7 @@ if different from the rewritten ones, will be stored in the namespace
Note that since this operation is very I/O expensive, it might
be a good idea to redirect the temporary directory off-disk with the
-'-d' option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
+`-d` option, e.g. on tmpfs. Reportedly the speedup is very noticeable.
Filters
@@ -171,7 +171,7 @@ to other tags will be rewritten to point to the underlying commit.
untouched. This switch allow git-filter-branch to ignore such
commits. Though, this switch only applies for commits that have one
and only one parent, it will hence keep merges points. Also, this
- option is not compatible with the use of '--commit-filter'. Though you
+ option is not compatible with the use of `--commit-filter`. Though you
just need to use the function 'git_commit_non_empty_tree "$@"' instead
of the `git commit-tree "$@"` idiom in your commit filter to make that
happen.
@@ -197,7 +197,7 @@ to other tags will be rewritten to point to the underlying commit.
<rev-list options>...::
Arguments for 'git rev-list'. All positive refs included by
these options are rewritten. You may also specify options
- such as '--all', but you must use '--' to separate them from
+ such as `--all`, but you must use `--` to separate them from
the 'git filter-branch' options. Implies <<Remap_to_ancestor>>.
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index d9d406dcfb..f57e69bc83 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -142,7 +142,7 @@ align::
<width> and <position> used instead. For instance,
`%(align:<width>,<position>)`. If the contents length is more
than the width then no alignment is performed. If used with
- '--quote' everything in between %(align:...) and %(end) is
+ `--quote` everything in between %(align:...) and %(end) is
quoted, but if nested then only the topmost level performs
quoting.
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 9624c84a65..9b200b379b 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -19,7 +19,8 @@ SYNOPSIS
[--start-number <n>] [--numbered-files]
[--in-reply-to=Message-Id] [--suffix=.<sfx>]
[--ignore-if-in-upstream]
- [--subject-prefix=Subject-Prefix] [(--reroll-count|-v) <n>]
+ [--rfc] [--subject-prefix=Subject-Prefix]
+ [(--reroll-count|-v) <n>]
[--to=<email>] [--cc=<email>]
[--[no-]cover-letter] [--quiet] [--notes[=<ref>]]
[<common diff options>]
@@ -172,6 +173,11 @@ will want to ensure that threading is disabled for `git send-email`.
allows for useful naming of a patch series, and can be
combined with the `--numbered` option.
+--rfc::
+ Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For
+ Comments"; use this when sending an experimental patch for
+ discussion rather than application.
+
-v <n>::
--reroll-count=<n>::
Mark the series as the <n>-th iteration of the topic. The
diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 84ee92e158..b9f060e3b2 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -11,7 +11,8 @@ SYNOPSIS
[verse]
'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
[--[no-]full] [--strict] [--verbose] [--lost-found]
- [--[no-]dangling] [--[no-]progress] [--connectivity-only] [<object>*]
+ [--[no-]dangling] [--[no-]progress] [--connectivity-only]
+ [--[no-]name-objects] [<object>*]
DESCRIPTION
-----------
@@ -82,6 +83,12 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs
a blob, the contents are written into the file, rather than
its object name.
+--name-objects::
+ When displaying names of reachable objects, in addition to the
+ SHA-1 also display a name that describes *how* they are reachable,
+ compatible with linkgit:git-rev-parse[1], e.g.
+ `HEAD@{1234567890}~25^2:src/`.
+
--[no-]progress::
Progress status is reported on the standard error stream by
default when it is attached to a terminal, unless
@@ -95,7 +102,7 @@ DISCUSSION
git-fsck tests SHA-1 and general object sanity, and it does full tracking
of the resulting reachability and everything else. It prints out any
corruption it finds (missing or bad objects), and if you use the
-'--unreachable' flag it will also print out objects that exist but that
+`--unreachable` flag it will also print out objects that exist but that
aren't reachable from any of the specified head nodes (or the default
set, as mentioned above).
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 40cfe37d00..0ecea6e491 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -41,16 +41,16 @@ CONFIGURATION
-------------
grep.lineNumber::
- If set to true, enable '-n' option by default.
+ If set to true, enable `-n` option by default.
grep.patternType::
Set the default matching behavior. Using a value of 'basic', 'extended',
- 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp',
- '--fixed-strings', or '--perl-regexp' option accordingly, while the
+ 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
+ `--fixed-strings`, or `--perl-regexp` option accordingly, while the
value 'default' will return to the default matching behavior.
grep.extendedRegexp::
- If set to true, enable '--extended-regexp' option by default. This
+ If set to true, enable `--extended-regexp` option by default. This
option is ignored when the `grep.patternType` option is set to a value
other than 'default'.
@@ -59,7 +59,7 @@ grep.threads::
8 threads are used by default (for now).
grep.fullName::
- If set to true, enable '--full-name' option by default.
+ If set to true, enable `--full-name` option by default.
grep.fallbackToNoIndex::
If set to true, fall back to git grep --no-index if git grep
diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt
index 8144527ae0..c1a3e8bf07 100644
--- a/Documentation/git-gui.txt
+++ b/Documentation/git-gui.txt
@@ -35,7 +35,7 @@ blame::
browser::
Start a tree browser showing all files in the specified
- commit (or 'HEAD' by default). Files selected through the
+ commit (or `HEAD` by default). Files selected through the
browser are opened in the blame viewer.
citool::
diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt
index 338b8d61ce..40d328a4b3 100644
--- a/Documentation/git-help.txt
+++ b/Documentation/git-help.txt
@@ -18,10 +18,10 @@ With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
command and a list of the most commonly used Git commands are printed
on the standard output.
-If the option '--all' or '-a' is given, all available commands are
+If the option `--all` or `-a` is given, all available commands are
printed on the standard output.
-If the option '--guide' or '-g' is given, a list of the useful
+If the option `--guide` or `-g` is given, a list of the useful
Git guides is also printed on the standard output.
If a command, or a guide, is given, a manual page for that command or
@@ -176,7 +176,7 @@ Note about git config --global
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that all these configuration variables should probably be set
-using the '--global' flag, for example like this:
+using the `--global` flag, for example like this:
------------------------------------------------
$ git config --global help.format web
diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt
index 2e67362bd4..2aceb6f26d 100644
--- a/Documentation/git-http-push.txt
+++ b/Documentation/git-http-push.txt
@@ -81,13 +81,13 @@ destination side.
exist in the set of remote refs; the ref matched <src>
locally is used as the name of the destination.
-Without '--force', the <src> ref is stored at the remote only if
+Without `--force`, the <src> ref is stored at the remote only if
<dst> does not exist, or <dst> is a proper subset (i.e. an
ancestor) of <src>. This check, known as "fast-forward check",
is performed in order to avoid accidentally overwriting the
remote ref and lose other peoples' commits from there.
-With '--force', the fast-forward check is disabled for all refs.
+With `--force`, the fast-forward check is disabled for all refs.
Optionally, a <ref> parameter can be prefixed with a plus '+' sign
to disable the fast-forward check only on that ref.
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index 7a4e055520..1b4b65d665 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -87,6 +87,8 @@ OPTIONS
Specifying 0 will cause Git to auto-detect the number of CPU's
and use maximum 3 threads.
+--max-input-size=<size>::
+ Die, if the pack is larger than <size>.
Note
----
diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
index a77b901f1d..93d1db6528 100644
--- a/Documentation/git-interpret-trailers.txt
+++ b/Documentation/git-interpret-trailers.txt
@@ -219,7 +219,7 @@ Signed-off-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>
------------
-* Use the '--in-place' option to edit a message file in place:
+* Use the `--in-place` option to edit a message file in place:
+
------------
$ cat msg.txt
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 4a6c47f843..32246fdb00 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -198,6 +198,10 @@ log.showRoot::
`git log -p` output would be shown without a diff attached.
The default is `true`.
+log.showSignature::
+ If `true`, `git log` and related commands will act as if the
+ `--show-signature` option was passed to them.
+
mailmap.*::
See linkgit:git-shortlog[1].
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 75c3f4157d..0d933ac355 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -159,8 +159,7 @@ not accessible in the working tree.
+
<eolattr> is the attribute that is used when checking out or committing,
it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf".
-Note: Currently Git does not support "text=auto eol=lf" or "text=auto eol=crlf",
-that may change in the future.
+Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported.
+
Both the <eolinfo> in the index ("i/<eolinfo>")
and in the working tree ("w/<eolinfo>") are shown for regular files,
@@ -175,7 +174,7 @@ followed by the ("attr/<eolattr>").
Output
------
-'git ls-files' just outputs the filenames unless '--stage' is specified in
+'git ls-files' just outputs the filenames unless `--stage` is specified in
which case it outputs:
[<tag> ]<mode> <object> <stage> <file>
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 16e87fd6dd..dbc91f98ff 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -20,16 +20,16 @@ in the current working directory. Note that:
- the behaviour is slightly different from that of "/bin/ls" in that the
'<path>' denotes just a list of patterns to match, e.g. so specifying
- directory name (without '-r') will behave differently, and order of the
+ directory name (without `-r`) will behave differently, and order of the
arguments does not matter.
- the behaviour is similar to that of "/bin/ls" in that the '<path>' is
taken as relative to the current working directory. E.g. when you are
in a directory 'sub' that has a directory 'dir', you can run 'git
ls-tree -r HEAD dir' to list the contents of the tree (that is
- 'sub/dir' in 'HEAD'). You don't want to give a tree that is not at the
+ 'sub/dir' in `HEAD`). You don't want to give a tree that is not at the
root level (e.g. `git ls-tree -r HEAD:sub dir`) in this case, as that
- would result in asking for 'sub/sub/dir' in the 'HEAD' commit.
+ would result in asking for 'sub/sub/dir' in the `HEAD` commit.
However, the current working directory can be ignored by passing
--full-tree option.
@@ -46,7 +46,7 @@ OPTIONS
-t::
Show tree entries even when going to recurse them. Has no effect
- if '-r' was not passed. '-d' implies '-t'.
+ if `-r` was not passed. `-d` implies `-t`.
-l::
--long::
diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt
index 4d1b871d96..e3b2a88c4b 100644
--- a/Documentation/git-mailsplit.txt
+++ b/Documentation/git-mailsplit.txt
@@ -8,7 +8,8 @@ git-mailsplit - Simple UNIX mbox splitter program
SYNOPSIS
--------
[verse]
-'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...]
+'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] [--mboxrd]
+ -o<directory> [--] [(<mbox>|<Maildir>)...]
DESCRIPTION
-----------
@@ -47,6 +48,10 @@ OPTIONS
--keep-cr::
Do not remove `\r` from lines ending with `\r\n`.
+--mboxrd::
+ Input is of the "mboxrd" format and "^>+From " line escaping is
+ reversed.
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-mktree.txt b/Documentation/git-mktree.txt
index 5c6ebdfad9..c3616e7711 100644
--- a/Documentation/git-mktree.txt
+++ b/Documentation/git-mktree.txt
@@ -32,7 +32,7 @@ OPTIONS
--batch::
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
+ optional. Note - if the `-z` option is used, lines are terminated
with NUL.
GIT
diff --git a/Documentation/git-mv.txt b/Documentation/git-mv.txt
index e4531325cd..79449bf98f 100644
--- a/Documentation/git-mv.txt
+++ b/Documentation/git-mv.txt
@@ -32,10 +32,10 @@ OPTIONS
--force::
Force renaming or moving of a file even if the target exists
-k::
- Skip move or rename actions which would lead to an error
+ Skip move or rename actions which would lead to an error
condition. An error happens when a source is neither existing nor
controlled by Git, or when it would overwrite an existing
- file unless '-f' is given.
+ file unless `-f` is given.
-n::
--dry-run::
Do nothing; only show what would happen
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 02a10bc3b6..be7db3048d 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -152,7 +152,7 @@ OPTIONS
-c <object>::
--reedit-message=<object>::
- Like '-C', but with '-c' the editor is invoked, so that
+ Like '-C', but with `-c` the editor is invoked, so that
the user can further edit the note message.
--allow-empty::
diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt
index 9d4f1519e7..c83aaf39c3 100644
--- a/Documentation/git-p4.txt
+++ b/Documentation/git-p4.txt
@@ -104,7 +104,7 @@ $ git p4 sync //path/in/your/perforce/depot
------------
This imports the specified depot into
'refs/remotes/p4/master' in an existing Git repository. The
-'--branch' option can be used to specify a different branch to
+`--branch` option can be used to specify a different branch to
be used for the p4 content.
If a Git repository includes branches 'refs/remotes/origin/p4', these
@@ -114,7 +114,7 @@ from a Git remote, this can be useful in a multi-developer environment.
If there are multiple branches, doing 'git p4 sync' will automatically
use the "BRANCH DETECTION" algorithm to try to partition new changes
-into the right branch. This can be overridden with the '--branch'
+into the right branch. This can be overridden with the `--branch`
option to specify just a single branch to update.
@@ -150,10 +150,10 @@ $ git p4 submit topicbranch
------------
The upstream reference is generally 'refs/remotes/p4/master', but can
-be overridden using the '--origin=' command-line option.
+be overridden using the `--origin=` command-line option.
The p4 changes will be created as the user invoking 'git p4 submit'. The
-'--preserve-user' option will cause ownership to be modified
+`--preserve-user` option will cause ownership to be modified
according to the author of the Git commit. This option requires admin
privileges in p4, which can be granted using 'p4 protect'.
@@ -221,7 +221,7 @@ Git repository:
where they will be treated as remote-tracking branches by
linkgit:git-branch[1] and other commands. This option instead
puts p4 branches in 'refs/heads/p4/'. Note that future
- sync operations must specify '--import-local' as well so that
+ sync operations must specify `--import-local` as well so that
they can find the p4 branches in refs/heads.
--max-changes <n>::
@@ -245,7 +245,7 @@ Git repository:
default, involves removing the entire depot path. With this
option, the full p4 depot path is retained in Git. For example,
path '//depot/main/foo/bar.c', when imported from
- '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the
+ '//depot/main/', becomes 'foo/bar.c'. With `--keep-path`, the
Git path is instead 'depot/main/foo/bar.c'.
--use-client-spec::
@@ -275,7 +275,7 @@ These options can be used to modify 'git p4 submit' behavior.
--origin <commit>::
Upstream location from which commits are identified to submit to
p4. By default, this is the most recent p4 commit reachable
- from 'HEAD'.
+ from `HEAD`.
-M::
Detect renames. See linkgit:git-diff[1]. Renames will be
@@ -341,7 +341,7 @@ p4 revision specifier on the end:
Import all changes from both named depot paths into a single
repository. Only files below these directories are included.
There is not a subdirectory in Git for each "proj1" and "proj2".
- You must use the '--destination' option when specifying more
+ You must use the `--destination` option when specifying more
than one depot path. The revision specifier must be specified
identically on each depot path. If there are files in the
depot paths with the same name, the path with the most recently
@@ -355,7 +355,7 @@ CLIENT SPEC
The p4 client specification is maintained with the 'p4 client' command
and contains among other fields, a View that specifies how the depot
is mapped into the client repository. The 'clone' and 'sync' commands
-can consult the client spec when given the '--use-client-spec' option or
+can consult the client spec when given the `--use-client-spec` option or
when the useClientSpec variable is true. After 'git p4 clone', the
useClientSpec variable is automatically set in the repository
configuration file. This allows future 'git p4 submit' commands to
@@ -390,7 +390,7 @@ different areas in the tree, and indicate related content. 'git p4'
can use these mappings to determine branch relationships.
If you have a repository where all the branches of interest exist as
-subdirectories of a single depot path, you can use '--detect-branches'
+subdirectories of a single depot path, you can use `--detect-branches`
when cloning or syncing to have 'git p4' automatically find
subdirectories in p4, and to generate these as branches in Git.
@@ -507,7 +507,7 @@ git-p4.labelImportRegexp::
git-p4.useClientSpec::
Specify that the p4 client spec should be used to identify p4
depot paths of interest. This is equivalent to specifying the
- option '--use-client-spec'. See the "CLIENT SPEC" section above.
+ option `--use-client-spec`. See the "CLIENT SPEC" section above.
This variable is a boolean, not the name of a p4 client.
git-p4.pathEncoding::
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 19cdcd0341..8973510a41 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -104,8 +104,8 @@ base-name::
out of memory with a large window, but still be able to take
advantage of the large window for the smaller objects. The
size can be suffixed with "k", "m", or "g".
- `--window-memory=0` makes memory usage unlimited, which is the
- default.
+ `--window-memory=0` makes memory usage unlimited. The default
+ is taken from the `pack.windowMemory` configuration variable.
--max-pack-size=<n>::
Maximum size of each output pack file. The size can be suffixed with
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 19f46b64d3..47b77e693b 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git push' [--all | --mirror | --tags] [--follow-tags] [--atomic] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
[--repo=<repository>] [-f | --force] [-d | --delete] [--prune] [-v | --verbose]
- [-u | --set-upstream]
+ [-u | --set-upstream] [--push-option=<string>]
[--[no-]signed|--sign=(true|false|if-asked)]
[--force-with-lease[=<refname>[:<expect>]]]
[--no-verify] [<repository> [<refspec>...]]
@@ -156,6 +156,12 @@ already exists on the remote side.
Either all refs are updated, or on error, no refs are updated.
If the server does not support atomic pushes the push will fail.
+-o::
+--push-option::
+ Transmit the given string to the server, which passes them to
+ the pre-receive as well as the post-receive hook. The given string
+ must not contain a NUL or LF character.
+
--receive-pack=<git-receive-pack>::
--exec=<git-receive-pack>::
Path to the 'git-receive-pack' program on the remote
@@ -198,10 +204,11 @@ branch we have for it.
+
`--force-with-lease=<refname>:<expect>` will protect the named ref (alone),
if it is going to be updated, by requiring its current value to be
-the same as the specified value <expect> (which is allowed to be
+the same as the specified value `<expect>` (which is allowed to be
different from the remote-tracking branch we have for the refname,
or we do not even have to have such a remote-tracking branch when
-this form is used).
+this form is used). If `<expect>` is the empty string, then the named ref
+must not already exist.
+
Note that all forms other than `--force-with-lease=<refname>:<expect>`
that specifies the expected current value of the ref explicitly are
@@ -275,7 +282,7 @@ origin +master` to force a push to the `master` branch). See the
all submodules that changed in the revisions to be pushed will be
pushed. If on-demand was not able to push all necessary revisions
it will also be aborted and exit with non-zero status. A value of
- 'no' or using '--no-recurse-submodules' can be used to override the
+ 'no' or using `--no-recurse-submodules` can be used to override the
push.recurseSubmodules configuration variable when no submodule
recursion is required.
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 0387b40e0a..de222c81af 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -208,10 +208,10 @@ rebase.stat::
rebase. False by default.
rebase.autoSquash::
- If set to true enable '--autosquash' option by default.
+ If set to true enable `--autosquash` option by default.
rebase.autoStash::
- If set to true enable '--autostash' option by default.
+ If set to true enable `--autostash` option by default.
rebase.missingCommitsCheck::
If set to "warn", print warnings about removed commits in
@@ -220,7 +220,7 @@ rebase.missingCommitsCheck::
done. "ignore" by default.
rebase.instructionFormat::
- Custom commit list format to use during an '--interactive' rebase.
+ Custom commit list format to use during an `--interactive` rebase.
OPTIONS
-------
@@ -428,9 +428,9 @@ without an explicit `--interactive`.
"fixup! " or "squash! " after the first, in case you referred to an
earlier fixup/squash with `git commit --fixup/--squash`.
+
-This option is only valid when the '--interactive' option is used.
+This option is only valid when the `--interactive` option is used.
+
-If the '--autosquash' option is enabled by default using the
+If the `--autosquash` option is enabled by default using the
configuration variable `rebase.autoSquash`, this option can be
used to override and disable this setting.
diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
index 000ee8dba2..0ccd5fbc78 100644
--- a/Documentation/git-receive-pack.txt
+++ b/Documentation/git-receive-pack.txt
@@ -33,6 +33,9 @@ post-update hooks found in the Documentation/howto directory.
option, which tells it if updates to a ref should be denied if they
are not fast-forwards.
+A number of other receive.* config options are available to tweak
+its behavior, see linkgit:git-config[1].
+
OPTIONS
-------
<directory>::
diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt
index e700bafa47..80afca866c 100644
--- a/Documentation/git-remote-fd.txt
+++ b/Documentation/git-remote-fd.txt
@@ -17,7 +17,7 @@ fetch, push or archive.
If only <infd> is given, it is assumed to be a bidirectional socket connected
to remote Git server (git-upload-pack, git-receive-pack or
-git-upload-achive). If both <infd> and <outfd> are given, they are assumed
+git-upload-archive). If both <infd> and <outfd> are given, they are assumed
to be pipes connected to a remote Git server (<infd> being the inbound pipe
and <outfd> being the outbound pipe.
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 1d7eceaa93..577b969c1b 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -137,9 +137,9 @@ branches, adds to that list.
Retrieves the URLs for a remote. Configurations for `insteadOf` and
`pushInsteadOf` are expanded here. By default, only the first URL is listed.
+
-With '--push', push URLs are queried rather than fetch URLs.
+With `--push`, push URLs are queried rather than fetch URLs.
+
-With '--all', all URLs for the remote will be listed.
+With `--all`, all URLs for the remote will be listed.
'set-url'::
@@ -147,11 +147,11 @@ Changes URLs for the remote. Sets first URL for remote <name> that matches
regex <oldurl> (first URL if no <oldurl> is given) to <newurl>. If
<oldurl> doesn't match any URL, an error occurs and nothing is changed.
+
-With '--push', push URLs are manipulated instead of fetch URLs.
+With `--push`, push URLs are manipulated instead of fetch URLs.
+
-With '--add', instead of changing existing URLs, new URL is added.
+With `--add`, instead of changing existing URLs, new URL is added.
+
-With '--delete', instead of changing existing URLs, all URLs matching
+With `--delete`, instead of changing existing URLs, all URLs matching
regex <url> are deleted for remote <name>. Trying to delete all
non-push URLs is an error.
+
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index b9c02ce481..26afe6ed54 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -33,7 +33,7 @@ OPTIONS
pack everything referenced into a single pack.
Especially useful when packing a repository that is used
for private development. Use
- with '-d'. This will clean up the objects that `git prune`
+ with `-d`. This will clean up the objects that `git prune`
leaves behind, but `git fsck --full --dangling` shows as
dangling.
+
@@ -42,7 +42,7 @@ whole new pack in order to get any contained object, no matter how many
other objects in that pack they already have locally.
-A::
- Same as `-a`, unless '-d' is used. Then any unreachable
+ Same as `-a`, unless `-d` is used. Then any unreachable
objects in a previous pack become loose, unpacked objects,
instead of being left in the old pack. Unreachable objects
are never intentionally added to a pack, even when repacking.
@@ -100,8 +100,10 @@ other objects in that pack they already have locally.
out of memory with a large window, but still be able to take
advantage of the large window for the smaller objects. The
size can be suffixed with "k", "m", or "g".
- `--window-memory=0` makes memory usage unlimited, which is the
- default.
+ `--window-memory=0` makes memory usage unlimited. The default
+ is taken from the `pack.windowMemory` configuration variable.
+ Note that the actual memory usage will be the limit multiplied
+ by the number of threads used by linkgit:git-pack-objects[1].
--max-pack-size=<n>::
Maximum size of each output pack file. The size can be suffixed with
@@ -128,6 +130,19 @@ other objects in that pack they already have locally.
with `-b` or `repack.writeBitmaps`, as it ensures that the
bitmapped packfile has the necessary objects.
+--unpack-unreachable=<when>::
+ When loosening unreachable objects, do not bother loosening any
+ objects older than `<when>`. This can be used to optimize out
+ the write of any objects that would be immediately pruned by
+ a follow-up `git prune`.
+
+-k::
+--keep-unreachable::
+ When used with `-ad`, any unreachable objects from existing
+ packs will be appended to the end of the packfile instead of
+ being removed. In addition, any unreachable loose objects will
+ be packed (and their loose counterparts removed).
+
Configuration
-------------
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 573616a04a..837707a8fd 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -24,7 +24,7 @@ from the HEAD commit).
Note: 'git revert' is used to record some new commits to reverse the
effect of some earlier commits (often only a faulty one). If you want to
throw away all uncommitted changes in your working directory, you
-should see linkgit:git-reset[1], particularly the '--hard' option. If
+should see linkgit:git-reset[1], particularly the `--hard` option. If
you want to extract specific files as they were in another commit, you
should see linkgit:git-checkout[1], specifically the `git checkout
<commit> -- <filename>` syntax. Take care with these alternatives as
@@ -37,7 +37,7 @@ OPTIONS
For a more complete list of ways to spell commit names, see
linkgit:gitrevisions[7].
Sets of commits can also be given but no traversal is done by
- default, see linkgit:git-rev-list[1] and its '--no-walk'
+ default, see linkgit:git-rev-list[1] and its `--no-walk`
option.
-e::
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index d0b38b4b10..642d0ef199 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -66,7 +66,7 @@ This option may be specified multiple times.
Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1])
to edit an introductory message for the patch series.
+
-When '--compose' is used, git send-email will use the From, Subject, and
+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,
@@ -182,19 +182,19 @@ $ git send-email --smtp-auth="PLAIN LOGIN GSSAPI" ...
+
If at least one of the specified mechanisms matches the ones advertised by the
SMTP server and if it is supported by the utilized SASL library, the mechanism
-is used for authentication. If neither 'sendemail.smtpAuth' nor '--smtp-auth'
+is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth`
is specified, all mechanisms supported by the SASL library can be used.
--smtp-pass[=<password>]::
Password for SMTP-AUTH. The argument is optional: If no
argument is specified, then the empty string is used as
the password. Default is the value of `sendemail.smtpPass`,
- however '--smtp-pass' always overrides this value.
+ however `--smtp-pass` always overrides this value.
+
Furthermore, passwords need not be specified in configuration files
or on the command line. If a username has been specified (with
-'--smtp-user' or a `sendemail.smtpUser`), but no password has been
-specified (with '--smtp-pass' or `sendemail.smtpPass`), then
+`--smtp-user` or a `sendemail.smtpUser`), but no password has been
+specified (with `--smtp-pass` or `sendemail.smtpPass`), then
a password is obtained using 'git-credential'.
--smtp-server=<host>::
@@ -240,7 +240,7 @@ must be used for each option.
--smtp-user=<user>::
Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`;
- if a username is not specified (with '--smtp-user' or `sendemail.smtpUser`),
+ if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`),
then authentication is not attempted.
--smtp-debug=0|1::
@@ -364,8 +364,8 @@ have been specified, in which case default to 'compose'.
--[no-]format-patch::
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
+ 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.
--quiet::
@@ -382,7 +382,7 @@ have been specified, in which case default to 'compose'.
--
+
Default is the value of `sendemail.validate`; if this is not set,
-default to '--validate'.
+default to `--validate`.
--force::
Send emails even if safety checks would prevent it.
@@ -428,13 +428,13 @@ sendmail;;
sendemail.multiEdit::
If true (default), a single editor instance will be spawned to edit
- files you have to edit (patches when '--annotate' is used, and the
- summary when '--compose' is used). If false, files will be edited one
+ files you have to edit (patches when `--annotate` is used, and the
+ summary when `--compose` is used). If false, files will be edited one
after the other, spawning a new editor each time.
sendemail.confirm::
Sets the default for whether to confirm before sending. Must be
- one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
+ one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
in the previous section for the meaning of these values.
EXAMPLE
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 6aa91e830c..a831dd0288 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -44,7 +44,7 @@ OPTIONS
option, then the refs from stdin are processed after those
on the command line.
+
-If '--stateless-rpc' is specified together with this option then
+If `--stateless-rpc` is specified together with this option then
the list of refs must be in packet format (pkt-line). Each ref must
be in a separate packet, and the list must end with a flush packet.
@@ -99,11 +99,11 @@ Specifying the Refs
There are three ways to specify which refs to update on the
remote end.
-With '--all' flag, all refs that exist locally are transferred to
+With `--all` flag, all refs that exist locally are transferred to
the remote side. You cannot specify any '<ref>' if you use
this flag.
-Without '--all' and without any '<ref>', the heads that exist
+Without `--all` and without any '<ref>', the heads that exist
both on the local side and on the remote side are updated.
When one or more '<ref>' are specified explicitly (whether on the
@@ -134,13 +134,13 @@ name. See linkgit:git-rev-parse[1].
exist in the set of remote refs; the ref matched <src>
locally is used as the name of the destination.
-Without '--force', the <src> ref is stored at the remote only if
+Without `--force`, the <src> ref is stored at the remote only if
<dst> does not exist, or <dst> is a proper subset (i.e. an
ancestor) of <src>. This check, known as "fast-forward check",
is performed in order to avoid accidentally overwriting the
remote ref and lose other peoples' commits from there.
-With '--force', the fast-forward check is disabled for all refs.
+With `--force`, the fast-forward check is disabled for all refs.
Optionally, a <ref> parameter can be prefixed with a plus '+' sign
to disable the fast-forward check only on that ref.
diff --git a/Documentation/git-shell.txt b/Documentation/git-shell.txt
index e4bdd2235c..2e30a3e42d 100644
--- a/Documentation/git-shell.txt
+++ b/Documentation/git-shell.txt
@@ -24,7 +24,7 @@ named `git-shell-commands` in the user's home directory.
COMMANDS
--------
-'git shell' accepts the following commands after the '-c' option:
+'git shell' accepts the following commands after the `-c` option:
'git receive-pack <argument>'::
'git upload-pack <argument>'::
@@ -43,7 +43,7 @@ directory.
INTERACTIVE USE
---------------
-By default, the commands above can be executed only with the '-c'
+By default, the commands above can be executed only with the `-c`
option; the shell is not interactive.
If a `~/git-shell-commands` directory is present, 'git shell'
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index b91d4e545b..7818e0f098 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -60,7 +60,7 @@ OPTIONS
are shown before their parents).
--date-order::
- This option is similar to '--topo-order' in the sense that no
+ 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.
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index 3a32451984..c0aa871c9e 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -60,7 +60,7 @@ OPTIONS
Enable stricter reference checking by requiring an exact ref path.
Aside from returning an error code of 1, it will also print an error
- message if '--quiet' was not specified.
+ message if `--quiet` was not specified.
--abbrev[=<n>]::
@@ -70,7 +70,7 @@ OPTIONS
-q::
--quiet::
- Do not print any results to stdout. When combined with '--verify' this
+ Do not print any results to stdout. When combined with `--verify` this
can be used to silently check if a reference exists.
--exclude-existing[=<pattern>]::
@@ -134,7 +134,7 @@ use:
This will show "refs/heads/master" but also "refs/remote/other-repo/master",
if such references exists.
-When using the '--verify' flag, the command requires an exact path:
+When using the `--verify` flag, the command requires an exact path:
-----------------------------------------------------------------------------
git show-ref --verify refs/heads/master
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index e1e8f57cdd..725065ef2d 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -32,11 +32,14 @@ OPTIONS
--branch::
Show the branch and tracking info even in short-format.
---porcelain::
+--porcelain[=<version>]::
Give the output in an easy-to-parse format for scripts.
This is similar to the short output, but will remain stable
across Git versions and regardless of user configuration. See
below for details.
++
+The version parameter is used to specify the format version.
+This is optional and defaults to the original version 'v1' format.
--long::
Give the output in the long-format. This is the default.
@@ -96,7 +99,7 @@ configuration variable documented in linkgit:git-config[1].
-z::
Terminate entries with NUL, instead of LF. This implies
- the `--porcelain` output format if no other format is given.
+ the `--porcelain=v1` output format if no other format is given.
--column[=<options>]::
--no-column::
@@ -180,12 +183,12 @@ in which case `XY` are `!!`.
If -b is used the short-format status is preceded by a line
-## branchname tracking info
+ ## branchname tracking info
-Porcelain Format
-~~~~~~~~~~~~~~~~
+Porcelain Format Version 1
+~~~~~~~~~~~~~~~~~~~~~~~~~~
-The porcelain format is similar to the short format, but is guaranteed
+Version 1 porcelain format is similar to the short format, but is guaranteed
not to change in a backwards-incompatible way between Git versions or
based on user configuration. This makes it ideal for parsing by scripts.
The description of the short format above also describes the porcelain
@@ -207,6 +210,124 @@ field from the first filename). Third, filenames containing special
characters are not specially formatted; no quoting or
backslash-escaping is performed.
+Porcelain Format Version 2
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Version 2 format adds more detailed information about the state of
+the worktree and changed items. Version 2 also defines an extensible
+set of easy to parse optional headers.
+
+Header lines start with "#" and are added in response to specific
+command line arguments. Parsers should ignore headers they
+don't recognize.
+
+### Branch Headers
+
+If `--branch` is given, a series of header lines are printed with
+information about the current branch.
+
+ Line Notes
+ ------------------------------------------------------------
+ # branch.oid <commit> | (initial) Current commit.
+ # branch.head <branch> | (detached) Current branch.
+ # branch.upstream <upstream_branch> If upstream is set.
+ # branch.ab +<ahead> -<behind> If upstream is set and
+ the commit is present.
+ ------------------------------------------------------------
+
+### Changed Tracked Entries
+
+Following the headers, a series of lines are printed for tracked
+entries. One of three different line formats may be used to describe
+an entry depending on the type of change. Tracked entries are printed
+in an undefined order; parsers should allow for a mixture of the 3
+line types in any order.
+
+Ordinary changed entries have the following format:
+
+ 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+
+Renamed or copied entries have the following format:
+
+ 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
+
+ Field Meaning
+ --------------------------------------------------------
+ <XY> A 2 character field containing the staged and
+ unstaged XY values described in the short format,
+ with unchanged indicated by a "." rather than
+ a space.
+ <sub> A 4 character field describing the submodule state.
+ "N..." when the entry is not a submodule.
+ "S<c><m><u>" when the entry is a submodule.
+ <c> is "C" if the commit changed; otherwise ".".
+ <m> is "M" if it has tracked changes; otherwise ".".
+ <u> is "U" if there are untracked changes; otherwise ".".
+ <mH> The octal file mode in HEAD.
+ <mI> The octal file mode in the index.
+ <mW> The octal file mode in the worktree.
+ <hH> The object name in HEAD.
+ <hI> The object name in the index.
+ <X><score> The rename or copy score (denoting the percentage
+ of similarity between the source and target of the
+ move or copy). For example "R100" or "C75".
+ <path> The pathname. In a renamed/copied entry, this
+ is the path in the index and in the working tree.
+ <sep> When the `-z` option is used, the 2 pathnames are separated
+ with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
+ byte separates them.
+ <origPath> The pathname in the commit at HEAD. This is only
+ present in a renamed/copied entry, and tells
+ where the renamed/copied contents came from.
+ --------------------------------------------------------
+
+Unmerged entries have the following format; the first character is
+a "u" to distinguish from ordinary changed entries.
+
+ u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+
+ Field Meaning
+ --------------------------------------------------------
+ <XY> A 2 character field describing the conflict type
+ as described in the short format.
+ <sub> A 4 character field describing the submodule state
+ as described above.
+ <m1> The octal file mode in stage 1.
+ <m2> The octal file mode in stage 2.
+ <m3> The octal file mode in stage 3.
+ <mW> The octal file mode in the worktree.
+ <h1> The object name in stage 1.
+ <h2> The object name in stage 2.
+ <h3> The object name in stage 3.
+ <path> The pathname.
+ --------------------------------------------------------
+
+### Other Items
+
+Following the tracked entries (and if requested), a series of
+lines will be printed for untracked and then ignored items
+found in the worktree.
+
+Untracked items have the following format:
+
+ ? <path>
+
+Ignored items have the following format:
+
+ ! <path>
+
+### Pathname Format Notes and -z
+
+When the `-z` option is given, pathnames are printed as is and
+without any quoting and lines are terminated with a NUL (ASCII 0x00)
+byte.
+
+Otherwise, all pathnames will be "C-quoted" if they contain any tab,
+linefeed, double quote, or backslash characters. In C-quoting, these
+characters will be replaced with the corresponding C-style escape
+sequences and the resulting pathname will be double quoted.
+
+
CONFIGURATION
-------------
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 698a6685f6..5f9e65b0c4 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -98,11 +98,11 @@ your Perl's Getopt::Long is < v2.37).
--ignore-paths=<regex>;;
When passed to 'init' or 'clone' this regular expression will
be preserved as a config key. See 'fetch' for a description
- of '--ignore-paths'.
+ of `--ignore-paths`.
--include-paths=<regex>;;
When passed to 'init' or 'clone' this regular expression will
be preserved as a config key. See 'fetch' for a description
- of '--include-paths'.
+ of `--include-paths`.
--no-minimize-url;;
When tracking multiple directories (using --stdlayout,
--branches, or --tags options), git svn will attempt to connect
@@ -110,7 +110,7 @@ your Perl's Getopt::Long is < v2.37).
repository. This default allows better tracking of history if
entire projects are moved within a repository, but may cause
issues on repositories where read access restrictions are in
- place. Passing '--no-minimize-url' will allow git svn to
+ place. Passing `--no-minimize-url` will allow git svn to
accept URLs as-is without attempting to connect to a higher
level directory. This option is off by default when only
one URL/branch is tracked (it would do little good).
@@ -141,7 +141,7 @@ the same local time zone.
--ignore-paths=<regex>;;
This allows one to specify a Perl regular expression that will
cause skipping of all matching paths from checkout from SVN.
- The '--ignore-paths' option should match for every 'fetch'
+ The `--ignore-paths` option should match for every 'fetch'
(including automatic fetches due to 'clone', 'dcommit',
'rebase', etc) on a given repository.
+
@@ -170,10 +170,10 @@ Skip "branches" and "tags" of first level directories;;
--include-paths=<regex>;;
This allows one to specify a Perl regular expression that will
cause the inclusion of only matching paths from checkout from SVN.
- The '--include-paths' option should match for every 'fetch'
+ The `--include-paths` option should match for every 'fetch'
(including automatic fetches due to 'clone', 'dcommit',
- 'rebase', etc) on a given repository. '--ignore-paths' takes
- precedence over '--include-paths'.
+ 'rebase', etc) on a given repository. `--ignore-paths` takes
+ precedence over `--include-paths`.
+
[verse]
config key: svn-remote.<name>.include-paths
@@ -191,7 +191,7 @@ config key: svn-remote.<name>.include-paths
or if a second argument is passed; it will create a directory
and work within that. It accepts all arguments that the
'init' and 'fetch' commands accept; with the exception of
- '--fetch-all' and '--parent'. After a repository is cloned,
+ `--fetch-all` and `--parent`. After a repository is cloned,
the 'fetch' command will be able to update revisions without
affecting the working tree; and the 'rebase' command will be
able to update the working tree with the latest changes.
@@ -216,7 +216,7 @@ it preserves linear history with 'git rebase' instead of
'git merge' for ease of dcommitting with 'git svn'.
+
This accepts all options that 'git svn fetch' and 'git rebase'
-accept. However, '--fetch-all' only fetches from the current
+accept. However, `--fetch-all` only fetches from the current
[svn-remote], and not all [svn-remote] definitions.
+
Like 'git rebase'; this requires that the working tree be clean
@@ -625,6 +625,9 @@ config key: svn.authorsfile
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.
++
+[verse]
+config key: svn.authorsProg
-q::
--quiet::
@@ -919,7 +922,7 @@ parent of the branch. However, it is possible that there is no suitable
Git commit to serve as parent. This will happen, among other reasons,
if the SVN branch is a copy of a revision that was not fetched by 'git
svn' (e.g. because it is an old revision that was skipped with
-'--revision'), or if in SVN a directory was copied that is not tracked
+`--revision`), or if in SVN a directory was copied that is not tracked
by 'git svn' (such as a branch that is not tracked at all, or a
subdirectory of a tracked branch). In these cases, 'git svn' will still
create a Git branch, but instead of using an existing Git commit as the
@@ -996,12 +999,12 @@ directories in the working copy. While this is the easiest way to get a
copy of a complete repository, for projects with many branches it will
lead to a working copy many times larger than just the trunk. Thus for
projects using the standard directory structure (trunk/branches/tags),
-it is recommended to clone with option '--stdlayout'. If the project
+it is recommended to clone with option `--stdlayout`. If the project
uses a non-standard structure, and/or if branches and tags are not
required, it is easiest to only clone one directory (typically trunk),
without giving any repository layout options. If the full history with
-branches and tags is required, the options '--trunk' / '--branches' /
-'--tags' must be used.
+branches and tags is required, the options `--trunk` / `--branches` /
+`--tags` must be used.
When using multiple --branches or --tags, 'git svn' does not automatically
handle name collisions (for example, if two branches from different paths have
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 6b89393746..7ecca8e247 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -167,7 +167,7 @@ This option is only applicable when listing tags without annotation lines.
--[no-]merged [<commit>]::
Only list tags whose tips are reachable, or not reachable
- if '--no-merged' is used, from the specified commit ('HEAD'
+ if `--no-merged` is used, from the specified commit (`HEAD`
if not specified).
CONFIGURATION
diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt
index 3e887d1610..b3de50d710 100644
--- a/Documentation/git-unpack-objects.txt
+++ b/Documentation/git-unpack-objects.txt
@@ -44,6 +44,9 @@ OPTIONS
--strict::
Don't write objects with broken content or links.
+--max-input-size=<size>::
+ Die, if the pack is larger than <size>.
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index c6cbed189c..7386c93162 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -102,7 +102,7 @@ thus, in case the assumed-untracked file is changed upstream,
you will need to handle the situation manually.
--really-refresh::
- Like '--refresh', but checks stat information unconditionally,
+ Like `--refresh`, but checks stat information unconditionally,
without regard to the "assume unchanged" setting.
--[no-]skip-worktree::
@@ -211,7 +211,7 @@ will remove the intended effect of the option.
Using --refresh
---------------
-'--refresh' does not calculate a new sha1 file or bring the index
+`--refresh` does not calculate a new sha1 file or bring the index
up-to-date for mode/content changes. But what it *does* do is to
"re-match" the stat information of a file with the index, so that you
can refresh the index for a file that hasn't been changed but where
@@ -222,7 +222,7 @@ up the stat index details with the proper files.
Using --cacheinfo or --info-only
--------------------------------
-'--cacheinfo' is used to register a file that is not in the
+`--cacheinfo` is used to register a file that is not in the
current working directory. This is useful for minimum-checkout
merging.
@@ -232,12 +232,12 @@ To pretend you have a file with mode and sha1 at path, say:
$ git update-index --cacheinfo <mode>,<sha1>,<path>
----------------
-'--info-only' is used to register files without placing them in the object
+`--info-only` is used to register files without placing them in the object
database. This is useful for status-only repositories.
-Both '--cacheinfo' and '--info-only' behave similarly: the index is updated
-but the object database isn't. '--cacheinfo' is useful when the object is
-in the database but the file isn't available locally. '--info-only' is
+Both `--cacheinfo` and `--info-only` behave similarly: the index is updated
+but the object database isn't. `--cacheinfo` is useful when the object is
+in the database but the file isn't available locally. `--info-only` is
useful when the file is available, but you do not wish to update the
object database.
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index 7daa28fd94..2d6b09a43c 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -110,7 +110,7 @@ Note about git-config --global
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note that these configuration variables should probably be set using
-the '--global' flag, for example like this:
+the `--global` flag, for example like this:
------------------------------------------------
$ git config --global web.browser firefox
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 23d8d2ace0..0aeb020d02 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -10,8 +10,10 @@ SYNOPSIS
--------
[verse]
'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>]
-'git worktree prune' [-n] [-v] [--expire <expire>]
'git worktree list' [--porcelain]
+'git worktree lock' [--reason <string>] <worktree>
+'git worktree prune' [-n] [-v] [--expire <expire>]
+'git worktree unlock' <worktree>
DESCRIPTION
-----------
@@ -38,9 +40,8 @@ section "DETAILS" for more information.
If a linked working tree is stored on a portable device or network share
which is not always mounted, you can prevent its administrative files from
-being pruned by creating a file named 'locked' alongside the other
-administrative files, optionally containing a plain text reason that
-pruning should be suppressed. See section "DETAILS" for more information.
+being pruned by issuing the `git worktree lock` command, optionally
+specifying `--reason` to explain why the working tree is locked.
COMMANDS
--------
@@ -55,10 +56,6 @@ If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used,
then, as a convenience, a new branch based at HEAD is created automatically,
as if `-b $(basename <path>)` was specified.
-prune::
-
-Prune working tree information in $GIT_DIR/worktrees.
-
list::
List details of each worktree. The main worktree is listed first, followed by
@@ -66,6 +63,22 @@ each of the linked worktrees. The output details include if the worktree is
bare, the revision currently checked out, and the branch currently checked out
(or 'detached HEAD' if none).
+lock::
+
+If a working tree is on a portable device or network share which
+is not always mounted, lock it to prevent its administrative
+files from being pruned automatically. This also prevents it from
+being moved or deleted. Optionally, specify a reason for the lock
+with `--reason`.
+
+prune::
+
+Prune working tree information in $GIT_DIR/worktrees.
+
+unlock::
+
+Unlock a working tree, allowing it to be pruned, moved or deleted.
+
OPTIONS
-------
@@ -111,6 +124,18 @@ OPTIONS
--expire <time>::
With `prune`, only expire unused working trees older than <time>.
+--reason <string>::
+ With `lock`, an explanation why the working tree is locked.
+
+<worktree>::
+ Working trees can be identified by path, either relative or
+ absolute.
++
+If the last path components in the working tree's path is unique among
+working trees, it can be used to identify worktrees. For example if
+you only have to working trees at "/abc/def/ghi" and "/abc/def/ggg",
+then "ghi" or "def/ghi" is enough to point to the former working tree.
+
DETAILS
-------
Each linked working tree has a private sub-directory in the repository's
@@ -151,7 +176,8 @@ instead.
To prevent a $GIT_DIR/worktrees entry from being pruned (which
can be useful in some situations, such as when the
-entry's working tree is stored on a portable device), add a file named
+entry's working tree is stored on a portable device), use the
+`git worktree lock` command, which adds a file named
'locked' to the entry's directory. The file contains the reason in
plain text. For example, if a linked working tree's `.git` file points
to `/path/main/.git/worktrees/test-next` then a file named
@@ -227,8 +253,6 @@ performed manually, such as:
- `remove` to remove a linked working tree and its administrative files (and
warn if the working tree is dirty)
- `mv` to move or rename a working tree and update its administrative files
-- `lock` to prevent automatic pruning of administrative files (for instance,
- for a working tree on a portable device)
GIT
---
diff --git a/Documentation/git.txt b/Documentation/git.txt
index ca611c9f86..7913fc2513 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -31,8 +31,8 @@ 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.
-Formatted and hyperlinked version of the latest Git documentation
-can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
+A formatted and hyperlinked copy of the latest Git documentation
+can be viewed at `https://git.github.io/htmldocs/git.html`.
ifdef::stalenotes[]
[NOTE]
@@ -43,9 +43,17 @@ unreleased) version of Git, that is available from the 'master'
branch of the `git.git` repository.
Documentation for older releases are available here:
-* link:v2.9.0/git.html[documentation for release 2.9]
+* link:v2.10.0/git.html[documentation for release 2.10]
* release notes for
+ link:RelNotes/2.10.0.txt[2.10].
+
+* link:v2.9.3/git.html[documentation for release 2.9.3]
+
+* release notes for
+ link:RelNotes/2.9.3.txt[2.9.3],
+ link:RelNotes/2.9.2.txt[2.9.2],
+ link:RelNotes/2.9.1.txt[2.9.1],
link:RelNotes/2.9.0.txt[2.9].
* link:v2.8.4/git.html[documentation for release 2.8.4]
@@ -513,7 +521,7 @@ OPTIONS
--help::
Prints the synopsis and a list of the most commonly used
- commands. If the option '--all' or '-a' is given then all
+ commands. If the option `--all` or `-a` is given then all
available commands are printed. If a Git command is named this
option will bring up the manual page for that command.
+
@@ -855,16 +863,16 @@ Git so take care if using a foreign front-end.
If the `GIT_DIR` environment variable is set then it
specifies a path to use instead of the default `.git`
for the base of the repository.
- The '--git-dir' command-line option also sets this value.
+ The `--git-dir` command-line option also sets this value.
`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`::
Set the Git namespace; see linkgit:gitnamespaces[7] for details.
- The '--namespace' command-line option also sets this value.
+ The `--namespace` command-line option also sets this value.
`GIT_CEILING_DIRECTORIES`::
This should be a colon-separated list of absolute paths. If
@@ -979,7 +987,7 @@ other
The command will be given exactly two or four arguments: the
'username@host' (or just 'host') from the URL and the shell
command to execute on that remote system, optionally preceded by
- '-p' (literally) and the 'port' from the URL when it specifies
+ `-p` (literally) and the 'port' from the URL when it specifies
something other than the default SSH port.
+
`$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 8882a3e914..7aff940202 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -115,6 +115,7 @@ text file is normalized, its line endings are converted to LF in the
repository. To control what line ending style is used in the working
directory, use the `eol` attribute for a single file and the
`core.eol` configuration variable for all text files.
+Note that `core.autocrlf` overrides `core.eol`
Set::
@@ -130,8 +131,9 @@ Unset::
Set to string value "auto"::
When `text` is set to "auto", the path is marked for automatic
- end-of-line normalization. If Git decides that the content is
- text, its line endings are normalized to LF on checkin.
+ end-of-line conversion. If Git decides that the content is
+ text, its line endings are converted to LF on checkin.
+ When the file has been committed with CRLF, no conversion is done.
Unspecified::
@@ -146,7 +148,7 @@ unspecified.
^^^^^
This attribute sets a specific line-ending style to be used in the
-working directory. It enables end-of-line normalization without any
+working directory. It enables end-of-line conversion without any
content checks, effectively setting the `text` attribute.
Set to string value "crlf"::
@@ -180,60 +182,51 @@ While Git normally leaves file contents alone, it can be configured to
normalize line endings to LF in the repository and, optionally, to
convert them to CRLF when files are checked out.
-Here is an example that will make Git normalize .txt, .vcproj and .sh
-files, ensure that .vcproj files have CRLF and .sh files have LF in
-the working directory, and prevent .jpg files from being normalized
-regardless of their content.
-
-------------------------
-*.txt text
-*.vcproj eol=crlf
-*.sh eol=lf
-*.jpg -text
-------------------------
-
-Other source code management systems normalize all text files in their
-repositories, and there are two ways to enable similar automatic
-normalization in Git.
-
If you simply want to have CRLF line endings in your working directory
regardless of the repository you are working with, you can set the
-config variable "core.autocrlf" without changing any attributes.
+config variable "core.autocrlf" without using any attributes.
------------------------
[core]
autocrlf = true
------------------------
-This does not force normalization of all text files, but does ensure
+This does not force normalization of text files, but does ensure
that text files that you introduce to the repository have their line
endings normalized to LF when they are added, and that files that are
already normalized in the repository stay normalized.
-If you want to interoperate with a source code management system that
-enforces end-of-line normalization, or you simply want all text files
-in your repository to be normalized, you should instead set the `text`
-attribute to "auto" for _all_ files.
+If you want to ensure that text files that any contributor introduces to
+the repository have their line endings normalized, you can set the
+`text` attribute to "auto" for _all_ files.
------------------------
* text=auto
------------------------
-This ensures that all files that Git considers to be text will have
-normalized (LF) line endings in the repository. The `core.eol`
-configuration variable controls which line endings Git will use for
-normalized files in your working directory; the default is to use the
-native line ending for your platform, or CRLF if `core.autocrlf` is
-set.
+The attributes allow a fine-grained control, how the line endings
+are converted.
+Here is an example that will make Git normalize .txt, .vcproj and .sh
+files, ensure that .vcproj files have CRLF and .sh files have LF in
+the working directory, and prevent .jpg files from being normalized
+regardless of their content.
+
+------------------------
+* text=auto
+*.txt text
+*.vcproj text eol=crlf
+*.sh text eol=lf
+*.jpg -text
+------------------------
+
+NOTE: When `text=auto` conversion is enabled in a cross-platform
+project using push and pull to a central repository the text files
+containing CRLFs should be normalized.
-NOTE: When `text=auto` normalization is enabled in an existing
-repository, any text files containing CRLFs should be normalized. If
-they are not they will be normalized the next time someone tries to
-change them, causing unfortunate misattribution. From a clean working
-directory:
+From a clean working directory:
-------------------------------------------------
-$ echo "* text=auto" >>.gitattributes
+$ echo "* text=auto" >.gitattributes
$ rm .git/index # Remove the index to force Git to
$ git reset # re-scan the working directory
$ git status # Show files that will be normalized
@@ -374,6 +367,11 @@ substitution. For example:
smudge = git-p4-filter --smudge %f
------------------------
+Note that "%f" is the name of the path that is being worked on. Depending
+on the version that is being filtered, the corresponding file on disk may
+not exist, or may have different contents. So, smudge and clean commands
+should not try to access the file on disk, but only act as filters on the
+content provided to them on standard input.
Interaction between checkin/checkout attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index 15b3bfa8db..4546fa0d75 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -949,7 +949,7 @@ for details.
[NOTE]
If there were more commits on the 'master' branch after the merge, the
merge commit itself would not be shown by 'git show-branch' by
-default. You would need to provide '--sparse' option to make the
+default. You would need to provide `--sparse` option to make the
merge commit visible in this case.
Now, let's pretend you are the one who did all the work in
diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt
index b06e852a85..4c6143c511 100644
--- a/Documentation/gitcvs-migration.txt
+++ b/Documentation/gitcvs-migration.txt
@@ -116,8 +116,12 @@ they create are writable and searchable by other group members.
Importing a CVS archive
-----------------------
+NOTE: These instructions use the `git-cvsimport` script which ships with
+git, but other importers may provide better results. See the note in
+linkgit:git-cvsimport[1] for other options.
+
First, install version 2.1 or higher of cvsps from
-http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
+https://github.com/andreyvit/cvsps[https://github.com/andreyvit/cvsps] and make
sure it is in your path. Then cd to a checked out CVS working directory
of the project you are interested in and run linkgit:git-cvsimport[1]:
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
index c579593e55..08cf62278e 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.txt
@@ -28,8 +28,8 @@ The 'git diff-{asterisk}' family works by first comparing two sets of
files:
- 'git diff-index' compares contents of a "tree" object and the
- working directory (when '--cached' flag is not used) or a
- "tree" object and the index file (when '--cached' flag is
+ working directory (when `--cached` flag is not used) or a
+ "tree" object and the index file (when `--cached` flag is
used);
- 'git diff-files' compares contents of the index file and the
diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
index d82e912e55..9565dc3fda 100644
--- a/Documentation/githooks.txt
+++ b/Documentation/githooks.txt
@@ -247,6 +247,15 @@ Both standard output and standard error output are forwarded to
'git send-pack' on the other end, so you can simply `echo` messages
for the user.
+The number of push options given on the command line of
+`git push --push-option=...` can be read from the environment
+variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are
+found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,...
+If it is negotiated to not use the push options phase, the
+environment variables will not be set. If the client selects
+to use push options, but doesn't transmit any, the count variable
+will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
+
[[update]]
update
~~~~~~
@@ -322,6 +331,15 @@ a sample script `post-receive-email` provided in the `contrib/hooks`
directory in Git distribution, which implements sending commit
emails.
+The number of push options given on the command line of
+`git push --push-option=...` can be read from the environment
+variable `GIT_PUSH_OPTION_COUNT`, and the options themselves are
+found in `GIT_PUSH_OPTION_0`, `GIT_PUSH_OPTION_1`,...
+If it is negotiated to not use the push options phase, the
+environment variables will not be set. If the client selects
+to use push options, but doesn't transmit any, the count variable
+will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.
+
[[post-update]]
post-update
~~~~~~~~~~~
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002176..e382dd96df 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
--left-right::
- Mark which side of a symmetric diff a commit is reachable
+ Mark which side of a symmetric difference a commit is reachable
from. Commits from the left side are prefixed with a `<`
symbol and those from the right with a `>` symbol.
@@ -82,7 +82,7 @@ linkgit:git-rev-list[1] for a complete list.
--simplify-merges::
- Additional option to '--full-history' to remove some needless
+ Additional option to `--full-history` to remove some needless
merges from the resulting history, as there are no selected
commits contributing to this merge. (See "History
simplification" in linkgit:git-log[1] for a more detailed
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index ac70eca321..10dcc08ff9 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -19,7 +19,7 @@ of linkgit:git-config[1].
The file contains one subsection per submodule, and the subsection value
is the name of the submodule. The name is set to the path where the
-submodule has been added unless it was customized with the '--name'
+submodule has been added unless it was customized with the `--name`
option of 'git submodule add'. Each submodule section also contains the
following required keys:
@@ -79,6 +79,11 @@ submodule.<name>.ignore::
"--ignore-submodule" option. The 'git submodule' commands are not
affected by this setting.
+submodule.<name>.shallow::
+ When set to true, a clone of this submodule will be performed as a
+ shallow clone unless the user explicitly asks for a non-shallow
+ clone.
+
EXAMPLES
--------
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 1e8659492f..a4de50ad22 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -210,17 +210,17 @@ the remote repository.
'export-marks' <file>::
This modifies the 'export' capability, instructing Git to dump the
internal marks table to <file> when complete. For details,
- read up on '--export-marks=<file>' in linkgit:git-fast-export[1].
+ read up on `--export-marks=<file>` in linkgit:git-fast-export[1].
'import-marks' <file>::
This modifies the 'export' capability, instructing Git to load the
marks specified in <file> before processing any input. For details,
- read up on '--import-marks=<file>' in linkgit:git-fast-export[1].
+ read up on `--import-marks=<file>` in linkgit:git-fast-export[1].
'signed-tags'::
This modifies the 'export' capability, instructing Git to pass
- '--signed-tags=verbatim' to linkgit:git-fast-export[1]. In the
- absence of this capability, Git will use '--signed-tags=warn-strip'.
+ `--signed-tags=verbatim` to linkgit:git-fast-export[1]. In the
+ absence of this capability, Git will use `--signed-tags=warn-strip`.
@@ -298,7 +298,7 @@ Supported if the helper has the "fetch" capability.
is followed by a blank line). For example, the following would
be two batches of 'push', the first asking the remote-helper
to push the local ref 'master' to the remote ref 'master' and
- the local 'HEAD' to the remote 'branch', and the second
+ the local `HEAD` to the remote 'branch', and the second
asking to push ref 'foo' to ref 'bar' (forced update requested
by the '+').
+
diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index e903eb7860..27dec5b91d 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -15,9 +15,9 @@ DESCRIPTION
Many Git commands take revision parameters as arguments. Depending on
the command, they denote a specific commit or, for commands which
-walk the revision graph (such as linkgit:git-log[1]), all commits which can
-be reached from that commit. In the latter case one can also specify a
-range of revisions explicitly.
+walk the revision graph (such as linkgit:git-log[1]), all commits which are
+reachable from that commit. For commands that walk the revision graph one can
+also specify a range of revisions explicitly.
In addition, some Git commands (such as linkgit:git-show[1]) also take
revision parameters which denote other objects than commits, e.g. blobs
diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index a79e350246..e6320891b1 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -246,13 +246,20 @@ $highlight_bin::
Note that 'highlight' feature must be set for gitweb to actually
use syntax highlighting.
+
-*NOTE*: if you want to add support for new file type (supported by
-"highlight" but not used by gitweb), you need to modify `%highlight_ext`
-or `%highlight_basename`, depending on whether you detect type of file
-based on extension (for example "sh") or on its basename (for example
-"Makefile"). The keys of these hashes are extension and basename,
-respectively, and value for given key is name of syntax to be passed via
-`--syntax <syntax>` to highlighter.
+*NOTE*: for a file to be highlighted, its syntax type must be detected
+and that syntax must be supported by "highlight". The default syntax
+detection is minimal, and there are many supported syntax types with no
+detection by default. There are three options for adding syntax
+detection. The first and second priority are `%highlight_basename` and
+`%highlight_ext`, which detect based on basename (the full filename, for
+example "Makefile") and extension (for example "sh"). The keys of these
+hashes are the basename and extension, respectively, and the value for a
+given key is the name of the syntax to be passed via `--syntax <syntax>`
+to "highlight". The last priority is the "highlight" configuration of
+`Shebang` regular expressions to detect the language based on the first
+line in the file, (for example, matching the line "#!/bin/bash"). See
+the highlight documentation and the default config at
+/etc/highlight/filetypes.conf for more details.
+
For example if repositories you are hosting use "phtml" extension for
PHP files, and you want to have correct syntax-highlighting for those
diff --git a/Documentation/howto/new-command.txt b/Documentation/howto/new-command.txt
index 6d772bd927..15a4c8031f 100644
--- a/Documentation/howto/new-command.txt
+++ b/Documentation/howto/new-command.txt
@@ -94,7 +94,7 @@ your language, document it in the INSTALL file.
6. There is a file command-list.txt in the distribution main directory
that categorizes commands by type, so they can be listed in appropriate
subsections in the documentation's summary command list. Add an entry
-for yours. To understand the categories, look at git-commands.txt
+for yours. To understand the categories, look at command-list.txt
in the main directory. If the new command is part of the typical Git
workflow and you believe it common enough to be mentioned in 'git help',
map this command to a common group in the column [common].
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b992f..a942d57f73 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -147,8 +147,14 @@ endif::git-rev-list[]
"U" for a good signature with unknown validity and "N" for no signature
- '%GS': show the name of the signer for a signed commit
- '%GK': show the key used to sign a signed commit
-- '%gD': reflog selector, e.g., `refs/stash@{1}`
-- '%gd': shortened reflog selector, e.g., `stash@{1}`
+- '%gD': reflog selector, e.g., `refs/stash@{1}` or
+ `refs/stash@{2 minutes ago`}; the format follows the rules described
+ for the `-g` option. The portion before the `@` is the refname as
+ given on the command line (so `git log -g refs/heads/master` would
+ yield `refs/heads/master@{0}`).
+- '%gd': shortened reflog selector; same as `%gD`, but the refname
+ portion is shortened for human readability (so `refs/heads/master`
+ becomes just `master`).
- '%gn': reflog identity name
- '%gN': reflog identity name (respecting .mailmap, see
linkgit:git-shortlog[1] or linkgit:git-blame[1])
@@ -166,7 +172,7 @@ endif::git-rev-list[]
respecting the `auto` settings of the former if we are going to a
terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
on the next placeholders until the color is switched again.
-- '%m': left, right or boundary mark
+- '%m': left (`<`), right (`>`) or boundary (`-`) mark
- '%n': newline
- '%%': a raw '%'
- '%x00': print a byte from a hex code
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 4f009d4424..7e462d3841 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -193,7 +193,7 @@ endif::git-rev-list[]
--stdin::
In addition to the '<commit>' listed on the command
- line, read them from the standard input. If a '--' separator is
+ line, read them from the standard input. If a `--` separator is
seen, stop reading commits and start reading paths to limit the
result.
@@ -225,7 +225,7 @@ excluded from the output.
--left-only::
--right-only::
- List only commits on the respective side of a symmetric range,
+ List only commits on the respective side of a symmetric difference,
i.e. only those which would be marked `<` resp. `>` by
`--left-right`.
+
@@ -252,10 +252,25 @@ list.
+
With `--pretty` format other than `oneline` (for obvious reasons),
this causes the output to have two extra lines of information
-taken from the reflog. By default, 'commit@\{Nth}' notation is
-used in the output. When the starting commit is specified as
-'commit@\{now}', output also uses 'commit@\{timestamp}' notation
-instead. Under `--pretty=oneline`, the commit message is
+taken from the reflog. The reflog designator in the output may be shown
+as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
+reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
+depending on a few rules:
++
+--
+1. If the starting point is specified as `ref@{Nth}`, show the index
+format.
++
+2. If the starting point was specified as `ref@{now}`, show the
+timestamp format.
++
+3. If neither was used, but `--date` was given on the command line, show
+the timestamp in the format requested by `--date`.
++
+4. Otherwise, show the index format.
+--
++
+Under `--pretty=oneline`, the commit message is
prefixed with this information on the same line.
This option cannot be combined with `--reverse`.
See also linkgit:git-reflog[1].
@@ -274,6 +289,10 @@ ifdef::git-rev-list[]
Try to speed up the traversal using the pack bitmap index (if
one is available). Note that when traversing with `--objects`,
trees and blobs will not have their associated path printed.
+
+--progress=<header>::
+ Show progress reports on stderr as objects are considered. The
+ `<header>` text will be printed with each progress update.
endif::git-rev-list[]
--
@@ -710,8 +729,8 @@ include::pretty-options.txt[]
`iso-local`), the user's local time zone is used instead.
+
`--date=relative` shows dates relative to the current time,
-e.g. ``2 hours ago''. The `-local` option cannot be used with
-`--raw` or `--relative`.
+e.g. ``2 hours ago''. The `-local` option has no effect for
+`--date=relative`.
+
`--date=local` is an alias for `--date=default-local`.
+
@@ -731,7 +750,18 @@ format, often found in email messages.
+
`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
+
-`--date=raw` shows the date in the internal raw Git format `%s %z` format.
+`--date=raw` shows the date as seconds since the epoch (1970-01-01
+00:00:00 UTC), followed by a space, and then the timezone as an offset
+from UTC (a `+` or `-` with four digits; the first two are hours, and
+the second two are minutes). I.e., as if the timestamp were formatted
+with `strftime("%s %z")`).
+Note that the `-local` option does not affect the seconds-since-epoch
+value (which is always measured in UTC), but does switch the accompanying
+timezone value.
++
+`--date=unix` shows the date as a Unix epoch timestamp (seconds since
+1970). As with `--raw`, this is always in UTC and therefore `-local`
+has no effect.
+
`--date=format:...` feeds the format `...` to your system `strftime`.
Use `--date=format:%c` to show the date in your system locale's
@@ -766,7 +796,7 @@ ifdef::git-rev-list[]
endif::git-rev-list[]
--left-right::
- Mark which side of a symmetric diff a commit is reachable from.
+ Mark which side of a symmetric difference a commit is reachable from.
Commits from the left side are prefixed with `<` and those from
the right with `>`. If combined with `--boundary`, those
commits are prefixed with `-`.
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 19314e3b7f..4bed5b1ab7 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -28,8 +28,8 @@ blobs contained in a commit.
first match in the following rules:
. If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
- useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD'
- and 'CHERRY_PICK_HEAD');
+ useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`
+ and `CHERRY_PICK_HEAD`);
. otherwise, 'refs/<refname>' if it exists;
@@ -41,16 +41,16 @@ blobs contained in a commit.
. otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
+
-'HEAD' names the commit on which you based the changes in the working tree.
-'FETCH_HEAD' records the branch which you fetched from a remote repository
+`HEAD` names the commit on which you based the changes in the working tree.
+`FETCH_HEAD` records the branch which you fetched from a remote repository
with your last `git fetch` invocation.
-'ORIG_HEAD' is created by commands that move your 'HEAD' in a drastic
-way, to record the position of the 'HEAD' before their operation, so that
+`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic
+way, to record the position of the `HEAD` before their operation, so that
you can easily change the tip of the branch back to the state before you ran
them.
-'MERGE_HEAD' records the commit(s) which you are merging into your branch
+`MERGE_HEAD` records the commit(s) which you are merging into your branch
when you run `git merge`.
-'CHERRY_PICK_HEAD' records the commit which you are cherry-picking
+`CHERRY_PICK_HEAD` records the commit which you are cherry-picking
when you run `git cherry-pick`.
+
Note that any of the 'refs/*' cases above may come either from
@@ -59,7 +59,7 @@ While the ref name encoding is unspecified, UTF-8 is preferred as
some output processing may assume ref names in UTF-8.
'@'::
- '@' alone is a shortcut for 'HEAD'.
+ '@' alone is a shortcut for `HEAD`.
'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
A ref followed by the suffix '@' with a date specification
@@ -71,7 +71,7 @@ some output processing may assume ref names in UTF-8.
existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state
of your *local* ref at a given time; e.g., what was in your local
'master' branch last week. If you want to look at commits made during
- certain times, see '--since' and '--until'.
+ certain times, see `--since` and `--until`.
'<refname>@{<n>}', e.g. 'master@\{1\}'::
A ref followed by the suffix '@' with an ordinal specification
@@ -101,7 +101,7 @@ some output processing may assume ref names in UTF-8.
'<branchname>@\{push\}', e.g. 'master@\{push\}', '@\{push\}'::
The suffix '@\{push}' reports the branch "where we would push to" if
`git push` were run while `branchname` was checked out (or the current
- 'HEAD' if no branchname is specified). Since our push destination is
+ `HEAD` if no branchname is specified). Since our push destination is
in a remote repository, of course, we report the local tracking branch
that corresponds to that branch (i.e., something in 'refs/remotes/').
+
@@ -237,58 +237,84 @@ SPECIFYING RANGES
-----------------
History traversing commands such as `git log` operate on a set
-of commits, not just a single commit. To these commands,
-specifying a single revision with the notation described in the
-previous section means the set of commits reachable from that
-commit, following the commit ancestry chain.
-
-To exclude commits reachable from a commit, a prefix '{caret}'
-notation is used. E.g. '{caret}r1 r2' means commits reachable
-from 'r2' but exclude the ones reachable from 'r1'.
-
-This set operation appears so often that there is a shorthand
-for it. When you have two commits 'r1' and 'r2' (named according
-to the syntax explained in SPECIFYING REVISIONS above), you can ask
-for commits that are reachable from r2 excluding those that are reachable
-from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
-
-A similar notation 'r1\...r2' is called symmetric difference
-of 'r1' and 'r2' and is defined as
-'r1 r2 --not $(git merge-base --all r1 r2)'.
-It is the set of commits that are reachable from either one of
-'r1' or 'r2' but not from both.
-
-In these two shorthands, you can omit one end and let it default to HEAD.
+of commits, not just a single commit.
+
+For these commands,
+specifying a single revision, using the notation described in the
+previous section, means the set of commits `reachable` from the given
+commit.
+
+A commit's reachable set is the commit itself and the commits in
+its ancestry chain.
+
+
+Commit Exclusions
+~~~~~~~~~~~~~~~~~
+
+'{caret}<rev>' (caret) Notation::
+ To exclude commits reachable from a commit, a prefix '{caret}'
+ notation is used. E.g. '{caret}r1 r2' means commits reachable
+ from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and
+ its ancestors).
+
+Dotted Range Notations
+~~~~~~~~~~~~~~~~~~~~~~
+
+The '..' (two-dot) Range Notation::
+ The '{caret}r1 r2' set operation appears so often that there is a shorthand
+ for it. When you have two commits 'r1' and 'r2' (named according
+ to the syntax explained in SPECIFYING REVISIONS above), you can ask
+ for commits that are reachable from r2 excluding those that are reachable
+ from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
+
+The '...' (three dot) Symmetric Difference Notation::
+ A similar notation 'r1\...r2' is called symmetric difference
+ of 'r1' and 'r2' and is defined as
+ 'r1 r2 --not $(git merge-base --all r1 r2)'.
+ It is the set of commits that are reachable from either one of
+ 'r1' (left side) or 'r2' (right side) but not from both.
+
+In these two shorthand notations, you can omit one end and let it default to HEAD.
For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
did I do since I forked from the origin branch?" Similarly, '..origin'
is a shorthand for 'HEAD..origin' and asks "What did the origin do since
I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an
empty range that is both reachable and unreachable from HEAD.
-Two other shorthands for naming a set that is formed by a commit
-and its parent commits exist. The 'r1{caret}@' notation means all
-parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes
-all of its parents.
+Other <rev>{caret} Parent Shorthand Notations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Two other shorthands exist, particularly useful for merge commits,
+for naming a set that is formed by a commit and its parent commits.
+
+The 'r1{caret}@' notation means all parents of 'r1'.
+
+The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
+By itself, this notation denotes the single commit 'r1'.
+
+While '<rev>{caret}<n>' was about specifying a single commit parent, these
+two notations consider all its parents. For example you can say
+'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.
-To summarize:
+Revision Range Summary
+----------------------
'<rev>'::
- Include commits that are reachable from (i.e. ancestors of)
- <rev>.
+ Include commits that are reachable from <rev> (i.e. <rev> and its
+ ancestors).
'{caret}<rev>'::
- Exclude commits that are reachable from (i.e. ancestors of)
- <rev>.
+ Exclude commits that are reachable from <rev> (i.e. <rev> and its
+ ancestors).
'<rev1>..<rev2>'::
Include commits that are reachable from <rev2> but exclude
those that are reachable from <rev1>. When either <rev1> or
- <rev2> is omitted, it defaults to 'HEAD'.
+ <rev2> is omitted, it defaults to `HEAD`.
'<rev1>\...<rev2>'::
Include commits that are reachable from either <rev1> or
<rev2> but exclude those that are reachable from both. When
- either <rev1> or <rev2> is omitted, it defaults to 'HEAD'.
+ either <rev1> or <rev2> is omitted, it defaults to `HEAD`.
'<rev>{caret}@', e.g. 'HEAD{caret}@'::
A suffix '{caret}' followed by an at sign is the same as listing
@@ -300,16 +326,27 @@ To summarize:
as giving commit '<rev>' and then all its parents prefixed with
'{caret}' to exclude them (and their ancestors).
-Here are a handful of examples:
-
- D G H D
- D F G H I J D F
- ^G D H D
- ^D B E I J F B
- B..C C
- B...C G H D E B C
- ^D B C E I J F B C
- C I J F C
- C^@ I J F
- C^! C
- F^! D G H D F
+Here are a handful of examples using the Loeliger illustration above,
+with each step in the notation's expansion and selection carefully
+spelt out:
+
+ Args Expanded arguments Selected commits
+ D G H D
+ D F G H I J D F
+ ^G D H D
+ ^D B E I J F B
+ ^D B C E I J F B C
+ C I J F C
+ B..C = ^B C C
+ B...C = B ^F C G H D E B C
+ C^@ = C^1
+ = F I J F
+ B^@ = B^1 B^2 B^3
+ = D E F D G H E F I J
+ C^! = C ^C^@
+ = C ^C^1
+ = C ^F C
+ B^! = B ^B^@
+ = B ^B^1 ^B^2 ^B^3
+ = B ^D ^E ^F B
+ F^! D = F ^I ^J D G H D F
diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt
index ad7a5bddd2..28f5a8b715 100644
--- a/Documentation/technical/api-hashmap.txt
+++ b/Documentation/technical/api-hashmap.txt
@@ -104,6 +104,11 @@ If `free_entries` is true, each hashmap_entry in the map is freed as well
`entry` points to the entry to initialize.
+
`hash` is the hash code of the entry.
++
+The hashmap_entry structure does not hold references to external resources,
+and it is safe to just discard it once you are done with it (i.e. if
+your structure was allocated with xmalloc(), you can just free(3) it,
+and if it is on stack, you can just let it go out of scope).
`void *hashmap_get(const struct hashmap *map, const void *key, const void *keydata)`::
diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt
index 8b36343802..736f3894a8 100644
--- a/Documentation/technical/pack-protocol.txt
+++ b/Documentation/technical/pack-protocol.txt
@@ -307,7 +307,7 @@ In multi_ack mode:
ready to make a packfile, it will blindly ACK all 'have' obj-ids
back to the client.
- * the server will then send a 'NACK' and then wait for another response
+ * the server will then send a 'NAK' and then wait for another response
from the client - either a 'done' or another list of 'have' lines.
In multi_ack_detailed mode:
@@ -454,7 +454,8 @@ The reference discovery phase is done nearly the same way as it is in the
fetching protocol. Each reference obj-id and name on the server is sent
in packet-line format to the client, followed by a flush-pkt. The only
real difference is that the capability listing is different - the only
-possible values are 'report-status', 'delete-refs' and 'ofs-delta'.
+possible values are 'report-status', 'delete-refs', 'ofs-delta' and
+'push-options'.
Reference Update Request and Packfile Transfer
----------------------------------------------
@@ -465,9 +466,10 @@ that it wants to update, it sends a line listing the obj-id currently on
the server, the obj-id the client would like to update it to and the name
of the reference.
-This list is followed by a flush-pkt and then the packfile that should
-contain all the objects that the server will need to complete the new
-references.
+This list is followed by a flush-pkt. Then the push options are transmitted
+one per packet followed by another flush-pkt. After that the packfile that
+should contain all the objects that the server will need to complete the new
+references will be sent.
----
update-request = *shallow ( command-list | push-cert ) [packfile]
diff --git a/Documentation/technical/protocol-capabilities.txt b/Documentation/technical/protocol-capabilities.txt
index eaab6b4ac7..4c28d3a8ae 100644
--- a/Documentation/technical/protocol-capabilities.txt
+++ b/Documentation/technical/protocol-capabilities.txt
@@ -253,6 +253,15 @@ atomic pushes. If the pushing client requests this capability, the server
will update the refs in one atomic transaction. Either all refs are
updated or none.
+push-options
+------------
+
+If the server sends the 'push-options' capability it is able to accept
+push options after the update commands have been sent, but before the
+packfile is streamed. If the pushing client requests this capability,
+the server will pass the options to the pre- and post- receive hooks
+that process this push request.
+
allow-tip-sha1-in-want
----------------------
diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt
index bf30167ae3..ecedb34bba 100644
--- a/Documentation/technical/protocol-common.txt
+++ b/Documentation/technical/protocol-common.txt
@@ -67,9 +67,9 @@ with non-binary data the same whether or not they contain the trailing
LF (stripping the LF if present, and not complaining when it is
missing).
-The maximum length of a pkt-line's data component is 65520 bytes.
-Implementations MUST NOT send pkt-line whose length exceeds 65524
-(65520 bytes of payload + 4 bytes of length data).
+The maximum length of a pkt-line's data component is 65516 bytes.
+Implementations MUST NOT send pkt-line whose length exceeds 65520
+(65516 bytes of payload + 4 bytes of length data).
Implementations SHOULD NOT send an empty pkt-line ("0004").
diff --git a/Documentation/technical/signature-format.txt b/Documentation/technical/signature-format.txt
new file mode 100644
index 0000000000..2c9406a56a
--- /dev/null
+++ b/Documentation/technical/signature-format.txt
@@ -0,0 +1,186 @@
+Git signature format
+====================
+
+== Overview
+
+Git uses cryptographic signatures in various places, currently objects (tags,
+commits, mergetags) and transactions (pushes). In every case, the command which
+is about to create an object or transaction determines a payload from that,
+calls gpg to obtain a detached signature for the payload (`gpg -bsa`) and
+embeds the signature into the object or transaction.
+
+Signatures always begin with `-----BEGIN PGP SIGNATURE-----`
+and end with `-----END PGP SIGNATURE-----`, unless gpg is told to
+produce RFC1991 signatures which use `MESSAGE` instead of `SIGNATURE`.
+
+The signed payload and the way the signature is embedded depends
+on the type of the object resp. transaction.
+
+== Tag signatures
+
+- created by: `git tag -s`
+- payload: annotated tag object
+- embedding: append the signature to the unsigned tag object
+- example: tag `signedtag` with subject `signed tag`
+
+----
+object 04b871796dc0420f8e7561a895b52484b701d51a
+type commit
+tag signedtag
+tagger C O Mitter <committer@example.com> 1465981006 +0000
+
+signed tag
+
+signed tag message body
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1
+
+iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
+rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
+8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
+q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
+rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
+lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
+=jpXa
+-----END PGP SIGNATURE-----
+----
+
+- verify with: `git verify-tag [-v]` or `git tag -v`
+
+----
+gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg: There is no indication that the signature belongs to the owner.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
+object 04b871796dc0420f8e7561a895b52484b701d51a
+type commit
+tag signedtag
+tagger C O Mitter <committer@example.com> 1465981006 +0000
+
+signed tag
+
+signed tag message body
+----
+
+== Commit signatures
+
+- created by: `git commit -S`
+- payload: commit object
+- embedding: header entry `gpgsig`
+ (content is preceded by a space)
+- example: commit with subject `signed commit`
+
+----
+tree eebfed94e75e7760540d1485c740902590a00332
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example.com> 1465981137 +0000
+committer C O Mitter <committer@example.com> 1465981137 +0000
+gpgsig -----BEGIN PGP SIGNATURE-----
+ Version: GnuPG v1
+
+ iQEcBAABAgAGBQJXYRjRAAoJEGEJLoW3InGJ3IwIAIY4SA6GxY3BjL60YyvsJPh/
+ HRCJwH+w7wt3Yc/9/bW2F+gF72kdHOOs2jfv+OZhq0q4OAN6fvVSczISY/82LpS7
+ DVdMQj2/YcHDT4xrDNBnXnviDO9G7am/9OE77kEbXrp7QPxvhjkicHNwy2rEflAA
+ zn075rtEERDHr8nRYiDh8eVrefSO7D+bdQ7gv+7GsYMsd2auJWi1dHOSfTr9HIF4
+ HJhWXT9d2f8W+diRYXGh4X0wYiGg6na/soXc+vdtDYBzIxanRqjg8jCAeo1eOTk1
+ EdTwhcTZlI0x5pvJ3H0+4hA2jtldVtmPM4OTB0cTrEWBad7XV6YgiyuII73Ve3I=
+ =jKHM
+ -----END PGP SIGNATURE-----
+
+signed commit
+
+signed commit message body
+----
+
+- verify with: `git verify-commit [-v]` (or `git show --show-signature`)
+
+----
+gpg: Signature made Wed Jun 15 10:58:57 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg: There is no indication that the signature belongs to the owner.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
+tree eebfed94e75e7760540d1485c740902590a00332
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example.com> 1465981137 +0000
+committer C O Mitter <committer@example.com> 1465981137 +0000
+
+signed commit
+
+signed commit message body
+----
+
+== Mergetag signatures
+
+- created by: `git merge` on signed tag
+- payload/embedding: the whole signed tag object is embedded into
+ the (merge) commit object as header entry `mergetag`
+- example: merge of the signed tag `signedtag` as above
+
+----
+tree c7b1cff039a93f3600a1d18b82d26688668c7dea
+parent c33429be94b5f2d3ee9b0adad223f877f174b05d
+parent 04b871796dc0420f8e7561a895b52484b701d51a
+author A U Thor <author@example.com> 1465982009 +0000
+committer C O Mitter <committer@example.com> 1465982009 +0000
+mergetag object 04b871796dc0420f8e7561a895b52484b701d51a
+ type commit
+ tag signedtag
+ tagger C O Mitter <committer@example.com> 1465981006 +0000
+
+ signed tag
+
+ signed tag message body
+ -----BEGIN PGP SIGNATURE-----
+ Version: GnuPG v1
+
+ iQEcBAABAgAGBQJXYRhOAAoJEGEJLoW3InGJklkIAIcnhL7RwEb/+QeX9enkXhxn
+ rxfdqrvWd1K80sl2TOt8Bg/NYwrUBw/RWJ+sg/hhHp4WtvE1HDGHlkEz3y11Lkuh
+ 8tSxS3qKTxXUGozyPGuE90sJfExhZlW4knIQ1wt/yWqM+33E9pN4hzPqLwyrdods
+ q8FWEqPPUbSJXoMbRPw04S5jrLtZSsUWbRYjmJCHzlhSfFWW4eFd37uquIaLUBS0
+ rkC3Jrx7420jkIpgFcTI2s60uhSQLzgcCwdA2ukSYIRnjg/zDkj8+3h/GaROJ72x
+ lZyI6HWixKJkWw8lE9aAOD9TmTW9sFJwcVAzmAuFX2kUreDUKMZduGcoRYGpD7E=
+ =jpXa
+ -----END PGP SIGNATURE-----
+
+Merge tag 'signedtag' into downstream
+
+signed tag
+
+signed tag message body
+
+# gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
+# gpg: Good signature from "Eris Discordia <discord@example.net>"
+# gpg: WARNING: This key is not certified with a trusted signature!
+# gpg: There is no indication that the signature belongs to the owner.
+# Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
+----
+
+- verify with: verification is embedded in merge commit message by default,
+ alternatively with `git show --show-signature`:
+
+----
+commit 9863f0c76ff78712b6800e199a46aa56afbcbd49
+merged tag 'signedtag'
+gpg: Signature made Wed Jun 15 10:56:46 2016 CEST using RSA key ID B7227189
+gpg: Good signature from "Eris Discordia <discord@example.net>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg: There is no indication that the signature belongs to the owner.
+Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
+Merge: c33429b 04b8717
+Author: A U Thor <author@example.com>
+Date: Wed Jun 15 09:13:29 2016 +0000
+
+ Merge tag 'signedtag' into downstream
+
+ signed tag
+
+ signed tag message body
+
+ # gpg: Signature made Wed Jun 15 08:56:46 2016 UTC using RSA key ID B7227189
+ # gpg: Good signature from "Eris Discordia <discord@example.net>"
+ # gpg: WARNING: This key is not certified with a trusted signature!
+ # gpg: There is no indication that the signature belongs to the owner.
+ # Primary key fingerprint: D4BE 2231 1AD3 131E 5EDA 29A4 6109 2E85 B722 7189
+----