diff options
Diffstat (limited to 'Documentation')
64 files changed, 1759 insertions, 229 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index c6e536f180..0ddd36879a 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -171,6 +171,11 @@ For C programs: - We try to keep to at most 80 characters per line. + - As a Git developer we assume you have a reasonably modern compiler + and we recommend you to enable the DEVELOPER makefile knob to + ensure your patch is clear of all compiler warnings we care about, + by e.g. "echo DEVELOPER=1 >>config.mak". + - We try to support a wide range of C compilers to compile Git with, including old ones. That means that you should not use C99 initializers, even if a lot of compilers grok it. diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e39e2815b..f6e288bc63 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -204,6 +204,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 +428,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.4.11.txt b/Documentation/RelNotes/2.4.11.txt new file mode 100644 index 0000000000..723360295c --- /dev/null +++ b/Documentation/RelNotes/2.4.11.txt @@ -0,0 +1,11 @@ +Git v2.4.11 Release Notes +========================= + +Fixes since v2.4.10 +------------------- + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.5.5.txt b/Documentation/RelNotes/2.5.5.txt new file mode 100644 index 0000000000..37eae9a2d9 --- /dev/null +++ b/Documentation/RelNotes/2.5.5.txt @@ -0,0 +1,11 @@ +Git v2.5.5 Release Notes +======================== + +Fixes since v2.5.4 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.6.6.txt b/Documentation/RelNotes/2.6.6.txt new file mode 100644 index 0000000000..023ad85ec6 --- /dev/null +++ b/Documentation/RelNotes/2.6.6.txt @@ -0,0 +1,11 @@ +Git v2.6.6 Release Notes +======================== + +Fixes since v2.6.5 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.7.2.txt b/Documentation/RelNotes/2.7.2.txt new file mode 100644 index 0000000000..4feef76704 --- /dev/null +++ b/Documentation/RelNotes/2.7.2.txt @@ -0,0 +1,41 @@ +Git v2.7.2 Release Notes +======================== + +Fixes since v2.7.1 +------------------ + + * The low-level merge machinery has been taught to use CRLF line + termination when inserting conflict markers to merged contents that + are themselves CRLF line-terminated. + + * "git worktree" had a broken code that attempted to auto-fix + possible inconsistency that results from end-users moving a + worktree to different places without telling Git (the original + repository needs to maintain backpointers to its worktrees, but + "mv" run by end-users who are not familiar with that fact will + obviously not adjust them), which actually made things worse + when triggered. + + * "git push --force-with-lease" has been taught to report if the push + needed to force (or fast-forwarded). + + * The emulated "yes" command used in our test scripts has been + tweaked not to spend too much time generating unnecessary output + that is not used, to help those who test on Windows where it would + not stop until it fills the pipe buffer due to lack of SIGPIPE. + + * The vimdiff backend for "git mergetool" has been tweaked to arrange + and number buffers in the order that would match the expectation of + majority of people who read left to right, then top down and assign + buffers 1 2 3 4 "mentally" to local base remote merge windows based + on that order. + + * The documentation for "git clean" has been corrected; it mentioned + that .git/modules/* are removed by giving two "-f", which has never + been the case. + + * Paths that have been told the index about with "add -N" are not + quite yet in the index, but a few commands behaved as if they + already are in a harmful way. + +Also includes tiny documentation and test updates. diff --git a/Documentation/RelNotes/2.7.3.txt b/Documentation/RelNotes/2.7.3.txt new file mode 100644 index 0000000000..6adf038915 --- /dev/null +++ b/Documentation/RelNotes/2.7.3.txt @@ -0,0 +1,62 @@ +Git v2.7.3 Release Notes +======================== + +Fixes since v2.7.2 +------------------ + + * Traditionally, the tests that try commands that work on the + contents in the working tree were named with "worktree" in their + filenames, but with the recent addition of "git worktree" + subcommand, whose tests are also named similarly, it has become + harder to tell them apart. The traditional tests have been renamed + to use "work-tree" instead in an attempt to differentiate them. + + * Many codepaths forget to check return value from git_config_set(); + the function is made to die() to make sure we do not proceed when + setting a configuration variable failed. + + * Handling of errors while writing into our internal asynchronous + process has been made more robust, which reduces flakiness in our + tests. + + * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a + rev, i.e. the object named by the the pathname with wildcard + characters in a tree object. + + * "git rev-parse --git-common-dir" used in the worktree feature + misbehaved when run from a subdirectory. + + * The "v(iew)" subcommand of the interactive "git am -i" command was + broken in 2.6.0 timeframe when the command was rewritten in C. + + * "git merge-tree" used to mishandle "both sides added" conflict with + its own "create a fake ancestor file that has the common parts of + what both sides have added and do a 3-way merge" logic; this has + been updated to use the usual "3-way merge with an empty blob as + the fake common ancestor file" approach used in the rest of the + system. + + * The memory ownership rule of fill_textconv() API, which was a bit + tricky, has been documented a bit better. + + * The documentation did not clearly state that the 'simple' mode is + now the default for "git push" when push.default configuration is + not set. + + * Recent versions of GNU grep are pickier when their input contains + arbitrary binary data, which some of our tests uses. Rewrite the + tests to sidestep the problem. + + * A helper function "git submodule" uses since v2.7.0 to list the + modules that match the pathspec argument given to its subcommands + (e.g. "submodule add <repo> <path>") has been fixed. + + * "git config section.var value" to set a value in per-repository + configuration file failed when it was run outside any repository, + but didn't say the reason correctly. + + * The code to read the pack data using the offsets stored in the pack + idx file has been made more carefully check the validity of the + data in the idx. + +Also includes documentation and test updates. diff --git a/Documentation/RelNotes/2.7.4.txt b/Documentation/RelNotes/2.7.4.txt new file mode 100644 index 0000000000..883ae896fe --- /dev/null +++ b/Documentation/RelNotes/2.7.4.txt @@ -0,0 +1,11 @@ +Git v2.7.4 Release Notes +======================== + +Fixes since v2.7.3 +------------------ + + * Bugfix patches were backported from the 'master' front to plug heap + corruption holes, to catch integer overflow in the computation of + pathname lengths, and to get rid of the name_path API. Both of + these would have resulted in writing over an under-allocated buffer + when formulating pathnames while tree traversal. diff --git a/Documentation/RelNotes/2.8.0.txt b/Documentation/RelNotes/2.8.0.txt index 17e904cf4d..25079710fa 100644 --- a/Documentation/RelNotes/2.8.0.txt +++ b/Documentation/RelNotes/2.8.0.txt @@ -1,12 +1,24 @@ Git 2.8 Release Notes ===================== +Backward compatibility note +--------------------------- + +The rsync:// transport has been removed. + + Updates since v2.7 ------------------ UI, Workflows & Features - * "branch --delete" has "branch -d" but "push --delete" does not. + * It turns out "git clone" over rsync transport has been broken when + the source repository has packed references for a long time, and + nobody noticed nor complained about it. + + * "push" learned that its "--delete" option can be shortened to + "-d", just like "branch --delete" and "branch -d" are the same + thing. * "git blame" learned to produce the progress eye-candy when it takes too much time before emitting the first line of the result. @@ -22,7 +34,7 @@ UI, Workflows & Features have a place to store the updated notes tree, iow, a ref). * "git grep" by default does not fall back to its "--no-index" - behaviour outside a directory under Git's control (otherwise the + behavior outside a directory under Git's control (otherwise the user may by mistake end up running a huge recursive search); with a new configuration (set in $HOME/.gitconfig--by definition this cannot be set in the config file per project), this safety can be @@ -43,7 +55,7 @@ UI, Workflows & Features * Many commands that read files that are expected to contain text that is generated (or can be edited) by the end user to control - their behaviour (e.g. "git grep -f <filename>") have been updated + their behavior (e.g. "git grep -f <filename>") have been updated to be more tolerant to lines that are terminated with CRLF (they used to treat such a line to contain payload that ends with CR, which is usually not what the users expect). @@ -83,14 +95,58 @@ UI, Workflows & Features commit that is reachable from <branch> that does not match the given <pattern>. + * The "user.useConfigOnly" configuration variable can be used to + force the user to always set user.email & user.name configuration + variables, serving as a reminder for those who work on multiple + projects and do not want to put these in their $HOME/.gitconfig. + + * "git fetch" and friends that make network connections can now be + told to only use ipv4 (or ipv6). + + * Some authentication methods do not need username or password, but + libcurl needs some hint that it needs to perform authentication. + Supplying an empty username and password string is a valid way to + do so, but you can set the http.[<url>.]emptyAuth configuration + variable to achieve the same, if you find it cleaner. + + * You can now set http.[<url>.]pinnedpubkey to specify the pinned + public key when building with recent enough versions of libcURL. + + * The configuration system has been taught to phrase where it found a + bad configuration variable in a better way in its error messages. + "git config" learnt a new "--show-origin" option to indicate where + the values come from. + + * The "credential-cache" daemon process used to run in whatever + directory it happened to start in, but this made umount(2)ing the + filesystem that houses the repository harder; now the process + chdir()s to the directory that house its own socket on startup. + + * When "git submodule update" did not result in fetching the commit + object in the submodule that is referenced by the superproject, the + command learned to retry another fetch, specifically asking for + that commit that may not be connected to the refs it usually + fetches. + + * "git merge-recursive" learned "--no-renames" option to disable its + rename detection logic. + + * Across the transition at around Git version 2.0, the user used to + get a pretty loud warning when running "git push" without setting + push.default configuration variable. We no longer warn because the + transition was completed a long time ago. + + * README has been renamed to README.md and its contents got tweaked + slightly to make it easier on the eyes. + Performance, Internal Implementation, Development Support etc. * Add a framework to spawn a group of processes in parallel, and use it to run "git fetch --recurse-submodules" in parallel. - * A slight update to the Makefile to mark "phoney" targets - as such correctly. + * A slight update to the Makefile to mark ".PHONY" targets as such + correctly. * In-core storage of the reverse index for .pack files (which lets you go from a pack offset to an object name) has been streamlined. @@ -126,6 +182,77 @@ Performance, Internal Implementation, Development Support etc. tests that take longer before other ones; this reduces the total wallclock time. + * Test scripts have been updated to remove assumptions that are not + portable between Git for POSIX and Git for Windows, or to skip ones + with expectations that are not satisfiable on Git for Windows. + + * Some calls to strcpy(3) triggers a false warning from static + analyzers that are less intelligent than humans, and reducing the + number of these false hits helps us notice real issues. A few + calls to strcpy(3) in a couple of protrams that are already safe + has been rewritten to avoid false warnings. + + * The "name_path" API was an attempt to reduce the need to construct + the full path out of a series of path components while walking a + tree hierarchy, but over time made less efficient because the path + needs to be flattened, e.g. to be compared with another path that + is already flat. The API has been removed and its users have been + rewritten to simplify the overall code complexity. + + * Help those who debug http(s) part of the system. + (merge 0054045 sp/remote-curl-ssl-strerror later to maint). + + * The internal API to interact with "remote.*" configuration + variables has been streamlined. + + * The ref-filter's format-parsing code has been refactored, in + preparation for "branch --format" and friends. + + * Traditionally, the tests that try commands that work on the + contents in the working tree were named with "worktree" in their + filenames, but with the recent addition of "git worktree" + subcommand, whose tests are also named similarly, it has become + harder to tell them apart. The traditional tests have been renamed + to use "work-tree" instead in an attempt to differentiate them. + (merge 5549029 mg/work-tree-tests later to maint). + + * Many codepaths forget to check return value from git_config_set(); + the function is made to die() to make sure we do not proceed when + setting a configuration variable failed. + (merge 3d18064 ps/config-error later to maint). + + * Handling of errors while writing into our internal asynchronous + process has been made more robust, which reduces flakiness in our + tests. + (merge 43f3afc jk/epipe-in-async later to maint). + + * There is a new DEVELOPER knob that enables many compiler warning + options in the Makefile. + + * The way the test scripts configure the Apache web server has been + updated to work also for Apache 2.4 running on RedHat derived + distros. + + * Out of maintenance gcc on OSX 10.6 fails to compile the code in + 'master'; work it around by using clang by default on the platform. + + * The "name_path" API was an attempt to reduce the need to construct + the full path out of a series of path components while walking a + tree hierarchy, but over time made less efficient because the path + needs to be flattened, e.g. to be compared with another path that + is already flat, in many cases. The API has been removed and its + users have been rewritten to simplify the overall code complexity. + This incidentally also closes some heap-corruption holes. + + * Recent versions of GNU grep is pickier than before to decide if a + file is "binary" and refuse to give line-oriented hits when we + expect it to, unless explicitly told with "-a" option. As our + scripted Porcelains use sane_grep wrapper for line-oriented data, + even when the line may contain non-ASCII payload we took from + end-user data, use "grep -a" to implement sane_grep wrapper when + using an implementation of "grep" that takes the "-a" option. + + Also contains various documentation updates and code clean-ups. @@ -141,39 +268,31 @@ notes for details). exporting GIT_WORK_TREE to point at the root of the working tree, interfering when they tried to use a different working tree without setting GIT_WORK_TREE environment themselves. - (merge df1e6ea nd/stop-setenv-work-tree later to maint). * The "exclude_list" structure has the usual "alloc, nr" pair of fields to be used by ALLOC_GROW(), but clear_exclude_list() forgot to reset 'alloc' to 0 when it cleared 'nr' to discard the managed array. - (merge 2653a8c nd/dir-exclude-cleanup later to maint). * Paths that have been told the index about with "add -N" are not quite yet in the index, but a few commands behaved as if they already are in a harmful way. - (merge 4d55200 nd/ita-cleanup later to maint). * "git send-email" was confused by escaped quotes stored in the alias files saved by "mutt", which has been corrected. - (merge 2c510f2 ew/send-email-mutt-alias-fix later to maint). - * A few unportable C construct have been spotted by clang compiler + * A few non-portable C construct have been spotted by clang compiler and have been fixed. - (merge a0df2e5 jk/clang-pedantic later to maint). * The documentation has been updated to hint the connection between the '--signoff' option and DCO. - (merge b2c150d dw/signoff-doc later to maint). * "git reflog" incorrectly assumed that all objects that used to be at the tip of a ref must be commits, which caused it to segfault. - (merge aecad37 dk/reflog-walk-with-non-commit later to maint). * The ignore mechanism saw a few regressions around untracked file listing and sparse checkout selection areas in 2.7.0; the change that is responsible for the regression has been reverted. - (merge 8c72236 nd/exclusion-regression-fix later to maint). * Some codepaths used fopen(3) when opening a fixed path in $GIT_DIR (e.g. COMMIT_EDITMSG) that is meant to be left after the command is @@ -181,7 +300,6 @@ notes for details). be shared with core.sharedRepository and the umask of the previous user is tighter. They have been made to work better by calling unlink(2) and retrying after fopen(3) fails with EPERM. - (merge ea56518 js/fopen-harder later to maint). * Asking gitweb for a nonexistent commit left a warning in the server log. @@ -189,87 +307,133 @@ notes for details). Somebody may want to follow this up with an additional test, perhaps? IIRC, we do test that no Perl warnings are given to the server log, so this should have been caught if our test coverage were good. - (merge a9eb90a ho/gitweb-squelch-undef-warning later to maint). * "git rebase", unlike all other callers of "gc --auto", did not ignore the exit code from "gc --auto". - (merge 8c24f5b jk/ok-to-fail-gc-auto-in-rebase later to maint). * Many codepaths that run "gc --auto" before exiting kept packfiles mapped and left the file descriptors to them open, which was not friendly to systems that cannot remove files that are open. They now close the packs before doing so. - (merge d562102 js/close-packs-before-gc later to maint). * A recent optimization to filter-branch in v2.7.0 introduced a regression when --prune-empty filter is used, which has been corrected. - (merge 1dc413e jk/filter-branch-no-index later to maint). * The description for SANITY prerequisite the test suite uses has been clarified both in the comment and in the implementation. - (merge 719c3da jk/sanity later to maint). * "git tag" started listing a tag "foo" as "tags/foo" when a branch named "foo" exists in the same repository; remove this unnecessary disambiguation, which is a regression introduced in v2.7.0. - (merge 0571979 jk/list-tag-2.7-regression later to maint). * The way "git svn" uses auth parameter was broken by Subversion 1.9.0 and later. - (merge 0b66415 ew/svn-1.9.0-auth later to maint). * The "split" subcommand of "git subtree" (in contrib/) incorrectly skipped merges when it shouldn't, which was corrected. - (merge 933cfeb dw/subtree-split-do-not-drop-merge later to maint). * A few options of "git diff" did not work well when the command was run from a subdirectory. - (merge a97262c nd/diff-with-path-params later to maint). * The command line completion learned a handful of additional options and command specific syntax. - (merge fa4b5e3 jk/completion-rebase later to maint). - (merge f7c2e1a pw/completion-show-branch later to maint). - (merge d7d4ca8 pw/completion-stash later to maint). - (merge e6414b4 tb/complete-word-diff-regex later to maint). * dirname() emulation has been added, as Msys2 lacks it. - (merge e7d5ce8 js/dirname-basename later to maint). * The underlying machinery used by "ls-files -o" and other commands - have been taught not to create empty submodule ref cache for a + has been taught not to create empty submodule ref cache for a directory that is not a submodule. This removes a ton of wasted CPU cycles. - (merge a2d5156 jk/ref-cache-non-repository-optim later to maint). * "git worktree" had a broken code that attempted to auto-fix possible inconsistency that results from end-users moving a worktree to different places without telling Git (the original - repository needs to maintain backpointers to its worktrees, but - "mv" run by end-users who are not familiar with that fact will - obviously not adjust them), which actually made things worse - when triggered. - (merge 618244e nd/do-not-move-worktree-manually later to maint). + repository needs to maintain back-pointers to its worktrees, + but "mv" run by end-users who are not familiar with that fact + will obviously not adjust them), which actually made things + worse when triggered. * The low-level merge machinery has been taught to use CRLF line termination when inserting conflict markers to merged contents that are themselves CRLF line-terminated. - (merge 15980de js/xmerge-marker-eol later to maint). * "git push --force-with-lease" has been taught to report if the push needed to force (or fast-forwarded). - (merge b2e93f8 aw/push-force-with-lease-reporting later to maint). * The emulated "yes" command used in our test scripts has been tweaked not to spend too much time generating unnecessary output that is not used, to help those who test on Windows where it would not stop until it fills the pipe buffer due to lack of SIGPIPE. - (merge 6129c93 js/test-lib-windows-emulated-yes later to maint). + + * The documentation for "git clean" has been corrected; it mentioned + that .git/modules/* are removed by giving two "-f", which has never + been the case. + + * The vimdiff backend for "git mergetool" has been tweaked to arrange + and number buffers in the order that would match the expectation of + majority of people who read left to right, then top down and assign + buffers 1 2 3 4 "mentally" to local base remote merge windows based + on that order. + + * "git show 'HEAD:Foo[BAR]Baz'" did not interpret the argument as a + rev, i.e. the object named by the the pathname with wildcard + characters in a tree object. + (merge aac4fac nd/dwim-wildcards-as-pathspecs later to maint). + + * "git rev-parse --git-common-dir" used in the worktree feature + misbehaved when run from a subdirectory. + (merge 17f1365 nd/git-common-dir-fix later to maint). + + * "git worktree add -B <branchname>" did not work. + + * The "v(iew)" subcommand of the interactive "git am -i" command was + broken in 2.6.0 timeframe when the command was rewritten in C. + (merge 708b8cc jc/am-i-v-fix later to maint). + + * "git merge-tree" used to mishandle "both sides added" conflict with + its own "create a fake ancestor file that has the common parts of + what both sides have added and do a 3-way merge" logic; this has + been updated to use the usual "3-way merge with an empty blob as + the fake common ancestor file" approach used in the rest of the + system. + (merge 907681e jk/no-diff-emit-common later to maint). + + * The memory ownership rule of fill_textconv() API, which was a bit + tricky, has been documented a bit better. + (merge a64e6a4 jk/more-comments-on-textconv later to maint). + + * Update various codepaths to avoid manually-counted malloc(). + (merge 08c95df jk/tighten-alloc later to maint). + + * The documentation did not clearly state that the 'simple' mode is + now the default for "git push" when push.default configuration is + not set. + (merge f6b1fb3 mm/push-simple-doc later to maint). + + * Recent versions of GNU grep are pickier when their input contains + arbitrary binary data, which some of our tests uses. Rewrite the + tests to sidestep the problem. + (merge 3b1442d jk/grep-binary-workaround-in-test later to maint). + + * A helper function "git submodule" uses since v2.7.0 to list the + modules that match the pathspec argument given to its subcommands + (e.g. "submodule add <repo> <path>") has been fixed. + (merge 2b56bb7 sb/submodule-module-list-fix later to maint). + + * "git config section.var value" to set a value in per-repository + configuration file failed when it was run outside any repository, + but didn't say the reason correctly. + (merge 638fa62 js/config-set-in-non-repository later to maint). + + * The code to read the pack data using the offsets stored in the pack + idx file has been made more carefully check the validity of the + data in the idx. + (merge 7465feb jk/pack-idx-corruption-safety later to maint). * Other minor clean-ups and documentation updates - (merge 99487cf ss/user-manual later to maint). - (merge e914ef0 ew/for-each-ref-doc later to maint). - (merge 36fc7d8 sg/t6050-failing-editor-test-fix later to maint). - (merge 60253a6 ss/clone-depth-single-doc later to maint). - (merge bd02e97 lv/add-doc-working-tree later to maint). + (merge f459823 ak/extract-argv0-last-dir-sep later to maint). + (merge 63ca1c0 ak/git-strip-extension-from-dashed-command later to maint). + (merge 4867f11 ps/plug-xdl-merge-leak later to maint). + (merge 4938686 dt/initial-ref-xn-commit-doc later to maint). + (merge 9537f21 ma/update-hooks-sample-typofix later to maint). diff --git a/Documentation/RelNotes/2.8.1.txt b/Documentation/RelNotes/2.8.1.txt new file mode 100644 index 0000000000..ef6d80b008 --- /dev/null +++ b/Documentation/RelNotes/2.8.1.txt @@ -0,0 +1,9 @@ +Git v2.8.1 Release Notes +======================== + +Fixes since v2.8 +---------------- + + * "make rpmbuild" target was broken as its input, git.spec.in, was + not updated to match a file it describes that has been renamed + recently. This has been fixed. diff --git a/Documentation/RelNotes/2.8.2.txt b/Documentation/RelNotes/2.8.2.txt new file mode 100644 index 0000000000..447b1933a8 --- /dev/null +++ b/Documentation/RelNotes/2.8.2.txt @@ -0,0 +1,70 @@ +Git v2.8.2 Release Notes +======================== + +Fixes since v2.8.1 +------------------ + + * 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. + + * Bunch of tests on "git clone" has been renumbered for better + organization. + + * The tests that involve running httpd leaked the system-wide + configuration in /etc/gitconfig to the tested environment. + + * "index-pack --keep=<msg>" was broken since v2.1.0 timeframe. + + * "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. + + * 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. + + * 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. + + * "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). + + * Build updates for MSVC. + + * "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. + + * 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. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.8.3.txt b/Documentation/RelNotes/2.8.3.txt new file mode 100644 index 0000000000..fedd9968e5 --- /dev/null +++ b/Documentation/RelNotes/2.8.3.txt @@ -0,0 +1,101 @@ +Git v2.8.3 Release Notes +======================== + +Fixes since v2.8.2 +------------------ + + * "git send-email" now uses a more readable timestamps when + formulating a message ID. + + * 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. + + * When "git worktree" feature is in use, "git branch -d" allowed + deletion of a branch that is checked out in another worktree + + * 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 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. + + * 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. + + * The socks5:// proxy support added back in 2.6.4 days was not aware + that socks5h:// proxies behave differently. + + * "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 + and http://thread.gmane.org/gmane.comp.version-control.git/275680. + + * "git replace -e" did not honour "core.editor" configuration. + + * Upcoming OpenSSL 1.1.0 will break compilation b updating a few APIs + we use in imap-send, which has been adjusted for the change. + + * "git submodule" reports the paths of submodules the command + recurses into, but this was incorrect when the command was not run + from the root level of the superproject. + + * 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. + + * 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 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. + + * A question by "git send-email" to ask the identity of the sender + has been updated. + + * Recent update to Git LFS broke "git p4" by changing the output from + its "lfs pointer" subcommand. + + * Some multi-byte encoding can have a backslash byte as a later part + of one letter, which would confuse "highlight" filter used in + gitweb. + +Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.8.4.txt b/Documentation/RelNotes/2.8.4.txt new file mode 100644 index 0000000000..6005548fd6 --- /dev/null +++ b/Documentation/RelNotes/2.8.4.txt @@ -0,0 +1,27 @@ +Git v2.8.4 Release Notes +======================== + +Fixes since v2.8.3 +------------------ + + * 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. + + * 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. + + * Portability enhancement for "rebase -i" to help platforms whose + shell does not like "for i in <empty>" (which is not POSIX-kosher). + + * "git fsck" learned to catch NUL byte in a commit object as + potential error and warn. + + * CI test was taught to build documentation pages. + + * Many 'linkgit:<git documentation page>' references were broken, + which are all fixed with this. + +Also contains other minor documentation updates and code clean-ups. diff --git a/Documentation/RelNotes/2.9.0.txt b/Documentation/RelNotes/2.9.0.txt new file mode 100644 index 0000000000..a60e92e0dd --- /dev/null +++ b/Documentation/RelNotes/2.9.0.txt @@ -0,0 +1,488 @@ +Git 2.9 Release Notes +===================== + +Backward compatibility note +--------------------------- + +The end-user facing Porcelain level commands in the "git diff" and +"git log" by default enables 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 Porcelain level commands like "diff" and "log" + now enables 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" session. + + * "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 --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 in + 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. + (merge d9d501b068 jc/rerere-multi later to maint). + + * "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 give name to 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." + (merge 7550424 js/name-rev-use-oldest-ref later to maint). + + * "git clone" learned "--shallow-submodules" option. + + * HTTP transport clients learned to throw extra HTTP headers at the + server, specified via http.extraHeader configuration variable. + + * Patch output from "git diff" and friends has been tweaked to be + more readable by using a blank line as a strong hint that the + contents before and after it belong to a logically separate unit. + + * 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 "commit.verbose" + configuration variable and act as if "--verbose" option was + given from the command line. + + +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. + + * 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" area 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 bef234b st/verify-tag later to maint). + + * "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. + + * Update of "git submodule" to move pieces of logic to C 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. + (merge d88785e jk/test-send-sh-x-trace-elsewhere later to maint). + + * 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 Porcelains 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. + + +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 b updating a few APIs + 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. + + * "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 lead to an inconsistent state for later + operations. + + * "git submodule" reports the paths of submodules the command + recurses into, but this was incorrect 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. + (merge 79f4344 bw/rebase-merge-entire-branch later to maint). + + * 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". + (merge 6694856 jc/commit-tree-ignore-commit-gpgsign later to maint). + + * "http.cookieFile" configuration variable clearly wants a pathname, + but we forgot to treat it as such by e.g. applying tilde expansion. + (merge e5a39ad bn/http-cookiefile-config later to maint). + + * Consolidate description of tilde-expansion that is done to + configuration variables that take pathname to a single place. + (merge dca83ab jc/config-pathname-type later to maint). + + * 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. + (merge f6a5279 sb/submodule-deinit-all later to maint). + + * Many 'linkgit:<git documentation page>' references were broken, + which are all fixed with this. + (merge 1cca17d jc/linkgit-fix later to maint). + + * "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. + (merge b98712b ls/travis-build-doc later to maint). + + * "git fsck" learned to catch NUL byte in a commit object as + potential error and warn. + (merge 6d2d780 jc/fsck-nul-in-commit later to maint). + + * Portability enhancement for "rebase -i" to help platforms whose + shell does not like "for i in <empty>" (which is not POSIX-kosher). + (merge 8e98b35 jk/rebase-interative-eval-fix later to maint). + + * 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. + (merge ebf31e7 js/windows-dotgit later to maint). + + * 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. + (merge 05a5869 kf/gpg-sig-verification-doc later to maint). + + * A couple of bugs around core.autocrlf have been fixed. + (merge caa47ad tb/core-eol-fix later to maint). + + * 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. + (merge 90a78b8 ar/diff-args-osx-precompose later to maint). + + * "git difftool" learned to handle unmerged paths correctly in + dir-diff mode. + (merge 366f9ce da/difftool later to maint). + + * Other minor clean-ups and documentation updates + (merge 832c0e5 lp/typofixes later to maint). + (merge f5ee54a sb/z-is-gnutar-ism later to maint). + (merge 2e3926b va/i18n-misc-updates later to maint). + (merge f212dcc bn/config-doc-tt-varnames later to maint). + (merge f54bea4 nd/remote-plural-ours-plus-theirs later to maint). + (merge 2bb0518 ak/t4151-ls-files-could-be-empty later to maint). + (merge 4df4313 jc/test-seq later to maint). + (merge a75a308 tb/t5601-sed-fix later to maint). + (merge 6c1fbe1 va/i18n-remote-comment-to-align later to maint). + (merge dee2303 va/mailinfo-doc-typofix later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 98fc4cc1d0..e8ad978824 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -61,23 +61,28 @@ Make sure that you have tests for the bug you are fixing. See t/README for guidance. When adding a new feature, make sure that you have new tests to show -the feature triggers the new behaviour when it should, and to show the -feature does not trigger when it shouldn't. Also make sure that the -test suite passes after your commit. Do not forget to update the -documentation to describe the updated behaviour. - -Speaking of the documentation, it is currently a liberal mixture of US -and UK English norms for spelling and grammar, which is somewhat -unfortunate. A huge patch that touches the files all over the place -only to correct the inconsistency is not welcome, though. Potential -clashes with other changes that can result from such a patch are not -worth it. We prefer to gradually reconcile the inconsistencies in -favor of US English, with small and easily digestible patches, as a -side effect of doing some other real work in the vicinity (e.g. -rewriting a paragraph for clarity, while turning en_UK spelling to -en_US). Obvious typographical fixes are much more welcomed ("teh -> -"the"), preferably submitted as independent patches separate from -other documentation changes. +the feature triggers the new behavior when it should, and to show the +feature does not trigger when it shouldn't. After any code change, make +sure that the entire test suite passes. + +If you have an account at GitHub (and you can get one for free to work +on open source projects), you can use their Travis CI integration to +test your changes on Linux, Mac (and hopefully soon Windows). See +GitHub-Travis CI hints section for details. + +Do not forget to update the documentation to describe the updated +behavior and make sure that the resulting documentation set formats +well. It is currently a liberal mixture of US and UK English norms for +spelling and grammar, which is somewhat unfortunate. A huge patch that +touches the files all over the place only to correct the inconsistency +is not welcome, though. Potential clashes with other changes that can +result from such a patch are not worth it. We prefer to gradually +reconcile the inconsistencies in favor of US English, with small and +easily digestible patches, as a side effect of doing some other real +work in the vicinity (e.g. rewriting a paragraph for clarity, while +turning en_UK spelling to en_US). Obvious typographical fixes are much +more welcomed ("teh -> "the"), preferably submitted as independent +patches separate from other documentation changes. Oh, another thing. We are picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped @@ -370,6 +375,47 @@ Know the status of your patch after submission entitled "What's cooking in git.git" and "What's in git.git" giving the status of various proposed changes. +-------------------------------------------------- +GitHub-Travis CI hints + +With an account at GitHub (you can get one for free to work on open +source projects), you can use Travis CI to test your changes on Linux, +Mac (and hopefully soon Windows). You can find a successful example +test build here: https://travis-ci.org/git/git/builds/120473209 + +Follow these steps for the initial setup: + + (1) Fork https://github.com/git/git to your GitHub account. + You can find detailed instructions how to fork here: + https://help.github.com/articles/fork-a-repo/ + + (2) Open the Travis CI website: https://travis-ci.org + + (3) Press the "Sign in with GitHub" button. + + (4) Grant Travis CI permissions to access your GitHub account. + You can find more information about the required permissions here: + https://docs.travis-ci.com/user/github-oauth-scopes + + (5) Open your Travis CI profile page: https://travis-ci.org/profile + + (6) Enable Travis CI builds for your Git fork. + +After the initial setup, Travis CI will run whenever you push new changes +to your fork of Git on GitHub. You can monitor the test state of all your +branches here: https://travis-ci.org/<Your GitHub handle>/git/branches + +If a branch did not pass all test cases then it is marked with a red +cross. In that case you can click on the failing Travis CI job and +scroll all the way down in the log. Find the line "<-- Click here to see +detailed test output!" and click on the triangle next to the log line +number to expand the detailed test output. Here is such a failing +example: https://travis-ci.org/git/git/jobs/122676187 + +Fix the problem and push your fix to your Git fork. This will trigger +a new Travis CI build to ensure all tests pass. + + ------------------------------------------------ MUA specific hints diff --git a/Documentation/config.txt b/Documentation/config.txt index 0a08638bcd..2e1b2e486e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -81,13 +81,16 @@ Includes You can include one config file from another by setting the special `include.path` variable to the name of the file to be included. The +variable takes a pathname as its value, and is subject to tilde +expansion. + +The included file is expanded immediately, as if its contents had been found at the location of the include directive. If the value of the `include.path` variable is a relative path, the path is considered to be relative to the configuration file in which the include directive was -found. The value of `include.path` is subject to tilde expansion: `~/` -is expanded to the value of `$HOME`, and `~user/` to the specified -user's home directory. See below for examples. +found. See below for examples. + Example ~~~~~~~ @@ -114,7 +117,7 @@ Example [include] path = /path/to/foo.inc ; include by absolute path path = foo ; expand "foo" relative to the current file - path = ~/foo ; expand "foo" in your $HOME directory + path = ~/foo ; expand "foo" in your `$HOME` directory Values @@ -169,6 +172,13 @@ 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. +pathname:: + A variable that takes a pathname value can be given a + string that begins with "`~/`" or "`~user/`", and the usual + tilde expansion happens to such a string: `~/` + is expanded to the value of `$HOME`, and `~user/` to the + specified user's home directory. + Variables ~~~~~~~~~ @@ -269,6 +279,12 @@ See linkgit:git-update-index[1]. + The default is true (when core.filemode is not specified in the config file). +core.hideDotFiles:: + (Windows-only) If true, mark newly-created directories and files whose + name starts with a dot as hidden. If 'dotGitOnly', only the `.git/` + directory is hidden, but no other files starting with a dot. The + default mode is 'dotGitOnly'. + core.ignoreCase:: If true, this option enables various workarounds to enable Git to work better on filesystems that are not case sensitive, @@ -337,9 +353,9 @@ core.quotePath:: core.eol:: Sets the line ending type to use in the working directory for - files that have the `text` property set. Alternatives are - 'lf', 'crlf' and 'native', which uses the platform's native - line ending. The default value is `native`. See + files that have the `text` property set when core.autocrlf is false. + Alternatives are 'lf', 'crlf' and 'native', which uses the platform's + native line ending. The default value is `native`. See linkgit:gitattributes[5] for more information on end-of-line conversion. @@ -486,10 +502,10 @@ repository's usual working tree). core.logAllRefUpdates:: Enable the reflog. Updates to a ref <ref> is logged to the file - "$GIT_DIR/logs/<ref>", by appending the new and old + "`$GIT_DIR/logs/<ref>`", by appending the new and old SHA-1, the date/time and the reason of the update, but only when the file exists. If this configuration - variable is set to true, missing "$GIT_DIR/logs/<ref>" + variable is set to true, missing "`$GIT_DIR/logs/<ref>`" file is automatically created for branch heads (i.e. under refs/heads/), remote refs (i.e. under refs/remotes/), note refs (i.e. under refs/notes/), and the symbolic ref HEAD. @@ -593,12 +609,11 @@ be delta compressed, but larger binary media files won't be. Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesFile:: - In addition to '.gitignore' (per-directory) and - '.git/info/exclude', Git looks into this file for patterns - of files which are not meant to be tracked. "`~/`" is expanded - to the value of `$HOME` and "`~user/`" to the specified user's - home directory. Its default value is $XDG_CONFIG_HOME/git/ignore. - If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore + Specifies the pathname to the file that contains patterns to + describe paths that are not meant to be tracked, in addition + to '.gitignore' (per-directory) and '.git/info/exclude'. + Defaults to `$XDG_CONFIG_HOME/git/ignore`. + If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` is used instead. See linkgit:gitignore[5]. core.askPass:: @@ -615,8 +630,25 @@ core.attributesFile:: '.git/info/attributes', Git looks into this file for attributes (see linkgit:gitattributes[5]). Path expansions are made the same way as for `core.excludesFile`. Its default value is - $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not - set or empty, $HOME/.config/git/attributes is used instead. + `$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 @@ -1106,15 +1138,19 @@ commit.status:: message. Defaults to true. commit.template:: - Specify a file to use as the template for new commit messages. - "`~/`" is expanded to the value of `$HOME` and "`~user/`" to the - specified user's home directory. + 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 @@ -1258,6 +1294,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 @@ -1334,7 +1374,7 @@ gc.worktreePruneExpire:: 'git worktree prune --expire 3.months.ago'. This config variable can be used to set a different grace period. The value "now" may be used to disable the grace - period and prune $GIT_DIR/worktrees immediately, or "never" + period and prune `$GIT_DIR/worktrees` immediately, or "never" may be used to suppress pruning. gc.reflogExpire:: @@ -1474,13 +1514,13 @@ grep.fallbackToNoIndex:: is executed outside of a git repository. Defaults to false. gpg.program:: - Use this custom program instead of "gpg" found on $PATH when + Use this custom program instead of "`gpg`" found on `$PATH` when making or verifying a PGP signature. The program must support the same command-line interface as GPG, namely, to verify a detached - signature, "gpg --verify $file - <$signature" is run, and the + signature, "`gpg --verify $file - <$signature`" is run, and the program is expected to signal a good signature by exiting with code 0, and to generate an ASCII-armored detached signature, the - standard input of "gpg -bsau $key" is fed with the contents to be + standard input of "`gpg -bsau $key`" is fed with the contents to be signed, and the program is expected to send the result to its standard output. @@ -1493,7 +1533,7 @@ gui.diffContext:: made by the linkgit:git-gui[1]. The default is "5". gui.displayUntracked:: - Determines if linkgit::git-gui[1] shows untracked files + Determines if linkgit:git-gui[1] shows untracked files in the file list. The default is "true". gui.encoding:: @@ -1648,12 +1688,25 @@ http.proxyAuthMethod:: * `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`) -- +http.emptyAuth:: + Attempt authentication without seeking a username or password. This + can be used to attempt GSS-Negotiate authentication without specifying + 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:: - File containing previously stored cookie lines which should be used + The pathname of a file containing previously stored cookie lines, + which should be used in the Git http session, if they match the server. The file format of the file to read cookies from should be plain HTTP headers or - the Netscape/Mozilla cookie file format (see linkgit:curl[1]). - NOTE that the file specified with http.cookieFile is only used as + the Netscape/Mozilla cookie file format (see `curl(1)`). + NOTE that the file specified with http.cookieFile is used only as input unless http.saveCookies is set. http.saveCookies:: @@ -1727,6 +1780,14 @@ http.sslCAPath:: with when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_CAPATH' environment variable. +http.pinnedpubkey:: + Public key of the https service. It may either be the filename of + a PEM or DER encoded public key file or a string starting with + 'sha256//' followed by the base64 encoded sha256 hash of the + public key. See also libcurl 'CURLOPT_PINNEDPUBLICKEY'. git will + exit with an error if this option is set but not supported by + cURL. + http.sslTry:: Attempt to use AUTH SSL/TLS and encrypted data transfers when connecting via regular FTP protocol. This might be needed @@ -1872,6 +1933,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 @@ -1887,7 +1956,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 @@ -2133,8 +2205,11 @@ pack.packSizeLimit:: The maximum size of a pack. This setting only affects packing to a file when repacking, i.e. the git:// protocol is unaffected. It can be overridden by the `--max-pack-size` - option of linkgit:git-repack[1]. The minimum size allowed is - limited to 1 MiB. The default is unlimited. + option of linkgit:git-repack[1]. Reaching this limit results + in the creation of multiple packfiles; which in turn prevents + bitmaps from being created. + The minimum size allowed is limited to 1 MiB. + The default is unlimited. Common unit suffixes of 'k', 'm', or 'g' are supported. @@ -2534,8 +2609,9 @@ repack.writeBitmaps:: objects to disk (e.g., when `git repack -a` is run). This index can speed up the "counting objects" phase of subsequent packs created for clones and fetches, at the cost of some disk - space and extra time spent on the initial repack. Defaults to - false. + space and extra time spent on the initial repack. This has + no effect if multiple packfiles are created. + Defaults to false. rerere.autoUpdate:: When set to true, `git-rerere` updates the index with the @@ -2715,6 +2791,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 @@ -2830,6 +2917,16 @@ user.name:: Can be overridden by the 'GIT_AUTHOR_NAME' and 'GIT_COMMITTER_NAME' environment variables. See linkgit:git-commit-tree[1]. +user.useConfigOnly:: + Instruct Git to avoid trying to guess defaults for 'user.email' + and 'user.name', and instead retrieve the values only from the + configuration. For example, if you have multiple email addresses + and would like to use a different one for each repository, then + with this configuration option set to `true` in the global config + along with a name, Git will prompt you to set up an email before + making new commits in a newly cloned repository. + Defaults to `false`. + user.signingKey:: If linkgit:git-tag[1] or linkgit:git-commit[1] is not selecting the key you want it to automatically when creating a signed tag or diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index 6eaa45271c..edba56522b 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 diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 306b7e3604..3cb301556e 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -26,12 +26,12 @@ ifndef::git-format-patch[] ifdef::git-diff[] This is the default. endif::git-diff[] -endif::git-format-patch[] -s:: --no-patch:: Suppress diff output. Useful for commands like `git show` that show the patch by default, or to cancel the effect of `--patch`. +endif::git-format-patch[] -U<n>:: --unified=<n>:: @@ -271,7 +271,7 @@ For example, `--word-diff-regex=.` will treat each character as a word and, correspondingly, show differences character by character. + The regex can also be set via a diff driver or configuration option, see -linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly +linkgit:gitattributes[5] or linkgit:git-config[1]. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings. @@ -286,8 +286,8 @@ endif::git-format-patch[] ifndef::git-format-patch[] --check:: - Warn if changes introduce whitespace errors. What are - considered whitespace errors is controlled by `core.whitespace` + Warn if changes introduce conflict markers or whitespace errors. + What are considered whitespace errors is controlled by `core.whitespace` configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the diff --git a/Documentation/everyday.txto b/Documentation/everyday.txto index c5047d8f9b..ae555bd47e 100644 --- a/Documentation/everyday.txto +++ b/Documentation/everyday.txto @@ -1,7 +1,7 @@ Everyday Git With 20 Commands Or So =================================== -This document has been moved to linkgit:giteveryday[1]. +This document has been moved to linkgit:giteveryday[7]. Please let the owners of the referring site know so that they can update the link you clicked to get here. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 952dfdfef0..036edfb099 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -158,3 +158,11 @@ endif::git-pull[] by default when it is attached to a terminal, unless -q is specified. This flag forces progress status even if the standard error stream is not directed to a terminal. + +-4:: +--ipv4:: + Use IPv4 addresses only, ignoring IPv6 addresses. + +-6:: +--ipv6:: + Use IPv6 addresses only, ignoring IPv4 addresses. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index d9ed6a1a4e..8ddb207409 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -13,7 +13,7 @@ SYNOPSIS [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached] - [--ignore-space-change | --ignore-whitespace ] + [--ignore-space-change | --ignore-whitespace] [--whitespace=(nowarn|warn|fix|error|error-all)] [--exclude=<path>] [--include=<path>] [--directory=<root>] [--verbose] [--unsafe-paths] [<patch>...] @@ -21,6 +21,8 @@ SYNOPSIS DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. +When running from a subdirectory in a repository, patched paths +outside the directory are ignored. With the `--index` option the patch is also applied to the index, and with the `--cached` option the patch is only applied to the index. Without these options, the command applies the patch only to files, diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index e94367a5ed..611754f10b 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -112,7 +112,7 @@ EXIT STATUS SEE ALSO -------- linkgit:gitignore[5] -linkgit:gitconfig[5] +linkgit:git-config[1] linkgit:git-ls-files[1] GIT diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index 641681f61a..51a7e26a8e 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -37,9 +37,7 @@ OPTIONS to false, 'git clean' will refuse to delete files or directories unless given -f, -n or -i. Git will refuse to delete directories with .git sub directory or file unless a second -f - is given. This affects also git submodules where the storage area - of the removed submodule under .git/modules/ is not removed until - -f is given twice. + is given. -i:: --interactive:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index b7c467a001..1b15cd7b16 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,9 @@ 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. This implies `--shallow-submodules`. If + you want to have a shallow superproject clone, but full submodules, + also pass `--no-shallow-submodules`. --[no-]single-branch:: Clone only the history leading to the tip of a single branch, @@ -212,6 +214,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 +224,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 48c33d7ed7..cb69faab68 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 9ec6b3cc17..d474226eb7 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-config.txt b/Documentation/git-config.txt index 2608ca74ac..6843114fc0 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,18 +9,18 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [type] [-z|--null] name [value [value_regex]] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] name [value [value_regex]] 'git config' [<file-option>] [type] --add name value 'git config' [<file-option>] [type] --replace-all name value [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get name [value_regex] -'git config' [<file-option>] [type] [-z|--null] --get-all name [value_regex] -'git config' [<file-option>] [type] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] --get name [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] --get-all name [value_regex] +'git config' [<file-option>] [type] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex] 'git config' [<file-option>] [type] [-z|--null] --get-urlmatch name URL 'git config' [<file-option>] --unset name [value_regex] 'git config' [<file-option>] --unset-all name [value_regex] 'git config' [<file-option>] --rename-section old_name new_name 'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [-z|--null] [--name-only] -l | --list +'git config' [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list 'git config' [<file-option>] --get-color name [default] 'git config' [<file-option>] --get-colorbool name [stdout-is-tty] 'git config' [<file-option>] -e | --edit @@ -58,13 +58,13 @@ that location (you can say '--local' but that is the default). This command will fail with non-zero status upon error. Some exit codes are: -. The config file is invalid (ret=3), -. can not write to the config file (ret=4), -. no section or name was provided (ret=2), -. the section or key is invalid (ret=1), -. you try to unset an option which does not exist (ret=5), -. you try to unset/set an option for which multiple lines match (ret=5), or -. you try to use an invalid regexp (ret=6). +- The section or key is invalid (ret=1), +- no section or name was provided (ret=2), +- the config file is invalid (ret=3), +- the config file cannot be written (ret=4), +- you try to unset an option which does not exist (ret=5), +- you try to unset/set an option for which multiple lines match (ret=5), or +- you try to use an invalid regexp (ret=6). On success, the command returns the exit code 0. @@ -86,8 +86,7 @@ OPTIONS found and the last value if multiple key values were found. --get-all:: - Like get, but does not fail if the number of values for the key - is not exactly one. + Like get, but returns all values for a multi-valued key. --get-regexp:: Like --get-all, but interprets the name as a regular expression and @@ -102,7 +101,7 @@ OPTIONS given URL is returned (if no such key exists, the value for section.key is used as a fallback). When given just the section as name, do so for all the keys in the section and - list them. + list them. Returns error code 1 if no value is found. --global:: For writing options: write to global `~/.gitconfig` file @@ -194,6 +193,12 @@ See also <<FILES>>. Output only the names of config variables for `--list` or `--get-regexp`. +--show-origin:: + Augment the output of all queried config options with the + origin type (file, standard input, blob, command line) and + the actual origin (config file path, ref, or blob id if + applicable). + --get-colorbool name [stdout-is-tty]:: Find the color setting for `name` (e.g. `color.diff`) and output @@ -219,7 +224,9 @@ See also <<FILES>>. --[no-]includes:: Respect `include.*` directives in config files when looking up - values. Defaults to on. + values. Defaults to `off` when a specific file is given (e.g., + using `--file`, `--global`, etc) and `on` when searching all + config files. [[FILES]] FILES diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index 89b730632d..96208f822e 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -36,7 +36,7 @@ OPTIONS cache daemon if one is not started). Defaults to `~/.git-credential-cache/socket`. If your home directory is on a network-mounted filesystem, you may need to change this to a - local filesystem. + local filesystem. You must specify an absolute path. CONTROLLING THE DAEMON ---------------------- diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 8680f45f8d..239623cc24 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -104,6 +104,10 @@ be in a separate packet, and the list must end with a flush packet. The remote heads to update from. This is relative to $GIT_DIR (e.g. "HEAD", "refs/heads/master"). When unspecified, update from all heads the remote side has. ++ +If the remote has enabled the options `uploadpack.allowTipSHA1InWant` or +`uploadpack.allowReachableSHA1InWant`, they may alternatively be 40-hex +sha1s present on the remote. SEE ALSO -------- diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 73fd9e8230..003731f6a9 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -205,7 +205,7 @@ to other tags will be rewritten to point to the underlying commit. Remap to ancestor ~~~~~~~~~~~~~~~~~ -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit the set of revisions which get rewritten. However, positive refs on the command line are distinguished: we don't let them be excluded by such limiters. For this purpose, they are instead rewritten to point at the nearest ancestor that diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 2e3e96f663..d9d406dcfb 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -76,7 +76,7 @@ OPTIONS specified commit (HEAD if not specified). --contains [<object>]:: - Only list tags which contain the specified commit (HEAD if not + Only list refs which contain the specified commit (HEAD if not specified). FIELD NAMES @@ -133,14 +133,18 @@ color:: align:: Left-, middle-, or right-align the content between - %(align:...) and %(end). The "align:" is followed by `<width>` - and `<position>` in any order separated by a comma, where the - `<position>` is either left, right or middle, default being - left and `<width>` is the total length of the content with - alignment. If the contents length is more than the width then - no alignment is performed. If used with '--quote' everything - in between %(align:...) and %(end) is quoted, but if nested - then only the topmost level performs quoting. + %(align:...) and %(end). The "align:" is followed by + `width=<width>` and `position=<position>` in any order + separated by a comma, where the `<position>` is either left, + right or middle, default being left and `<width>` is the total + length of the content with alignment. For brevity, the + "width=" and/or "position=" prefixes may be omitted, and bare + <width> and <position> used instead. For instance, + `%(align:<width>,<position>)`. If the contents length is more + than the width then no alignment is performed. If used with + '--quote' everything in between %(align:...) and %(end) is + quoted, but if nested then only the topmost level performs + quoting. In addition to the above, for commit and tag objects, the header field names (`tree`, `parent`, `object`, `type`, and `tag`) can @@ -175,7 +179,7 @@ returns an empty string instead. As a special case for the date-type fields, you may specify a format for the date by adding `:` followed by date format name (see the -values the `--date` option to linkgit::git-rev-list[1] takes). +values the `--date` option to linkgit:git-rev-list[1] takes). EXAMPLES diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 6821441d7d..bdeecd59e0 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 8174d27efd..6364e5dc45 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 03f958029a..dec379b3e2 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 diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 0e08f567a1..75c3f4157d 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -155,7 +155,7 @@ a space) at the start of each line: <eolinfo> is either "-text", "none", "lf", "crlf", "mixed" or "". + "" means the file is not a regular file, it is not in the index or -not accessable in the working tree. +not accessible in the working tree. + <eolattr> is the attribute that is used when checking out or committing, it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt index 0947084140..3bbc731f67 100644 --- a/Documentation/git-mailinfo.txt +++ b/Documentation/git-mailinfo.txt @@ -85,7 +85,7 @@ with comments and suggestions on the message you are responding to, and to conclude it with a patch submission, separating the discussion and the beginning of the proposed commit log message with a scissors line. + -This can enabled by default with the configuration option mailinfo.scissors. +This can be enabled by default with the configuration option mailinfo.scissors. --no-scissors:: Ignore scissors lines. Useful for overriding mailinfo.scissors settings. 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-notes.txt b/Documentation/git-notes.txt index 8de349968a..9c4fd6812c 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -402,4 +402,4 @@ on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. GIT --- -Part of the linkgit:git[7] suite +Part of the linkgit:git[1] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 738cfde10c..88ba42b455 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -515,20 +515,18 @@ git-p4.pathEncoding:: Git expects paths encoded as UTF-8. Use this config to tell git-p4 what encoding Perforce had used for the paths. This encoding is used to transcode the paths to UTF-8. As an example, Perforce on Windows - often uses “cp1252” to encode path names. + often uses "cp1252" to encode path names. git-p4.largeFileSystem:: Specify the system that is used for large (binary) files. Please note that large file systems do not support the 'git p4 submit' command. - Only Git LFS [1] is implemented right now. Download - and install the Git LFS command line extension to use this option - and configure it like this: + Only Git LFS is implemented right now (see https://git-lfs.github.com/ + for more information). Download and install the Git LFS command line + extension to use this option and configure it like this: + ------------- git config git-p4.largeFileSystem GitLFS ------------- -+ - [1] https://git-lfs.github.com/ git-p4.largeFileExtensions:: All files matching a file extension in the list will be processed @@ -553,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-pack-objects.txt b/Documentation/git-pack-objects.txt index bbea5294ca..19cdcd0341 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -110,7 +110,8 @@ base-name:: --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - If specified, multiple packfiles may be created. + If specified, multiple packfiles may be created, which also + prevents the creation of a bitmap index. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. 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-push.txt b/Documentation/git-push.txt index 32482cec42..cf6ee4a4df 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -37,6 +37,13 @@ the default `<refspec>` by consulting `remote.*.push` configuration, and if it is not found, honors `push.default` configuration to decide what to push (See linkgit:git-config[1] for the meaning of `push.default`). +When neither the command-line nor the configuration specify what to +push, the default behavior is used, which corresponds to the `simple` +value for `push.default`: the current branch is pushed to the +corresponding upstream branch, but as a safety measure, the push is +aborted if the upstream branch does not have the same name as the +local one. + OPTIONS[[OPTIONS]] ------------------ @@ -277,6 +284,13 @@ origin +master` to force a push to the `master` branch). See the default is --verify, giving the hook a chance to prevent the push. With --no-verify, the hook is bypassed completely. +-4:: +--ipv4:: + Use IPv4 addresses only, ignoring IPv6 addresses. + +-6:: +--ipv6:: + Use IPv6 addresses only, ignoring IPv4 addresses. include::urls-remotes.txt[] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 6cca8bb51d..0387b40e0a 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -3,7 +3,7 @@ git-rebase(1) NAME ---- -git-rebase - Forward-port local commits to the updated upstream head +git-rebase - Reapply commits on top of another base tip SYNOPSIS -------- @@ -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 af230d0647..b9c02ce481 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -106,7 +106,8 @@ other objects in that pack they already have locally. --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with "k", "m", or "g". The minimum size allowed is limited to 1 MiB. - If specified, multiple packfiles may be created. + If specified, multiple packfiles may be created, which also + prevents the creation of a bitmap index. The default is unlimited, unless the config variable `pack.packSizeLimit` is set. @@ -115,7 +116,8 @@ other objects in that pack they already have locally. Write a reachability bitmap index as part of the repack. This only makes sense when used with `-a` or `-A`, as the bitmaps must be able to refer to all reachable objects. This option - overrides the setting of `pack.writeBitmaps`. + overrides the setting of `repack.writeBitmaps`. This option + has no effect if multiple packfiles are created. --pack-kept-objects:: Include objects in `.keep` files when repacking. Note that we @@ -123,7 +125,7 @@ other objects in that pack they already have locally. This means that we may duplicate objects, but this makes the option safe to use when there are concurrent pushes or fetches. This option is generally only useful if you are writing bitmaps - with `-b` or `pack.writeBitmaps`, as it ensures that the + with `-b` or `repack.writeBitmaps`, as it ensures that the bitmapped packfile has the necessary objects. Configuration diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 771a7b5b09..edbba3a2ef 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 acocunt, 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 1572f058f5..9226c4380c 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -13,10 +13,10 @@ SYNOPSIS [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] 'git submodule' [--quiet] init [--] [<path>...] -'git submodule' [--quiet] deinit [-f|--force] [--] <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>...] + [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...] 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] 'git submodule' [--quiet] foreach [--recursive] <command> @@ -140,12 +140,15 @@ deinit:: tree. Further calls to `git submodule update`, `git submodule foreach` and `git submodule sync` will skip any unregistered submodules until they are initialized again, so use this command if you don't want to - have a local checkout of the submodule in your work tree anymore. If + have a local checkout of the submodule in your working tree anymore. If you really want to remove a submodule from the repository and commit that use linkgit:git-rm[1] instead. + -If `--force` is specified, the submodule's work tree will be removed even if -it contains local modifications. +When the command is run without pathspec, it errors out, +instead of deinit-ing everything, to prevent mistakes. ++ +If `--force` is specified, the submodule's working tree will +be removed even if it contains local modifications. update:: + @@ -247,6 +250,10 @@ OPTIONS --quiet:: Only print error messages. +--all:: + This option is only valid for the deinit command. Unregister all + submodules in the working tree. + -b:: --branch:: Branch of repository to add as submodule. @@ -257,8 +264,8 @@ OPTIONS --force:: This option is only valid for add, deinit and update commands. When running add, allow adding an otherwise ignored submodule path. - When running deinit the submodule work trees will be removed even if - they contain local changes. + When running deinit the submodule working trees will be removed even + if they contain local changes. When running update (only effective with the checkout procedure), throw away local changes in submodules when switching to a different commit; and always run a checkout operation in the @@ -377,6 +384,11 @@ 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] +-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 0c0f60b20e..fb23a98a17 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -1034,6 +1034,8 @@ listed below are allowed: url = http://server.org/svn fetch = trunk/project-a:refs/remotes/project-a/trunk branches = branches/*/project-a:refs/remotes/project-a/branches/* + branches = branches/release_*:refs/remotes/project-a/branches/release_* + branches = branches/re*se:refs/remotes/project-a/branches/* tags = tags/*/project-a:refs/remotes/project-a/tags/* ------------------------------------------------------------------------ @@ -1044,6 +1046,16 @@ independent path component (surrounded by '/' or EOL). This type of configuration is not automatically created by 'init' and should be manually entered with a text-editor or using 'git config'. +Also note that only one asterisk is allowed per word. For example: + + branches = branches/re*se:refs/remotes/project-a/branches/* + +will match branches 'release', 'rese', 're123se', however + + branches = branches/re*s*e:refs/remotes/project-a/branches/* + +will produce an error. + It is also possible to fetch a subset of branches or tags by using a comma-separated list of names within braces. For example: diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 62c76c1c89..c62234538b 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -9,7 +9,7 @@ git-worktree - Manage multiple working trees SYNOPSIS -------- [verse] -'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>] +'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>] 'git worktree prune' [-n] [-v] [--expire <expire>] 'git worktree list' [--porcelain] @@ -87,6 +87,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 a48c1e8024..dd6dbf7dd9 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,15 +43,26 @@ 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.7.1/git.html[documentation for release 2.7.1] +* link:v2.8.3/git.html[documentation for release 2.8.3] * release notes for + link:RelNotes/2.8.3.txt[2.8.3], + link:RelNotes/2.8.2.txt[2.8.2], + link:RelNotes/2.8.1.txt[2.8.1], + link:RelNotes/2.8.0.txt[2.8]. + +* link:v2.7.3/git.html[documentation for release 2.7.3] + +* release notes for + link:RelNotes/2.7.3.txt[2.7.3], + link:RelNotes/2.7.2.txt[2.7.2], link:RelNotes/2.7.1.txt[2.7.1], link:RelNotes/2.7.0.txt[2.7]. -* link:v2.6.5/git.html[documentation for release 2.6.5] +* link:v2.6.6/git.html[documentation for release 2.6.6] * release notes for + link:RelNotes/2.6.6.txt[2.6.6], link:RelNotes/2.6.5.txt[2.6.5], link:RelNotes/2.6.4.txt[2.6.4], link:RelNotes/2.6.3.txt[2.6.3], @@ -59,18 +70,20 @@ Documentation for older releases are available here: link:RelNotes/2.6.1.txt[2.6.1], link:RelNotes/2.6.0.txt[2.6]. -* link:v2.5.4/git.html[documentation for release 2.5.4] +* link:v2.5.5/git.html[documentation for release 2.5.5] * release notes for + link:RelNotes/2.5.5.txt[2.5.5], link:RelNotes/2.5.4.txt[2.5.4], link:RelNotes/2.5.3.txt[2.5.3], link:RelNotes/2.5.2.txt[2.5.2], link:RelNotes/2.5.1.txt[2.5.1], link:RelNotes/2.5.0.txt[2.5]. -* link:v2.4.10/git.html[documentation for release 2.4.10] +* link:v2.4.11/git.html[documentation for release 2.4.11] * release notes for + link:RelNotes/2.4.11.txt[2.4.11], link:RelNotes/2.4.10.txt[2.4.10], link:RelNotes/2.4.9.txt[2.4.9], link:RelNotes/2.4.8.txt[2.4.8], @@ -1122,7 +1135,7 @@ of clones and fetches. connection (or proxy, if configured) - `ssh`: git over ssh (including `host:path` syntax, - `git+ssh://`, etc). + `ssh://`, etc). - `http`: git over http, both "smart http" and "dumb http". Note that this does _not_ include `https`; if you want both, 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 7ba0ac965d..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 @@ -397,7 +410,7 @@ preceding SP is also omitted. Currently, no commands pass any 'extra-info'. The hook always runs after the automatic note copying (see -"notes.rewrite.<command>" in linkgit:git-config.txt[1]) has happened, and +"notes.rewrite.<command>" in linkgit:git-config[1]) has happened, and thus has access to these notes. The following command-specific comments apply: diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index cafc284359..8ad29e61a9 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -145,7 +145,7 @@ current branch integrates with) obviously do not work, as there is no A fast-forward is a special type of <<def_merge,merge>> where you have a <<def_revision,revision>> and you are "merging" another <<def_branch,branch>>'s changes that happen to be a descendant of what - you have. In such these cases, you do not make a new <<def_merge,merge>> + you have. In such a case, you do not make a new <<def_merge,merge>> <<def_commit,commit>> but instead just update to his revision. This will happen frequently on a <<def_remote_tracking_branch,remote-tracking branch>> of a remote 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 f08e9b80c5..5b4a62e936 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -89,8 +89,11 @@ option can be used to override --squash. --verify-signatures:: --no-verify-signatures:: - Verify that the commits being merged have good and trusted GPG signatures - and abort the merge in case they do not. + Verify that the tip commit of the side branch being merged is + signed with a valid key, i.e. a key that has a valid uid: in the + default trust model, this means the signing key has been signed by + a trusted key. If the tip commit of the side branch is not signed + with a valid key, the merge is aborted. --summary:: --no-summary:: @@ -114,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/merge-strategies.txt b/Documentation/merge-strategies.txt index 7bbd19b300..2eb92b9327 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -81,9 +81,17 @@ no-renormalize;; Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. +no-renames;; + Turn off rename detection. + See also linkgit:git-diff[1] `--no-renames`. + +find-renames[=<n>];; + Turn on rename detection, optionally setting the similarity + threshold. This is the default. + See also linkgit:git-diff[1] `--find-renames`. + rename-threshold=<n>;; - Controls the similarity threshold used for rename detection. - See also linkgit:git-diff[1] `-M`. + Deprecated synonym for `find-renames=<n>`. subtree[=<path>];; This option is a more advanced form of 'subtree' strategy, where diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 671cebd95c..29b19b992f 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -143,8 +143,8 @@ ifndef::git-rev-list[] - '%N': commit notes endif::git-rev-list[] - '%GG': raw verification message from GPG for a signed commit -- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good, - untrusted signature and "N" for no signature +- '%G?': show "G" for a good (valid) signature, "B" for a bad signature, + "U" for a good signature with unknown validity and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit - '%gD': reflog selector, e.g., `refs/stash@{1}` diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 54b88b6dca..6c67182728 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-argv-array.txt b/Documentation/technical/api-argv-array.txt index 8076172a08..cfc063018c 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -56,3 +56,10 @@ Functions `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. + +`argv_array_detach`:: + Disconnect the `argv` member from the `argv_array` struct and + return it. The caller is responsible for freeing the memory used + by the array, and by the strings it references. After detaching, + the `argv_array` is in a reinitialized state and can be pushed + into again. diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt index 0d8b99b368..20741f345e 100644 --- a/Documentation/technical/api-config.txt +++ b/Documentation/technical/api-config.txt @@ -63,13 +63,6 @@ parse for configuration, rather than looking in the usual files. Regular Specify whether include directives should be followed in parsed files. Regular `git_config` defaults to `1`. -There is a special version of `git_config` called `git_config_early`. -This version takes an additional parameter to specify the repository -config, instead of having it looked up via `git_path`. This is useful -early in a Git program before the repository has been found. Unless -you're working with early setup code, you probably don't want to use -this. - Reading Specific Files ---------------------- diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt index e44426dd04..75368f26ca 100644 --- a/Documentation/technical/api-credentials.txt +++ b/Documentation/technical/api-credentials.txt @@ -243,7 +243,7 @@ appended to its command line, which is one of: The details of the credential will be provided on the helper's stdin stream. The exact format is the same as the input/output format of the `git credential` plumbing command (see the section `INPUT/OUTPUT -FORMAT` in linkgit:git-credential[7] for a detailed specification). +FORMAT` in linkgit:git-credential[1] for a detailed specification). For a `get` operation, the helper should produce a list of attributes on stdout in the same format. A helper is free to produce a subset, or @@ -268,4 +268,4 @@ See also linkgit:gitcredentials[7] -linkgit:git-config[5] (See configuration variables `credential.*`) +linkgit:git-config[1] (See configuration variables `credential.*`) diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 5f0757dcc9..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. @@ -231,6 +235,13 @@ There are some macros to easily define options: pass the command-line option, which can be specified multiple times, to another command. +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: + Define an "operation mode" option, only one of which in the same + group of "operating mode" options that share the same `int_var` + can be given by the user. `enum_val` is set to `int_var` when the + option is used, but an error is reported if other "operating mode" + option has already set its value to the same `int_var`. + The last element of the array must be `OPT_END()`. diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt index 097a651d96..fadb5979c4 100644 --- a/Documentation/technical/api-trace.txt +++ b/Documentation/technical/api-trace.txt @@ -28,7 +28,7 @@ static struct trace_key trace_foo = TRACE_KEY_INIT(FOO); static void trace_print_foo(const char *message) { - trace_print_key(&trace_foo, message); + trace_printf_key(&trace_foo, "%s", message); } ------------ + @@ -95,3 +95,46 @@ for (;;) { } trace_performance(t, "frotz"); ------------ + +Bugs & Caveats +-------------- + +GIT_TRACE_* environment variables can be used to tell Git to show +trace output to its standard error stream. Git can often spawn a pager +internally to run its subcommand and send its standard output and +standard error to it. + +Because GIT_TRACE_PERFORMANCE trace is generated only at the very end +of the program with atexit(), which happens after the pager exits, it +would not work well if you send its log to the standard error output +and let Git spawn the pager at the same time. + +As a work around, you can for example use '--no-pager', or set +GIT_TRACE_PERFORMANCE to another file descriptor which is redirected +to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its +absolute path. + +For example instead of the following command which by default may not +print any performance information: + +------------ +GIT_TRACE_PERFORMANCE=2 git log -1 +------------ + +you may want to use: + +------------ +GIT_TRACE_PERFORMANCE=2 git --no-pager log -1 +------------ + +or: + +------------ +GIT_TRACE_PERFORMANCE=3 3>&2 git log -1 +------------ + +or: + +------------ +GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1 +------------ diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index c6977bbc5a..8b36343802 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -526,7 +526,7 @@ Push Certificate A push certificate begins with a set of header lines. After the header and an empty line, the protocol commands follow, one per -line. Note that the the trailing LF in push-cert PKT-LINEs is _not_ +line. Note that the trailing LF in push-cert PKT-LINEs is _not_ optional; it must be present. Currently, the following header fields are defined: diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index ec6bacfcdf..5e07454572 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -2134,7 +2134,7 @@ browsing the repository using gitweb. The default server when using instaweb is lighttpd. See the file gitweb/INSTALL in the Git source tree and -linkgit:gitweb[1] for instructions on details setting up a permament +linkgit:gitweb[1] for instructions on details setting up a permanent installation with a CGI or Perl capable server. [[how-to-get-a-git-repository-with-minimal-history]] |