diff options
Diffstat (limited to 'Documentation')
40 files changed, 1592 insertions, 94 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e39e2815b..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 @@ -146,7 +147,7 @@ else ASCIIDOC_EXTRA += -a git-asciidoc-no-roff endif endif -ifdef MAN_BOLD_LITERAL +ifndef NO_MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif ifdef DOCBOOK_SUPPRESS_SP @@ -204,6 +205,7 @@ ifndef V QUIET_DBLATEX = @echo ' ' DBLATEX $@; QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; QUIET_GEN = @echo ' ' GEN $@; + QUIET_LINT = @echo ' ' LINT $@; QUIET_STDERR = 2> /dev/null QUIET_SUBDIR0 = +@subdir= QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ @@ -427,4 +429,7 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done +lint-docs:: + $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl + .PHONY: FORCE diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.txt new file mode 100644 index 0000000000..4783e25ce1 --- /dev/null +++ b/Documentation/RelNotes/2.10.0.txt @@ -0,0 +1,268 @@ +Git 2.10 Release Notes +====================== + +Backward compatibility notes +---------------------------- + +Updates since v2.9 +------------------ + +UI, Workflows & Features + + * "git pull --rebase --verify-signature" learned to warn the user + that "--verify-signature" is a no-op when rebasing. + + * An upstream project can make a recommendation to shallowly clone + some submodules in the .gitmodules file it ships. + + * "git worktree add" learned that '-' can be used as a short-hand for + "@{-1}", the previous branch. + + * Update the funcname definition to support css files. + + * The completion script (in contrib/) learned to complete "git + status" options. + + * Messages that are generated by auto gc during "git push" on the + receiving end are now passed back to the sending end in such a way + 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. + (merge 46e3d17 jk/add-i-diff-compact-heuristics later to maint). + + * "upload-pack" allows a custom "git pack-objects" replacement when + responding to "fetch/clone" via the uploadpack.packObjectsHook. + (merge 20b20a2 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. + (merge 066790d nd/graph-width-padded later to maint). + + * 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). + + * A couple of "git svn" updates. + + +Performance, Internal Implementation, Development Support etc. + + * "git fast-import" learned the same performance trick to avoid + creating too small a packfile as "git fetch" and "git push" have, + using *.unpackLimit configuration. + + * When "git daemon" is run without --[init-]timeout specified, a + 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. + + * 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 a struct string_list that is + allocated with all NULs happens to be STRING_LIST_INIT_NODUP kind, + 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. + (merge b7410f6 km/fetch-do-not-free-remote-name later to maint). + + * "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. + (merge 43ec550 jk/bisect-show-tree later to maint). + + * 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. + (merge cc6ee97 mg/signature-doc later to maint). + + * 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. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.9 +---------------- + +Unless otherwise noted, all the fixes since v2.8 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * The commands in `git log` family take %C(auto) in a custom format + string. This unconditionally turned the color on, ignoring + --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. + + * "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. + + * compat/regex code did not cleanly compile. + + * 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. + + * 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. + (merge 18a74a0 sb/clone-shallow-passthru later to maint). + + * Fix unnecessarily waste in the idiomatic use of ': ${VAR=default}' + to set the default value, without enclosing it in double quotes. + (merge 01247e0 lc/shell-default-value-noexpand later to maint). + + * Some platform-specific code had non-ANSI strict declarations of C + functions that do not take any parameters, which has been + corrected. + (merge 0767172 js/mingw-parameter-less-c-functions later to maint). + + * 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. + (merge bab7483 jk/tzoffset-fix later to maint). + + * 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). + (merge d2addc3 ak/t7800-wo-readlink later to maint). + + * t/perf needs /usr/bin/time with GNU extension; the invocation of it + is updated to "gtime" on Darwin. + (merge e3efa94 js/perf-on-apple later to maint). + + * 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_. + (merge 09667d0 ao/p4-has-branch-prefix-fix later to maint). + + * 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. + (merge f793582 jn/preformatted-doc-url later to maint). + + * 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. + (merge 054a5ae js/find-commit-subject-ignore-leading-blanks later to maint). + + * 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. + (merge 3d0a833 js/color-on-windows-comment later to maint). + + * Other minor clean-ups and documentation updates + (merge e51b0df pb/commit-editmsg-path later to maint). + (merge b333d0d jk/send-pack-stdio later to maint). + (merge fcf0fe9 lf/sideband-returns-void later to maint). + (merge 5819c2e sb/t5614-modernize later to maint). + (merge fe0537a cb/t7810-test-label-fix later to maint). + (merge 412b9a1 jc/t2300-setup later to maint). diff --git a/Documentation/RelNotes/2.9.0.txt b/Documentation/RelNotes/2.9.0.txt new file mode 100644 index 0000000000..b61d36712f --- /dev/null +++ b/Documentation/RelNotes/2.9.0.txt @@ -0,0 +1,512 @@ +Git 2.9 Release Notes +===================== + +Backward compatibility notes +---------------------------- + +The end-user facing Porcelain level commands in the "git diff" and +"git log" family by default enable the rename detection; you can still +use "diff.renames" configuration variable to disable this. + +Merging two branches that have no common ancestor with "git merge" is +by default forbidden now to prevent creating such an unusual merge by +mistake. + +The output formats of "git log" that indents the commit log message by +4 spaces now expands HT in the log message by default. You can use +the "--no-expand-tabs" option to disable this. + +"git commit-tree" plumbing command required the user to always sign +its result when the user sets the commit.gpgsign configuration +variable, which was an ancient mistake, which this release corrects. +A script that drives commit-tree, if it relies on this mistake, now +needs to read commit.gpgsign and pass the -S option as necessary. + + +Updates since v2.8 +------------------ + +UI, Workflows & Features + + * Comes with git-multimail 1.3.1 (in contrib/). + + * The end-user facing commands like "git diff" and "git log" + now enable the rename detection by default. + + * The credential.helper configuration variable is cumulative and + there is no good way to override it from the command line. As + a special case, giving an empty string as its value now serves + as the signal to clear the values specified in various files. + + * A new "interactive.diffFilter" configuration can be used to + customize the diff shown in "git add -i" sessions. + + * "git p4" now allows P4 author names to be mapped to Git author + names. + + * "git rebase -x" can be used without passing "-i" option. + + * "git -c credential.<var>=<value> submodule" can now be used to + propagate configuration variables related to credential helper + down to the submodules. + + * "git tag" can create an annotated tag without explicitly given an + "-a" (or "-s") option (i.e. when a tag message is given). A new + configuration variable, tag.forceSignAnnotated, can be used to tell + the command to create signed tag in such a situation. + + * "git merge" used to allow merging two branches that have no common + base by default, which led to a brand new history of an existing + project created and then get pulled by an unsuspecting maintainer, + which allowed an unnecessary parallel history merged into the + existing project. The command has been taught not to allow this by + default, with an escape hatch "--allow-unrelated-histories" option + to be used in a rare event that merges histories of two projects + that started their lives independently. + + * "git pull" has been taught to pass the "--allow-unrelated-histories" + option to underlying "git merge". + + * "git apply -v" learned to report paths in the patch that were + skipped via --include/--exclude mechanism or being outside the + current working directory. + + * Shell completion (in contrib/) updates. + + * The commit object name reported when "rebase -i" stops has been + shortened. + + * "git worktree add" can be given "--no-checkout" option to only + create an empty worktree without checking out the files. + + * "git mergetools" learned to drive ExamDiff. + + * "git pull --rebase" learned "--[no-]autostash" option, so that + the rebase.autostash configuration variable set to true can be + overridden from the command line. + + * When "git log" shows the log message indented by 4-spaces, the + remainder of a line after a HT does not align in the way the author + originally intended. The command now expands tabs by default to help + such a case, and allows the users to override it with a new option, + "--no-expand-tabs". + + * "git send-email" now uses a more readable timestamps when + formulating a message ID. + + * "git rerere" can encounter two or more files with the same conflict + signature that have to be resolved in different ways, but there was + no way to record these separate resolutions. + + * "git p4" learned to record P4 jobs in Git commit that imports from + the history in Perforce. + + * "git describe --contains" often made a hard-to-justify choice of + tag to name a given commit, because it tried to come up + with a name with smallest number of hops from a tag, causing an old + commit whose close descendant that is recently tagged were not + described with respect to an old tag but with a newer tag. It did + not help that its computation of "hop" count was further tweaked to + penalize being on a side branch of a merge. The logic has been + updated to favor using the tag with the oldest tagger date, which + is a lot easier to explain to the end users: "We describe a commit + in terms of the (chronologically) oldest tag that contains the + commit." + + * "git clone" learned the "--shallow-submodules" option. + + * HTTP transport clients learned to throw extra HTTP headers at the + server, specified via http.extraHeader configuration variable. + + * The "--compaction-heuristic" option to "git diff" family of + commands enables a heuristic to make the patch output more readable + by using a blank line as a strong hint that the contents before and + after it belong to logically separate units. It is still + experimental. + + * A new configuration variable core.hooksPath allows customizing + where the hook directory is. + + * An earlier addition of "sanitize_submodule_env" with 14111fc4 (git: + submodule honor -c credential.* from command line, 2016-02-29) + turned out to be a convoluted no-op; implement what it wanted to do + correctly, and stop filtering settings given via "git -c var=val". + + * "git commit --dry-run" reported "No, no, you cannot commit." in one + case where "git commit" would have allowed you to commit, and this + improves it a little bit ("git commit --dry-run --short" still does + not give you the correct answer, for example). This is a stop-gap + measure in that "commit --short --dry-run" still gives an incorrect + result. + + * The experimental "multiple worktree" feature gains more safety to + forbid operations on a branch that is checked out or being actively + worked on elsewhere, by noticing that e.g. it is being rebased. + + * "git format-patch" learned a new "--base" option to record what + (public, well-known) commit the original series was built on in + its output. + + * "git commit" learned to pay attention to the "commit.verbose" + configuration variable and act as if the "--verbose" option + was given from the command line. + + * Updated documentation gives hints to GMail users with two-factor + auth enabled that they need app-specific-password when using + "git send-email". + + * The manpage output of our documentation did not render well in + terminal; typeset literals in bold by default to make them stand + out more. + + * The mark-up in the top-level README.md file has been updated to + typeset CLI command names differently from the body text. + + +Performance, Internal Implementation, Development Support etc. + + * The embedded args argv-array in the child process is used to build + the command line to run pack-objects instead of using a separate + array of strings. + + * A test for tags has been restructured so that more parts of it can + easily be run on a platform without a working GnuPG. + + * The startup_info data, which records if we are working inside a + repository (among other things), are now uniformly available to Git + subcommand implementations, and Git avoids attempting to touch + references when we are not in a repository. + + * The command line argument parser for "receive-pack" has been + rewritten to use parse-options. + + * A major part of "git submodule update" has been ported to C to take + advantage of the recently added framework to run download tasks in + parallel. Other updates to "git submodule" that move pieces of + logic to C continues. + + * Rename bunch of tests on "git clone" for better organization. + + * The tests that involve running httpd leaked the system-wide + configuration in /etc/gitconfig to the tested environment. + + * Build updates for MSVC. + + * The repository set-up sequence has been streamlined (the biggest + change is that there is no longer git_config_early()), so that we + do not attempt to look into refs/* when we know we do not have a + Git repository. + + * Code restructuring around the "refs" API to prepare for pluggable + refs backends. + + * Sources to many test helper binaries and the generated helpers + have been moved to t/helper/ subdirectory to reduce clutter at the + top level of the tree. + + * Unify internal logic between "git tag -v" and "git verify-tag" + commands by making one directly call into the other. + + * "merge-recursive" strategy incorrectly checked if a path that is + involved in its internal merge exists in the working tree. + + * The test scripts for "git p4" (but not "git p4" implementation + itself) has been updated so that they would work even on a system + where the installed version of Python is python 3. + + * As nobody maintains our in-tree git.spec.in and distros use their + own spec file, we stopped pretending that we support "make rpm". + + * Move from "unsigned char[20]" to "struct object_id" continues. + + * The code for warning_errno/die_errno has been refactored and a new + error_errno() reporting helper is introduced. + (merge 1da045f nd/error-errno later to maint). + + * Running tests with '-x' option to trace the individual command + executions is a useful way to debug test scripts, but some tests + that capture the standard error stream and check what the command + said can be broken with the trace output mixed in. When running + our tests under "bash", however, we can redirect the trace output + to another file descriptor to keep the standard error of programs + being tested intact. + + * t0040 had too many unnecessary repetitions in its test data. Teach + test-parse-options program so that a caller can tell what it + expects in its output, so that these repetitions can be cleaned up. + + * Add perf test for "rebase -i". + + * Common mistakes when writing gitlink: in our documentation are + found by "make check-docs". + + * t9xxx series has been updated primarily for readability, while + fixing small bugs in it. A few scripted Porcelain commands have + also been updated to fix possible bugs around their use of + "test -z" and "test -n". + + * CI test was taught to run git-svn tests. + + * "git cat-file --batch-all" has been sped up, by taking advantage + of the fact that it does not have to read a list of objects, in two + ways. + + * test updates to make it more readable and maintainable. + (merge e6273f4 es/t1500-modernize later to maint). + + * "make DEVELOPER=1" worked as expected; setting DEVELOPER=1 in + config.mak didn't. + (merge 51dd3e8 mm/makefile-developer-can-be-in-config-mak later to maint). + + * The way how "submodule--helper list" signals unmatch error to its + callers has been updated. + + * A bash-ism "local" has been removed from "git submodule" scripted + Porcelain. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.8 +---------------- + +Unless otherwise noted, all the fixes since v2.8 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * "git config --get-urlmatch", unlike other variants of the "git + config --get" family, did not signal error with its exit status + when there was no matching configuration. + + * The "--local-env-vars" and "--resolve-git-dir" options of "git + rev-parse" failed to work outside a repository when the command's + option parsing was rewritten in 1.8.5 era. + + * "git index-pack --keep[=<msg>] pack-$name.pack" simply did not work. + + * Fetching of history by naming a commit object name directly didn't + work across remote-curl transport. + + * A small memory leak in an error codepath has been plugged in xdiff + code. + + * strbuf_getwholeline() did not NUL-terminate the buffer on certain + corner cases in its error codepath. + + * "git mergetool" did not work well with conflicts that both sides + deleted. + + * "git send-email" had trouble parsing alias file in mailrc format + when lines in it had trailing whitespaces on them. + + * When "git merge --squash" stopped due to conflict, the concluding + "git commit" failed to read in the SQUASH_MSG that shows the log + messages from all the squashed commits. + + * "git merge FETCH_HEAD" dereferenced NULL pointer when merging + nothing into an unborn history (which is arguably unusual usage, + which perhaps was the reason why nobody noticed it). + + * When "git worktree" feature is in use, "git branch -d" allowed + deletion of a branch that is checked out in another worktree, + which was wrong. + + * When "git worktree" feature is in use, "git branch -m" renamed a + branch that is checked out in another worktree without adjusting + the HEAD symbolic ref for the worktree. + + * "git diff -M" used to work better when two originally identical + files A and B got renamed to X/A and X/B by pairing A to X/A and B + to X/B, but this was broken in the 2.0 timeframe. + + * "git send-pack --all <there>" was broken when its command line + option parsing was written in the 2.6 timeframe. + + * "git format-patch --help" showed `-s` and `--no-patch` as if these + are valid options to the command. We already hide `--patch` option + from the documentation, because format-patch is about showing the + diff, and the documentation now hides these options as well. + + * When running "git blame $path" with unnormalized data in the index + for the path, the data in the working tree was blamed, even though + "git add" would not have changed what is already in the index, due + to "safe crlf" that disables the line-end conversion. It has been + corrected. + + * A change back in version 2.7 to "git branch" broke display of a + symbolic ref in a non-standard place in the refs/ hierarchy (we + expect symbolic refs to appear in refs/remotes/*/HEAD to point at + the primary branch the remote has, and as .git/HEAD to point at the + branch we locally checked out). + + * A partial rewrite of "git submodule" in the 2.7 timeframe changed + the way the gitdir: pointer in the submodules point at the real + repository location to use absolute paths by accident. This has + been corrected. + + * "git commit" misbehaved in a few minor ways when an empty message + is given via -m '', all of which has been corrected. + + * Support for CRAM-MD5 authentication method in "git imap-send" did + not work well. + + * Upcoming OpenSSL 1.1.0 will break compilation by updating a few API + elements we use in imap-send, which has been adjusted for the change. + + * The socks5:// proxy support added back in 2.6.4 days was not aware + that socks5h:// proxies behave differently from socks5:// proxies. + + * "git config" had a codepath that tried to pass a NULL to + printf("%s"), which nobody seems to have noticed. + + * On Cygwin, object creation uses the "create a temporary and then + rename it to the final name" pattern, not "create a temporary, + hardlink it to the final name and then unlink the temporary" + pattern. + + This is necessary to use Git on Windows shared directories, and is + already enabled for the MinGW and plain Windows builds. It also + has been used in Cygwin packaged versions of Git for quite a while. + See http://thread.gmane.org/gmane.comp.version-control.git/291853 + + * "merge-octopus" strategy did not ensure that the index is clean + when merge begins. + + * When "git merge" notices that the merge can be resolved purely at + the tree level (without having to merge blobs) and the resulting + tree happens to already exist in the object store, it forgot to + update the index, which left an inconsistent state that would + break later operations. + + * "git submodule" reports the paths of submodules the command + recurses into, but these paths were incorrectly reported when + the command was not run from the root level of the superproject. + + * The "user.useConfigOnly" configuration variable makes it an error + if users do not explicitly set user.name and user.email. However, + its check was not done early enough and allowed another error to + trigger, reporting that the default value we guessed from the + system setting was unusable. This was a suboptimal end-user + experience as we want the users to set user.name/user.email without + relying on the auto-detection at all. + + * "git mv old new" did not adjust the path for a submodule that lives + as a subdirectory inside old/ directory correctly. + + * "git replace -e" did not honour "core.editor" configuration. + + * "git push" from a corrupt repository that attempts to push a large + number of refs deadlocked; the thread to relay rejection notices + for these ref updates blocked on writing them to the main thread, + after the main thread at the receiving end notices that the push + failed and decides not to read these notices and return a failure. + + * mmap emulation on Windows has been optimized and work better without + consuming paging store when not needed. + + * A question by "git send-email" to ask the identity of the sender + has been updated. + + * UI consistency improvements for "git mergetool". + + * "git rebase -m" could be asked to rebase an entire branch starting + from the root, but failed by assuming that there always is a parent + commit to the first commit on the branch. + + * Fix a broken "p4 lfs" test. + + * Recent update to Git LFS broke "git p4" by changing the output from + its "lfs pointer" subcommand. + + * "git fetch" test t5510 was flaky while running a (forced) automagic + garbage collection. + + * Documentation updates to help contributors setting up Travis CI + test for their patches. + + * Some multi-byte encoding can have a backslash byte as a later part + of one letter, which would confuse "highlight" filter used in + gitweb. + + * "git commit-tree" plumbing command required the user to always sign + its result when the user sets the commit.gpgsign configuration + variable, which was an ancient mistake. Rework "git rebase" that + relied on this mistake so that it reads commit.gpgsign and pass (or + not pass) the -S option to "git commit-tree" to keep the end-user + expectation the same, while teaching "git commit-tree" to ignore + the configuration variable. This will stop requiring the users to + sign commit objects used internally as an implementation detail of + "git stash". + + * "http.cookieFile" configuration variable clearly wants a pathname, + but we forgot to treat it as such by e.g. applying tilde expansion. + + * Consolidate description of tilde-expansion that is done to + configuration variables that take pathname to a single place. + + * Correct faulty recommendation to use "git submodule deinit ." when + de-initialising all submodules, which would result in a strange + error message in a pathological corner case. + + * Many 'linkgit:<git documentation page>' references were broken, + which are all fixed with this. + + * "git rerere" can get confused by conflict markers deliberately left + by the inner merge step, because they are indistinguishable from + the real conflict markers left by the outermost merge which are + what the end user and "rerere" need to look at. This was fixed by + making the conflict markers left by the inner merges a bit longer. + (merge 0f9fd5c jc/ll-merge-internal later to maint). + + * CI test was taught to build documentation pages. + + * "git fsck" learned to catch NUL byte in a commit object as + potential error and warn. + + * Portability enhancement for "rebase -i" to help platforms whose + shell does not like "for i in <empty>" (which is not POSIX-kosher). + + * On Windows, .git and optionally any files whose name starts with a + dot are now marked as hidden, with a core.hideDotFiles knob to + customize this behaviour. + + * Documentation for "git merge --verify-signatures" has been updated + to clarify that the signature of only the commit at the tip is + verified. Also the phrasing used for signature and key validity is + adjusted to align with that used by OpenPGP. + + * A couple of bugs around core.autocrlf have been fixed. + + * Many commands normalize command line arguments from NFD to NFC + variant of UTF-8 on OSX, but commands in the "diff" family did + not, causing "git diff $path" to complain that no such path is + known to Git. They have been taught to do the normalization. + + * "git difftool" learned to handle unmerged paths correctly in + dir-diff mode. + + * The "are we talking with TTY, doing an interactive session?" + detection has been updated to work better for "Git for Windows". + + * We forgot to add "git log --decorate=auto" to documentation when we + added the feature back in v2.1.0 timeframe. + (merge 462cbb4 rj/log-decorate-auto later to maint). + + * "git fast-import --export-marks" would overwrite the existing marks + file even when it makes a dump from its custom die routine. + Prevent it from doing so when we have an import-marks file but + haven't finished reading it. + (merge f4beed6 fc/fast-import-broken-marks-file later to maint). + + * "git rebase -i", after it fails to auto-resolve the conflict, had + an unnecessary call to "git rerere" from its very early days, which + was spotted recently; the call has been removed. + (merge 7063693 js/rebase-i-dedup-call-to-rerere later to maint). + + * Other minor clean-ups and documentation updates + (merge cd82b7a pa/cherry-pick-doc-typo later to maint). + (merge 2bb73ae rs/patch-id-use-skip-prefix later to maint). + (merge aa20cbc rs/apply-name-terminate later to maint). + (merge fe17fc0 jc/t2300-setup later to maint). + (merge e256eec jk/shell-portability later to maint). diff --git a/Documentation/RelNotes/2.9.1.txt b/Documentation/RelNotes/2.9.1.txt new file mode 100644 index 0000000000..338394097e --- /dev/null +++ b/Documentation/RelNotes/2.9.1.txt @@ -0,0 +1,117 @@ +Git v2.9.1 Release Notes +======================== + +Fixes since v2.9 +---------------- + + * When "git daemon" is run without --[init-]timeout specified, a + 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. + + * The commands in `git log` family take %C(auto) in a custom format + string. This unconditionally turned the color on, ignoring + --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". + + * "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. + + * "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. + + * 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/config.txt b/Documentation/config.txt index 982b62009c..16dc22d9cf 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -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 @@ -633,6 +640,23 @@ core.attributesFile:: `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/attributes` is used instead. +core.hooksPath:: + By default Git will look for your hooks in the + '$GIT_DIR/hooks' directory. Set this to different path, + e.g. '/etc/git/hooks', and Git will try to find your hooks in + that directory, e.g. '/etc/git/hooks/pre-receive' instead of + in '$GIT_DIR/hooks/pre-receive'. ++ +The path can be either absolute or relative. A relative path is +taken as relative to the directory where the hooks are run (see +the "DESCRIPTION" section of linkgit:githooks[5]). ++ +This configuration variable is useful in cases where you'd like to +centrally configure your Git hooks instead of configuring them on a +per-repository basis, or as a more flexible and centralized +alternative to having an `init.templateDir` where you've changed +default hooks. + core.editor:: Commands such as `commit` and `tag` that lets you edit messages by launching an editor uses the value of this @@ -1124,11 +1148,16 @@ commit.template:: Specify the pathname of a file to use as the template for new commit messages. +commit.verbose:: + A boolean or int to specify the level of verbose with `git commit`. + See linkgit:git-commit[1]. + credential.helper:: Specify an external helper to be called when a username or password credential is needed; the helper may consult external - storage to avoid prompting the user for the credentials. See - linkgit:gitcredentials[7] for details. + storage to avoid prompting the user for the credentials. Note + that multiple helpers may be defined. See linkgit:gitcredentials[7] + for details. credential.useHttpPath:: When acquiring credentials, consider the "path" component of an http @@ -1167,6 +1196,15 @@ difftool.<tool>.cmd:: difftool.prompt:: Prompt before each invocation of the diff tool. +fastimport.unpackLimit:: + If the number of objects imported by linkgit:git-fast-import[1] + is below this limit, then the objects will be unpacked into + loose object files. However if the number of imported objects + equals or exceeds this limit then the pack will be stored as a + pack. Storing the pack from a fast-import can make the import + operation complete faster, especially on slow filesystems. If + not set, the value of `transfer.unpackLimit` is used instead. + fetch.recurseSubmodules:: This option can be either set to a boolean value or to 'on-demand'. Setting it to a boolean changes the behavior of fetch and pull to @@ -1272,6 +1310,10 @@ format.outputDirectory:: Set a custom directory to store the resulting files instead of the current working directory. +format.useAutoBase:: + A boolean value which lets you enable the `--base=auto` option of + format-patch by default. + filter.<driver>.clean:: The command which is used to convert the content of a worktree file to a blob upon checkin. See linkgit:gitattributes[5] for @@ -1668,6 +1710,12 @@ http.emptyAuth:: a username in the URL, as libcurl normally requires a username for authentication. +http.extraHeader:: + Pass an additional HTTP header when communicating with a server. If + more than one such entry exists, all of them are added as extra + headers. To allow overriding the settings inherited from the system + config, an empty value will reset the extra headers to the empty list. + http.cookieFile:: The pathname of a file containing previously stored cookie lines, which should be used @@ -1901,6 +1949,14 @@ interactive.singleKey:: setting is silently ignored if portable keystroke input is not available; requires the Perl module Term::ReadKey. +interactive.diffFilter:: + When an interactive command (such as `git add --patch`) shows + a colorized diff, git will pipe the diff through the shell + command defined by this configuration variable. The command may + mark up the diff further for human consumption, provided that it + retains a one-to-one correspondence with the lines in the + original diff. Defaults to disabled (no filtering). + log.abbrevCommit:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may @@ -1916,7 +1972,10 @@ log.decorate:: command. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the full ref name (including prefix) will be printed. - This is the same as the log commands `--decorate` option. + 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 + of the `git log`. log.follow:: If `true`, `git log` will act as if the `--follow` option was used when @@ -2748,6 +2807,17 @@ submodule.<name>.ignore:: "--ignore-submodules" option. The 'git submodule' commands are not affected by this setting. +submodule.fetchJobs:: + Specifies how many submodules are fetched/cloned at the same time. + A positive integer allows up to that number of submodules fetched + in parallel. A value of 0 will give some reasonable default. + If unset, it defaults to 1. + +tag.forceSignAnnotated:: + A boolean to specify whether annotated tags created should be GPG signed. + If `--annotate` is specified on the command line, it takes + precedence over this option. + tag.sort:: This variable controls the sort ordering of tags when displayed by linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the @@ -2829,6 +2899,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 0ddb7a6b4c..d5a5b17d50 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -108,9 +108,13 @@ diff.renameLimit:: detection; equivalent to the 'git diff' option `-l`. diff.renames:: - Tells Git to detect renames. If set to any boolean value, it - will enable basic rename detection. If set to "copies" or - "copy", it will detect copies, as well. + Whether and how Git detects renames. If set to "false", + rename detection is disabled. If set to "true", basic rename + detection is enabled. If set to "copies" or "copy", Git will + detect copies, as well. Defaults to true. Note that this + affects only 'git diff' Porcelain like linkgit:git-diff[1] and + linkgit:git-log[1], and not lower level commands such as + linkgit:git-diff-files[1]. diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space @@ -166,6 +170,11 @@ diff.tool:: include::mergetools-diff.txt[] +diff.compactionHeuristic:: + Set this option to `true` to enable an experimental heuristic that + shifts the hunk boundary in an attempt to make the resulting + patch easier to read. + diff.algorithm:: Choose a diff algorithm. The variants are as follows: + diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 3cb301556e..d9ae681d8f 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -63,6 +63,13 @@ ifndef::git-format-patch[] Synonym for `-p --raw`. endif::git-format-patch[] +--compaction-heuristic:: +--no-compaction-heuristic:: + These are to help debugging and tuning an experimental + heuristic (which is off by default) that shifts the hunk + boundary in an attempt to make the resulting patch easier + to read. + --minimal:: Spend extra time to make sure the smallest possible diff is produced. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index dcc68b9429..9eab1f5fa4 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -52,7 +52,7 @@ ifndef::git-pull[] -p:: --prune:: - After fetching, remove any remote-tracking references that no + Before fetching, remove any remote-tracking references that no longer exist on the remote. Tags are not subject to pruning if they are fetched only because of the default tag auto-following or due to a --tags option. However, if tags diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 8dd9e4f052..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:: diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index c95b715c8c..d35d771fc8 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -128,7 +128,7 @@ effect to your index in a row. --allow-empty-message:: By default, cherry-picking a commit with an empty message will fail. - This option overrides that behaviour, allowing commits with empty + This option overrides that behavior, allowing commits with empty messages to be cherry picked. --keep-redundant-commits:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index b7c467a001..ec41d3d698 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -14,8 +14,8 @@ SYNOPSIS [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--dissociate] [--separate-git-dir <git dir>] [--depth <depth>] [--[no-]single-branch] - [--recursive | --recurse-submodules] [--] <repository> - [<directory>] + [--recursive | --recurse-submodules] [--[no-]shallow-submodules] + [--jobs <n>] [--] <repository> [<directory>] DESCRIPTION ----------- @@ -191,7 +191,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. + 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, @@ -212,6 +213,9 @@ objects from the source repository into a pack in the cloned repository. repository does not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`, or `--mirror` is given) +--[no-]shallow-submodules:: + All submodules which are cloned will be shallow with a depth of 1. + --separate-git-dir=<git dir>:: Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, @@ -219,6 +223,10 @@ objects from the source repository into a pack in the cloned repository. The result is Git repository can be separated from working tree. +-j <n>:: +--jobs <n>:: + The number of submodules fetched at the same time. + Defaults to the `submodule.fetchJobs` option. <repository>:: The (possibly remote) repository to clone from. See the diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index ff130250be..002dae625e 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -61,8 +61,8 @@ OPTIONS stuck to the option without a space. --no-gpg-sign:: - Countermand `commit.gpgSign` configuration variable that is - set to force each and every commit to be signed. + Do not GPG-sign commit, to countermand a `--gpg-sign` option + given earlier on the command line. Commit Information diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 448f42c839..b0a294d3b5 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -290,7 +290,8 @@ configuration variable documented in linkgit:git-config[1]. what changes the commit has. Note that this diff output doesn't have its lines prefixed with '#'. This diff will not be a part - of the commit message. + of the commit message. See the `commit.verbose` configuration + variable in linkgit:git-config[1]. + If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index c105f2121e..2b762654bf 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -136,6 +136,8 @@ Performance and Compression Tuning Maximum size of each output packfile. The default is unlimited. +fastimport.unpackLimit:: + See linkgit:git-config[1] Performance ----------- diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 353f6351a0..9624c84a65 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -265,6 +265,11 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`. Output an all-zero hash in each patch's From header instead of the hash of the commit. +--base=<commit>:: + Record the base tree information to identify the state the + patch series applies to. See the BASE TREE INFORMATION section + below for details. + --root:: Treat the revision argument as a <revision range>, even if it is just a single commit (that would normally be treated as a @@ -520,6 +525,61 @@ This should help you to submit patches inline using KMail. 5. Back in the compose window: add whatever other text you wish to the message, complete the addressing and subject fields, and press send. +BASE TREE INFORMATION +--------------------- + +The base tree information block is used for maintainers or third party +testers to know the exact state the patch series applies to. It consists +of the 'base commit', which is a well-known commit that is part of the +stable part of the project history everybody else works off of, and zero +or more 'prerequisite patches', which are well-known patches in flight +that is not yet part of the 'base commit' that need to be applied on top +of 'base commit' in topological order before the patches can be applied. + +The 'base commit' is shown as "base-commit: " followed by the 40-hex of +the commit object name. A 'prerequisite patch' is shown as +"prerequisite-patch-id: " followed by the 40-hex 'patch id', which can +be obtained by passing the patch through the `git patch-id --stable` +command. + +Imagine that on top of the public commit P, you applied well-known +patches X, Y and Z from somebody else, and then built your three-patch +series A, B, C, the history would be like: + +................................................ +---P---X---Y---Z---A---B---C +................................................ + +With `git format-patch --base=P -3 C` (or variants thereof, e.g. with +`--cover-letter` of using `Z..C` instead of `-3 C` to specify the +range), the base tree information block is shown at the end of the +first message the command outputs (either the first patch, or the +cover letter), like this: + +------------ +base-commit: P +prerequisite-patch-id: X +prerequisite-patch-id: Y +prerequisite-patch-id: Z +------------ + +For non-linear topology, such as + +................................................ +---P---X---A---M---C + \ / + Y---Z---B +................................................ + +You can also use `git format-patch --base=P -3 C` to generate patches +for A, B and C, and the identifiers for P, X, Y, Z are appended at the +end of the first message. + +If set `--base=auto` in cmdline, it will track base commit automatically, +the base commit will be the merge base of tip commit of the remote-tracking +branch and revision-range specified in cmdline. +For a local branch, you need to track a remote branch by `git branch +--set-upstream-to` before using this option. EXAMPLES -------- diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt index 341a164b91..9d27197de8 100644 --- a/Documentation/git-init.txt +++ b/Documentation/git-init.txt @@ -130,7 +130,12 @@ The template directory will be one of the following (in order): - the default template directory: `/usr/share/git-core/templates`. The default template directory includes some directory structure, suggested -"exclude patterns" (see linkgit:gitignore[5]), and sample hook files (see linkgit:githooks[5]). +"exclude patterns" (see linkgit:gitignore[5]), and sample hook files. + +The sample hooks are all disabled by default, To enable one of the +sample hooks rename it by removing its `.sample` suffix. + +See linkgit:githooks[5] for more general info on hook execution. EXAMPLES -------- diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index e8dc9cab90..32246fdb00 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -29,12 +29,14 @@ OPTIONS (works only for a single file). --no-decorate:: ---decorate[=short|full|no]:: +--decorate[=short|full|auto|no]:: Print out the ref names of any commits that are shown. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the - full ref name (including prefix) will be printed. The default option - is 'short'. + 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. The default option is 'short'. --source:: Print out the ref name given on the command line by which each @@ -196,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-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-merge.txt b/Documentation/git-merge.txt index 07f7295ec8..b758d5556c 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -11,6 +11,7 @@ SYNOPSIS [verse] 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] + [--[no-]allow-unrelated-histories] [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] 'git merge' <msg> HEAD <commit>... 'git merge' --abort diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index ac7e6a38c0..c83aaf39c3 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -551,6 +551,17 @@ git-p4.keepEmptyCommits:: A changelist that contains only excluded files will be imported as an empty commit if this boolean option is set to true. +git-p4.mapUser:: + Map a P4 user to a name and email address in Git. Use a string + with the following format to create a mapping: ++ +------------- +git config --add git-p4.mapUser "p4user = First Last <mail@address.com>" +------------- ++ +A mapping will override any user information from P4. Mappings for +multiple P4 user can be defined. + Submit variables ~~~~~~~~~~~~~~~~ git-p4.detectRenames:: diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index a62a2a615d..d033b258e5 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -128,6 +128,15 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: Override earlier --rebase. +--autostash:: +--no-autostash:: + Before starting rebase, stash local modifications away (see + linkgit:git-stash[1]) if needed, and apply the stash when + done. `--no-autostash` is useful to override the `rebase.autoStash` + configuration variable (see linkgit:git-config[1]). ++ +This option is only valid when "--rebase" is used. + Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index a8078ff2a9..de222c81af 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -391,9 +391,6 @@ idea unless you know what you are doing (see BUGS below). final history. <cmd> will be interpreted as one or more shell commands. + -This option can only be used with the `--interactive` option -(see INTERACTIVE MODE below). -+ You may execute several commands by either using one instance of `--exec` with several commands: + @@ -406,6 +403,9 @@ or by giving more than one `--exec`: If `--autosquash` is used, "exec" lines will not be appended for the intermediate commits, and will only appear at the end of each squash/fixup series. ++ +This uses the `--interactive` machinery internally, but it can be run +without an explicit `--interactive`. --root:: Rebase all commits reachable from <branch>, instead of diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index 0c03eecff9..c5975234f4 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -128,6 +128,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-send-email.txt b/Documentation/git-send-email.txt index d85b878139..642d0ef199 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -450,6 +450,19 @@ edit ~/.gitconfig to specify your account settings: smtpUser = yourname@gmail.com smtpServerPort = 587 +If you have multifactor authentication setup on your gmail account, you will +need to generate an app-specific password for use with 'git send-email'. Visit +https://security.google.com/settings/security/apppasswords to setup an +app-specific password. Once setup, you can store it with the credentials +helper: + + $ git credential fill + protocol=smtp + host=smtp.gmail.com + username=youname@gmail.com + password=app-password + + Once your commits are ready to be sent to the mailing list, run the following commands: diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index ad851838cc..bf3bb372ee 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -15,8 +15,9 @@ SYNOPSIS 'git submodule' [--quiet] init [--] [<path>...] 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] - [-f|--force] [--rebase|--merge] [--reference <repository>] - [--depth <depth>] [--recursive] [--] [<path>...] + [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge] + [--reference <repository>] [--depth <depth>] [--recursive] + [--jobs <n>] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> @@ -384,6 +385,17 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. clone with a history truncated to the specified number of revisions. See linkgit:git-clone[1] +--[no-]recommend-shallow:: + This option is only valid for the update command. + The initial clone of a submodule will use the recommended + `submodule.<name>.shallow` as provided by the .gitmodules file + by default. To ignore the suggestions use `--no-recommend-shallow`. + +-j <n>:: +--jobs <n>:: + This option is only valid for the update command. + Clone new submodules in parallel with as many jobs. + Defaults to the `submodule.fetchJobs` option. <path>...:: Paths to submodule(s). When specified this will restrict the command diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index 935d3c27f2..7e17cade7f 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -459,6 +459,20 @@ Any other arguments are passed directly to 'git log' Gets the Subversion property given as the first argument, for a file. A specific revision can be specified with -r/--revision. +'propset':: + Sets the Subversion property given as the first argument, to the + value given as the second argument for the file given as the + third argument. ++ +Example: ++ +------------------------------------------------------------------------ +git svn propset svn:keywords "FreeBSD=%H" devel/py-tipper/Makefile +------------------------------------------------------------------------ ++ +This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file +'devel/py-tipper/Makefile'. + 'show-externals':: Shows the Subversion externals. Use -r/--revision to specify a specific revision. diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index dfd6b27682..7ecca8e247 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -78,7 +78,7 @@ OPTIONS -v:: --verify:: - Verify the gpg signature of the given tag names. + Verify the GPG signature of the given tag names. -n<num>:: <num> specifies how many lines from the annotation, if any, diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt index 0abc806ea9..822ad593af 100644 --- a/Documentation/git-upload-pack.txt +++ b/Documentation/git-upload-pack.txt @@ -9,8 +9,8 @@ git-upload-pack - Send objects packed back to git-fetch-pack SYNOPSIS -------- [verse] -'git-upload-pack' [--strict] [--timeout=<n>] <directory> - +'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc] + [--advertise-refs] <directory> DESCRIPTION ----------- Invoked by 'git fetch-pack', learns what @@ -25,12 +25,22 @@ repository. For push operations, see 'git send-pack'. OPTIONS ------- ---strict:: +--[no-]strict:: Do not try <directory>/.git/ if <directory> is no Git directory. --timeout=<n>:: Interrupt transfer after <n> seconds of inactivity. +--stateless-rpc:: + Perform only a single read-write cycle with stdin and stdout. + This fits with the HTTP POST request processing model where + a program may read the request, write a response, and must exit. + +--advertise-refs:: + Only the initial ref advertisement is output, and the program exits + immediately. This fits with the HTTP GET request model, where + no request content is received but a response must be produced. + <directory>:: The repository to sync from. diff --git a/Documentation/git-verify-commit.txt b/Documentation/git-verify-commit.txt index ecf4da16cf..92097f6673 100644 --- a/Documentation/git-verify-commit.txt +++ b/Documentation/git-verify-commit.txt @@ -12,7 +12,7 @@ SYNOPSIS DESCRIPTION ----------- -Validates the gpg signature created by 'git commit -S'. +Validates the GPG signature created by 'git commit -S'. OPTIONS ------- diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 62c76c1c89..7c4cfb0885 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,9 +9,9 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>] -'git worktree prune' [-n] [-v] [--expire <expire>] +'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>] 'git worktree list' [--porcelain] +'git worktree prune' [-n] [-v] [--expire <expire>] DESCRIPTION ----------- @@ -48,16 +48,13 @@ add <path> [<branch>]:: Create `<path>` and checkout `<branch>` into it. The new working directory is linked to the current repository, sharing everything except working -directory specific files such as HEAD, index, etc. +directory specific files such as HEAD, index, etc. `-` may also be +specified as `<branch>`; it is synonymous with `@{-1}`. + 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 @@ -65,6 +62,10 @@ 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). +prune:: + +Prune working tree information in $GIT_DIR/worktrees. + OPTIONS ------- @@ -87,6 +88,12 @@ OPTIONS With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" in linkgit:git-checkout[1]. +--[no-]checkout:: + By default, `add` checks out `<branch>`, however, `--no-checkout` can + be used to suppress checkout in order to make customizations, + such as configuring sparse-checkout. See "Sparse checkout" + in linkgit:git-read-tree[1]. + -n:: --dry-run:: With `prune`, do not remove anything; just report what it would diff --git a/Documentation/git.txt b/Documentation/git.txt index 56d579b583..c461701f57 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,6 +43,12 @@ 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.1/git.html[documentation for release 2.9.1] + +* release notes for + 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] * release notes for @@ -1078,6 +1084,14 @@ of clones and fetches. cloning of shallow repositories. See `GIT_TRACE` for available trace output options. +`GIT_TRACE_CURL`:: + Enables a curl full trace dump of all incoming and outgoing data, + including descriptive information, of the git transport protocol. + This is similar to doing curl `--trace-ascii` on the command line. + This option overrides setting the `GIT_CURL_VERBOSE` environment + variable. + See `GIT_TRACE` for available trace output options. + `GIT_LITERAL_PATHSPECS`:: Setting this variable to `1` will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index e3b1de8033..8882a3e914 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -525,6 +525,8 @@ patterns are available: - `csharp` suitable for source code in the C# language. +- `css` suitable for cascading style sheets. + - `fortran` suitable for source code in the Fortran language. - `fountain` suitable for Fountain documents. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 1c75be0803..f3a75d1ce1 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -106,6 +106,11 @@ variable, each helper will be tried in turn, and may provide a username, password, or nothing. Once Git has acquired both a username and a password, no more helpers will be tried. +If `credential.helper` is configured to the empty string, this resets +the helper list to empty (so you may override a helper set by a +lower-priority config file by configuring the empty-string helper, +followed by whatever set of helpers you would like). + CREDENTIAL CONTEXTS ------------------- diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index a2f59b194c..d82e912e55 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -7,24 +7,35 @@ githooks - Hooks used by Git SYNOPSIS -------- -$GIT_DIR/hooks/* +$GIT_DIR/hooks/* (or \`git config core.hooksPath`/*) DESCRIPTION ----------- -Hooks are little scripts you can place in `$GIT_DIR/hooks` -directory to trigger action at certain points. When -'git init' is run, a handful of example hooks are copied into the -`hooks` directory of the new repository, but by default they are -all disabled. To enable a hook, rename it by removing its `.sample` -suffix. +Hooks are programs you can place in a hooks directory to trigger +actions at certain points in git's execution. Hooks that don't have +the executable bit set are ignored. -NOTE: It is also a requirement for a given hook to be executable. -However - in a freshly initialized repository - the `.sample` files are -executable by default. +By default the hooks directory is `$GIT_DIR/hooks`, but that can be +changed via the `core.hooksPath` configuration variable (see +linkgit:git-config[1]). -This document describes the currently defined hooks. +Before Git invokes a hook, it changes its working directory to either +the root of the working tree in a non-bare repository, or to the +$GIT_DIR in a bare repository. + +Hooks can get their arguments via the environment, command-line +arguments, and stdin. See the documentation for each hook below for +details. + +'git init' may copy hooks to the new repository, depending on its +configuration. See the "TEMPLATE DIRECTORY" section in +linkgit:git-init[1] for details. When the rest of this document refers +to "default hooks" it's talking about the default template shipped +with Git. + +The currently supported hooks are described below. HOOKS ----- @@ -32,15 +43,15 @@ HOOKS applypatch-msg ~~~~~~~~~~~~~~ -This hook is invoked by 'git am' script. It takes a single +This hook is invoked by 'git am'. It takes a single parameter, the name of the file that holds the proposed commit -log message. Exiting with non-zero status causes -'git am' to abort before applying the patch. +log message. Exiting with a non-zero status causes 'git am' to abort +before applying the patch. The hook is allowed to edit the message file in place, and can be used to normalize the message into some project standard -format (if the project has one). It can also be used to refuse -the commit after inspecting the message file. +format. It can also be used to refuse the commit after inspecting +the message file. The default 'applypatch-msg' hook, when enabled, runs the 'commit-msg' hook, if the latter is enabled. @@ -73,10 +84,10 @@ pre-commit ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed -with `--no-verify` option. It takes no parameter, and is +with the `--no-verify` option. It takes no parameters, and is invoked before obtaining the proposed commit log message and -making a commit. Exiting with non-zero status from this script -causes the 'git commit' to abort. +making a commit. Exiting with a non-zero status from this script +causes the 'git commit' command to abort before creating a commit. The default 'pre-commit' hook, when enabled, catches introduction of lines with trailing whitespaces and aborts the commit when @@ -115,15 +126,15 @@ commit-msg ~~~~~~~~~~ This hook is invoked by 'git commit', and can be bypassed -with `--no-verify` option. It takes a single parameter, the +with the `--no-verify` option. It takes a single parameter, the name of the file that holds the proposed commit log message. -Exiting with non-zero status causes the 'git commit' to +Exiting with a non-zero status causes the 'git commit' to abort. -The hook is allowed to edit the message file in place, and can -be used to normalize the message into some project standard -format (if the project has one). It can also be used to refuse -the commit after inspecting the message file. +The hook is allowed to edit the message file in place, and can be used +to normalize the message into some project standard format. It +can also be used to refuse the commit after inspecting the message +file. The default 'commit-msg' hook, when enabled, detects duplicate "Signed-off-by" lines, and aborts the commit if one is found. @@ -131,8 +142,8 @@ The default 'commit-msg' hook, when enabled, detects duplicate post-commit ~~~~~~~~~~~ -This hook is invoked by 'git commit'. It takes no -parameter, and is invoked after a commit is made. +This hook is invoked by 'git commit'. It takes no parameters, and is +invoked after a commit is made. This hook is meant primarily for notification, and cannot affect the outcome of 'git commit'. @@ -267,9 +278,11 @@ does not know the entire set of branches, so it would end up firing one e-mail per ref when used naively, though. The <<post-receive,'post-receive'>> hook is more suited to that. -Another use suggested on the mailing list is to use this hook to -implement access control which is finer grained than the one -based on filesystem group. +In an environment that restricts the users' access only to git +commands over the wire, this hook can be used to implement access +control without relying on filesystem ownership and group +membership. See linkgit:git-shell[1] for how you might use the login +shell to restrict the user's access to only git commands. Both standard output and standard error output are forwarded to 'git send-pack' on the other end, so you can simply `echo` messages 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/lint-gitlink.perl b/Documentation/lint-gitlink.perl new file mode 100755 index 0000000000..476cc30b83 --- /dev/null +++ b/Documentation/lint-gitlink.perl @@ -0,0 +1,71 @@ +#!/usr/bin/perl + +use File::Find; +use Getopt::Long; + +my $basedir = "."; +GetOptions("basedir=s" => \$basedir) + or die("Cannot parse command line arguments\n"); + +my $found_errors = 0; + +sub report { + my ($where, $what, $error) = @_; + print "$where: $error: $what\n"; + $found_errors = 1; +} + +sub grab_section { + my ($page) = @_; + open my $fh, "<", "$basedir/$page.txt"; + my $firstline = <$fh>; + chomp $firstline; + close $fh; + my ($section) = ($firstline =~ /.*\((\d)\)$/); + return $section; +} + +sub lint { + my ($file) = @_; + open my $fh, "<", $file + or return; + while (<$fh>) { + my $where = "$file:$."; + while (s/linkgit:((.*?)\[(\d)\])//) { + my ($target, $page, $section) = ($1, $2, $3); + + # De-AsciiDoc + $page =~ s/{litdd}/--/g; + + if ($page !~ /^git/) { + report($where, $target, "nongit link"); + next; + } + if (! -f "$basedir/$page.txt") { + report($where, $target, "no such source"); + next; + } + $real_section = grab_section($page); + if ($real_section != $section) { + report($where, $target, + "wrong section (should be $real_section)"); + next; + } + } + } + close $fh; +} + +sub lint_it { + lint($File::Find::name) if -f && /\.txt$/; +} + +if (!@ARGV) { + find({ wanted => \&lint_it, no_chdir => 1 }, $basedir); +} else { + for (@ARGV) { + lint($_); + } +} + +exit $found_errors; diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index 30808a01e7..5b4a62e936 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -117,3 +117,11 @@ ifndef::git-pull[] reporting. endif::git-pull[] + +--allow-unrelated-histories:: + By default, `git merge` command refuses to merge histories + that do not share a common ancestor. This option can be + used to override this safety when merging histories of two + projects that started their lives independently. As that is + a very rare occasion, no configuration variable to enable + this by default exists and will not be added. diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 87e1317eed..e44fc8f738 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -42,6 +42,20 @@ people using 80-column terminals. verbatim; this means that invalid sequences in the original commit may be copied to the output. +--expand-tabs=<n>:: +--expand-tabs:: +--no-expand-tabs:: + Perform a tab expansion (replace each tab with enough spaces + to fill to the next display column that is multiple of '<n>') + in the log message before showing it in the output. + `--expand-tabs` is a short-hand for `--expand-tabs=8`, and + `--no-expand-tabs` is a short-hand for `--expand-tabs=0`, + which disables tab expansion. ++ +By default, tabs are expanded in pretty formats that indent the log +message by 4 spaces (i.e. 'medium', which is the default, 'full', +and 'fuller'). + ifndef::git-rev-list[] --notes[=<treeish>]:: Show the notes (see linkgit:git-notes[1]) that annotate the diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 695bd4bf43..27bd701c0d 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -144,8 +144,12 @@ There are some macros to easily define options: `OPT_COUNTUP(short, long, &int_var, description)`:: Introduce a count-up option. - `int_var` is incremented on each use of `--option`, and - reset to zero with `--no-option`. + Each use of `--option` increments `int_var`, starting from zero + (even if initially negative), and `--no-option` resets it to + zero. To determine if `--option` or `--no-option` was encountered at + all, initialize `int_var` to a negative value, and if it is still + negative after parse_options(), then neither `--option` nor + `--no-option` was seen. `OPT_BIT(short, long, &int_var, description, mask)`:: Introduce a boolean option. 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 +---- |