diff options
Diffstat (limited to 'Documentation')
28 files changed, 673 insertions, 161 deletions
diff --git a/Documentation/RelNotes/2.10.0.txt b/Documentation/RelNotes/2.10.0.txt index a9fb0736d6..f4da28ab66 100644 --- a/Documentation/RelNotes/2.10.0.txt +++ b/Documentation/RelNotes/2.10.0.txt @@ -71,15 +71,14 @@ UI, Workflows & Features command line option "--no-show-signature" to countermand it. (merge fce04c3 mj/log-show-signature-conf later to maint). - * A couple of "git svn" updates. - * More markings of messages for i18n, with updates to various tests to pass GETTEXT_POISON tests. * "git archive" learned to handle files that are larger than 8GB and commits far in the future than expressible by the traditional US-TAR format. - (merge 5caeeb8 jk/big-and-future-archive-tar later to maint). + (merge 560b0e8 jk/big-and-future-archive-tar later to maint). + * A new configuration variable core.sshCommand has been added to specify what value for GIT_SSH_COMMAND to use per repository. @@ -97,7 +96,6 @@ UI, Workflows & Features * "git status" learned to suggest "merge --abort" during a conflicted merge, just like it already suggests "rebase --abort" during a conflicted rebase. - (merge b0a61ab mm/status-suggest-merge-abort later to maint). * "git jump" script (in contrib/) has been updated a bit. (merge a91e692 jk/git-jump later to maint). @@ -105,6 +103,31 @@ UI, Workflows & Features * "git push" and "git clone" learned to give better progress meters to the end user who is waiting on the terminal. + * An entry "git log --decorate" for the tip of the current branch is + shown as "HEAD -> name" (where "name" is the name of the branch); + the arrow is now painted in the same color as "HEAD", not in the + color for commits. + + * "git format-patch" learned format.from configuration variable to + specify the default settings for its "--from" option. + + * "git am -3" calls "git merge-recursive" when it needs to fall back + to a three-way merge; this call has been turned into an internal + subroutine call instead of spawning a separate subprocess. + + * The command line completion scripts (in contrib/) now knows about + "git branch --delete/--move [--remote]". + (merge 2703c22 vs/completion-branch-fully-spelled-d-m-r later to maint). + + * "git rev-parse --git-path hooks/<hook>" learned to take + core.hooksPath configuration variable (introduced during 2.9 cycle) + into account. + (merge 9445b49 ab/hooks later to maint). + + * "git log --show-signature" and other commands that display the + verification status of PGP signature now shows the longer key-id, + as 32-bit key-id is so last century. + Performance, Internal Implementation, Development Support etc. @@ -120,19 +143,19 @@ Performance, Internal Implementation, Development Support etc. * "git upload-pack" command has been updated to use the parse-options API. - * The "git apply" standalone program is being libified; this is the - first step to move many state variables into a structure that can - be explicitly (re)initialized to make the machinery callable more - than once. + * The "git apply" standalone program is being libified; the first + step to move many state variables into a structure that can be + explicitly (re)initialized to make the machinery callable more + than once has been merged. * HTTP transport gained an option to produce more detailed debugging trace. (merge 73e57aa ep/http-curl-trace later to maint). - * Instead of taking advantage of a struct string_list that is - allocated with all NULs happens to be STRING_LIST_INIT_NODUP kind, - initialize them explicitly as such, to document their behaviour - better. + * Instead of taking advantage of the fact that a struct string_list + that is allocated with all NULs happens to be the INIT_NODUP kind, + the users of string_list structures are taught to initialize them + explicitly as such, to document their behaviour better. (merge 2721ce2 jk/string-list-static-init later to maint). * HTTPd tests learned to show the server error log to help diagnosing @@ -157,7 +180,7 @@ Performance, Internal Implementation, Development Support etc. the standard output and the standard error of an external process, which is cumbersome to hand-roll correctly without deadlocking. - The codepath to sign data in a prepared buffer with GPG has been + * The codepath to sign data in a prepared buffer with GPG has been updated to use this API to read from the status-fd to check for errors (instead of relying on GPG's exit status). (merge efee955 jk/gpg-interface-cleanup later to maint). @@ -180,7 +203,6 @@ Performance, Internal Implementation, Development Support etc. * The .c/.h sources are marked as such in our .gitattributes file so that "git diff -W" and friends would work better. - (merge e82675a rs/help-c-source-with-gitattributes later to maint). * Code clean-up to avoid using a variable string that compilers may feel untrustable as printf-style format given to write_file() @@ -193,7 +215,6 @@ Performance, Internal Implementation, Development Support etc. library did not check all the functions from pthread libraries; recent FreeBSD has some functions in libc but not others, and we mistakenly thought linking with libc is enough when it is not. - (merge a9b02de ew/autoconf-pthread later to maint). * When "git fsck" reports a broken link (e.g. a tree object contains a blob that does not exist), both containing object and the object @@ -202,7 +223,6 @@ Performance, Internal Implementation, Development Support etc. the containing object from existing refs (e.g. "HEAD~24^2:file.txt"). * Allow http daemon tests in Travis CI tests. - (merge d9d1426 ls/travis-enable-httpd-tests later to maint). * Makefile assumed that -lrt is always available on platforms that want to use clock_gettime() and CLOCK_MONOTONIC, which is not a @@ -225,6 +245,17 @@ Performance, Internal Implementation, Development Support etc. * The API to iterate over all the refs (i.e. for_each_ref(), etc.) has been revamped. + * The handling of the "text=auto" attribute has been corrected. + $ echo "* text=auto eol=crlf" >.gitattributes + used to have the same effect as + $ echo "* text eol=crlf" >.gitattributes + i.e. declaring all files are text (ignoring "auto"). The + combination has been fixed to be equivalent to doing + $ git config core.autocrlf true + + * Documentation has been updated to show better example usage + of the updated "text=auto" attribute. + * A few tests that specifically target "git rebase -i" have been added. @@ -236,7 +267,6 @@ Performance, Internal Implementation, Development Support etc. to decide the set of supported options dynamically, which makes the code error-prone and hard to read. This has been corrected by tweaking the API to allocate and return a new copy of "struct option" array. - (merge 023ff39 jk/parse-options-concat later to maint). * "git fetch" exchanges batched have/ack messages between the sender and the receiver, initially doubling every time and then falling @@ -246,6 +276,46 @@ Performance, Internal Implementation, Development Support etc. repository. The internal mechanism learned to grow the window size more aggressively when working with the "smart http" transport. + * Tests for "git svn" have been taught to reuse the lib-httpd test + infrastructure when testing the subversion integration that + interacts with subversion repositories served over the http:// + protocol. + (merge a8a5d25 ew/git-svn-http-tests later to maint). + + * "git pack-objects" has a few options that tell it not to pack + objects found in certain packfiles, which require it to scan .idx + files of all available packs. The codepaths involved in these + operations have been optimized for a common case of not having any + non-local pack and/or any .kept pack. + + * The t3700 test about "add --chmod=-x" have been made a bit more + robust and generally cleaned up. + (merge 766cdc4 ib/t3700-add-chmod-x-updates later to maint). + + * The build procedure learned PAGER_ENV knob that lists what default + environment variable settings to export for popular pagers. This + mechanism is used to tweak the default settings to MORE on FreeBSD. + (merge 995bc22 ew/build-time-pager-tweaks later to maint). + + * The http-backend (the server-side component of smart-http + transport) used to trickle the HTTP header one at a time. Now + these write(2)s are batched. + (merge b36045c ew/http-backend-batch-headers later to maint). + + * When "git rebase" tries to compare set of changes on the updated + upstream and our own branch, it computes patch-id for all of these + changes and attempts to find matches. This has been optimized by + lazily computing the full patch-id (which is expensive) to be + compared only for changes that touch the same set of paths. + (merge ba67504 kw/patch-ids-optim later to maint). + + * A handful of tests that were broken under gettext-poison build have + been fixed. + + * The recent i18n patch we added during this cycle did a bit too much + refactoring of the messages to avoid word-legos; the repetition has + been reduced to help translators. + Also contains various documentation updates and code clean-ups. @@ -416,16 +486,13 @@ notes for details). "file" did not appear in the current commit. When "file" was created by renaming an existing file (but the change has not been committed), this restriction was unnecessarily tight. - (merge c66b470 mh/blame-worktree later to maint). * "git add -N dir/file && git write-tree" produced an incorrect tree when there are other paths in the same directory that sorts after "file". - (merge 6d6a782 nd/cache-tree-ita later to maint). * "git fetch http://user:pass@host/repo..." scrubbed the userinfo part, but "git push" didn't. - (merge 68f3c07 jk/push-scrub-url later to maint). * "git merge" with renormalization did not work well with merge-recursive, due to "safer crlf" conversion kicking in when it @@ -434,50 +501,41 @@ notes for details). * The use of strbuf in "git rm" to build filename to remove was a bit suboptimal, which has been fixed. - (merge deb8e15 rs/rm-strbuf-optim later to maint). * An age old bug that caused "git diff --ignore-space-at-eol" misbehave has been fixed. - (merge 044fb19 js/ignore-space-at-eol later to maint). * "git notes merge" had a code to see if a path exists (and fails if it does) and then open the path for writing (when it doesn't). Replace it with open with O_EXCL. - (merge deb9c15 rs/notes-merge-no-toctou later to maint). * "git pack-objects" and "git index-pack" mostly operate with off_t when talking about the offset of objects in a packfile, but there were a handful of places that used "unsigned long" to hold that value, leading to an unintended truncation. - (merge ec9d224 nd/pack-ofs-4gb-limit later to maint). * Recent update to "git daemon" tries to enable the socket-level KEEPALIVE, but when it is spawned via inetd, the standard input file descriptor may not necessarily be connected to a socket. Suppress an ENOTSOCK error from setsockopt(). - (merge fab6027 ew/daemon-socket-keepalive later to maint). * Recent FreeBSD stopped making perl available at /usr/bin/perl; switch the default the built-in path to /usr/local/bin/perl on not too ancient FreeBSD releases. - (merge 259f22a ew/find-perl-on-freebsd-in-local later to maint). * "git commit --help" said "--no-verify" is only about skipping the pre-commit hook, and failed to say that it also skipped the commit-msg hook. - (merge def480f os/no-verify-skips-commit-msg-too later to maint). * "git merge" in Git v2.9 was taught to forbid merging an unrelated lines of history by default, but that is exactly the kind of thing the "--rejoin" mode of "git subtree" (in contrib/) wants to do. "git subtree" has been taught to use the "--allow-unrelated-histories" option to override the default. - (merge 0f12c7d da/subtree-2.9-regression later to maint). * The build procedure for "git persistent-https" helper (in contrib/) has been updated so that it can be built with more recent versions of Go. - (merge accb613 pm/build-persistent-https-with-recent-go later to maint). * There is an optimization used in "git diff $treeA $treeB" to borrow an already checked-out copy in the working tree when it is known to @@ -488,23 +546,130 @@ notes for details). conversion (including the clean filter), which defeats the whole point of the optimization. The optimization has been disabled when the conversion is necessary. - (merge 06dec43 jk/diff-do-not-reuse-wtf-needs-cleaning later to maint). * "git -c grep.patternType=extended log --basic-regexp" misbehaved because the internal API to access the grep machinery was not designed well. - (merge 8465541 jc/grep-commandline-vs-configuration later to maint). + + * Windows port was failing some tests in t4130, due to the lack of + inum in the returned values by its lstat(2) emulation. + + * The reflog output format is documented better, and a new format + --date=unix to report the seconds-since-epoch (without timezone) + has been added. + (merge 442f6fd jk/reflog-date later to maint). + + * "git difftool <paths>..." started in a subdirectory failed to + interpret the paths relative to that directory, which has been + fixed. + + * The characters in the label shown for tags/refs for commits in + "gitweb" output are now properly escaped for proper HTML output. + + * FreeBSD can lie when asked mtime of a directory, which made the + untracked cache code to fall back to a slow-path, which in turn + caused tests in t7063 to fail because it wanted to verify the + behaviour of the fast-path. + + * Squelch compiler warnings for nedmalloc (in compat/) library. + + * A small memory leak in the command line parsing of "git blame" + has been plugged. + + * The API documentation for hashmap was unclear if hashmap_entry + can be safely discarded without any other consideration. State + that it is safe to do so. + + * Not-so-recent rewrite of "git am" that started making internal + calls into the commit machinery had an unintended regression, in + that no matter how many seconds it took to apply many patches, the + resulting committer timestamp for the resulting commits were all + the same. + + * "git push --force-with-lease" already had enough logic to allow + ensuring that such a push results in creation of a ref (i.e. the + receiving end did not have another push from sideways that would be + discarded by our force-pushing), but didn't expose this possibility + to the users. It does so now. + (merge 9eed4f3 jk/push-force-with-lease-creation later to maint). + + * The mechanism to limit the pack window memory size, when packing is + done using multiple threads (which is the default), is per-thread, + but this was not documented clearly. + (merge 954176c ms/document-pack-window-memory-is-per-thread later to maint). + + * "import-tars" fast-import script (in contrib/) used to ignore a + hardlink target and replaced it with an empty file, which has been + corrected to record the same blob as the other file the hardlink is + shared with. + (merge 04e0869 js/import-tars-hardlinks later to maint). + + * "git mv dir non-existing-dir/" did not work in some environments + the same way as existing mainstream platforms. The code now moves + "dir" to "non-existing-dir", without relying on rename("A", "B/") + that strips the trailing slash of '/'. + (merge 189d035 js/mv-dir-to-new-directory later to maint). + + * The "t/" hierarchy is prone to get an unusual pathname; "make test" + has been taught to make sure they do not contain paths that cannot + be checked out on Windows (and the mechanism can be reusable to + catch pathnames that are not portable to other platforms as need + arises). + (merge c2cafd3 js/test-lint-pathname later to maint). + + * When "git merge-recursive" works on history with many criss-cross + merges in "verbose" mode, the names the command assigns to the + virtual merge bases could have overwritten each other by unintended + reuse of the same piece of memory. + (merge 5447a76 rs/pull-signed-tag later to maint). + + * "git checkout --detach <branch>" used to give the same advice + message as that is issued when "git checkout <tag>" (or anything + that is not a branch name) is given, but asking with "--detach" is + an explicit enough sign that the user knows what is going on. The + advice message has been squelched in this case. + (merge 779b88a sb/checkout-explit-detach-no-advice later to maint). + + * "git difftool" by default ignores the error exit from the backend + commands it spawns, because often they signal that they found + differences by exiting with a non-zero status code just like "diff" + does; the exit status codes 126 and above however are special in + that they are used to signal that the command is not executable, + does not exist, or killed by a signal. "git difftool" has been + taught to notice these exit status codes. + (merge 45a4f5d jk/difftool-command-not-found later to maint). + + * On Windows, help.browser configuration variable used to be ignored, + which has been corrected. + (merge 6db5967 js/no-html-bypass-on-windows later to maint). + + * The "git -c var[=val] cmd" facility to append a configuration + variable definition at the end of the search order was described in + git(1) manual page, but not in git-config(1), which was more likely + place for people to look for when they ask "can I make a one-shot + override, and if so how?" + (merge ae1f709 dg/document-git-c-in-git-config-doc later to maint). + + * The tempfile (hence its user lockfile) API lets the caller to open + a file descriptor to a temporary file, write into it and then + finalize it by first closing the filehandle and then either + removing or renaming the temporary file. When the process spawns a + subprocess after obtaining the file descriptor, and if the + subprocess has not exited when the attempt to remove or rename is + made, the last step fails on Windows, because the subprocess has + the file descriptor still open. Open tempfile with O_CLOEXEC flag + to avoid this (on Windows, this is mapped to O_NOINHERIT). + (merge 05d1ed6 bw/mingw-avoid-inheriting-fd-to-lockfile later to maint). + + * Correct an age-old calco (is that a typo-like word for calc) + in the documentation. + (merge 7841c48 ls/packet-line-protocol-doc-fix later to maint). * Other minor clean-ups and documentation updates - (merge e51b0df pb/commit-editmsg-path later to maint). - (merge b333d0d jk/send-pack-stdio later to maint). - (merge fcf0fe9 lf/sideband-returns-void later to maint). - (merge c2691e2 ah/unpack-trees-advice-messages later to maint). - (merge c61b2af lf/recv-sideband-cleanup later to maint). - (merge 31471ba rs/use-strbuf-addbuf later to maint). - (merge 503e224 nd/test-helpers later to maint). - (merge 16726cf jc/doc-diff-filter-exclude later to maint). - (merge fd2e7da rs/worktree-use-strbuf-absolute-path later to maint). - (merge 406621f sb/submodule-deinit-all later to maint). - (merge 55cbe18 rs/submodule-config-code-cleanup later to maint). - (merge 280abfd sb/pack-protocol-doc-nak later to maint). + (merge 02a8cfa rs/merge-add-strategies-simplification later to maint). + (merge af4941d rs/merge-recursive-string-list-init later to maint). + (merge 1eb47f1 rs/use-strbuf-add-unique-abbrev later to maint). + (merge ddd0bfa jk/tighten-alloc later to maint). + (merge ecf30b2 rs/mailinfo-lib later to maint). + (merge 0eb75ce sg/reflog-past-root later to maint). + (merge 4369523 hv/doc-commit-reference-style later to maint). diff --git a/Documentation/RelNotes/2.3.10.txt b/Documentation/RelNotes/2.3.10.txt index 9d425d814d..20c2d2cacc 100644 --- a/Documentation/RelNotes/2.3.10.txt +++ b/Documentation/RelNotes/2.3.10.txt @@ -7,7 +7,7 @@ Fixes since v2.3.9 * xdiff code we use to generate diffs is not prepared to handle extremely large files. It uses "int" in many places, which can overflow if we have a very large number of lines or even bytes in - our input files, for example. Cap the input size to soemwhere + our input files, for example. Cap the input size to somewhere around 1GB for now. * Some protocols (like git-remote-ext) can execute arbitrary code diff --git a/Documentation/RelNotes/2.4.10.txt b/Documentation/RelNotes/2.4.10.txt index 8621199bc6..702d8d4e22 100644 --- a/Documentation/RelNotes/2.4.10.txt +++ b/Documentation/RelNotes/2.4.10.txt @@ -7,7 +7,7 @@ Fixes since v2.4.9 * xdiff code we use to generate diffs is not prepared to handle extremely large files. It uses "int" in many places, which can overflow if we have a very large number of lines or even bytes in - our input files, for example. Cap the input size to soemwhere + our input files, for example. Cap the input size to somewhere around 1GB for now. * Some protocols (like git-remote-ext) can execute arbitrary code diff --git a/Documentation/RelNotes/2.5.4.txt b/Documentation/RelNotes/2.5.4.txt index a5e8477a4a..b8a2f93ee7 100644 --- a/Documentation/RelNotes/2.5.4.txt +++ b/Documentation/RelNotes/2.5.4.txt @@ -7,7 +7,7 @@ Fixes since v2.5.4 * xdiff code we use to generate diffs is not prepared to handle extremely large files. It uses "int" in many places, which can overflow if we have a very large number of lines or even bytes in - our input files, for example. Cap the input size to soemwhere + our input files, for example. Cap the input size to somewhere around 1GB for now. * Some protocols (like git-remote-ext) can execute arbitrary code diff --git a/Documentation/RelNotes/2.6.1.txt b/Documentation/RelNotes/2.6.1.txt index 1e51363e3c..f37ea89cda 100644 --- a/Documentation/RelNotes/2.6.1.txt +++ b/Documentation/RelNotes/2.6.1.txt @@ -7,7 +7,7 @@ Fixes since v2.6 * xdiff code we use to generate diffs is not prepared to handle extremely large files. It uses "int" in many places, which can overflow if we have a very large number of lines or even bytes in - our input files, for example. Cap the input size to soemwhere + our input files, for example. Cap the input size to somewhere around 1GB for now. * Some protocols (like git-remote-ext) can execute arbitrary code diff --git a/Documentation/RelNotes/2.9.3.txt b/Documentation/RelNotes/2.9.3.txt index 28003a54ef..695b86f612 100644 --- a/Documentation/RelNotes/2.9.3.txt +++ b/Documentation/RelNotes/2.9.3.txt @@ -55,4 +55,116 @@ Fixes since v2.9.2 * A test that unconditionally used "mktemp" learned that the command is not necessarily available everywhere. + * "git blame file" allowed the lineage of lines in the uncommitted, + unadded contents of "file" to be inspected, but it refused when + "file" did not appear in the current commit. When "file" was + created by renaming an existing file (but the change has not been + committed), this restriction was unnecessarily tight. + + * "git add -N dir/file && git write-tree" produced an incorrect tree + when there are other paths in the same directory that sorts after + "file". + + * "git fetch http://user:pass@host/repo..." scrubbed the userinfo + part, but "git push" didn't. + + * An age old bug that caused "git diff --ignore-space-at-eol" + misbehave has been fixed. + + * "git notes merge" had a code to see if a path exists (and fails if + it does) and then open the path for writing (when it doesn't). + Replace it with open with O_EXCL. + + * "git pack-objects" and "git index-pack" mostly operate with off_t + when talking about the offset of objects in a packfile, but there + were a handful of places that used "unsigned long" to hold that + value, leading to an unintended truncation. + + * Recent update to "git daemon" tries to enable the socket-level + KEEPALIVE, but when it is spawned via inetd, the standard input + file descriptor may not necessarily be connected to a socket. + Suppress an ENOTSOCK error from setsockopt(). + + * Recent FreeBSD stopped making perl available at /usr/bin/perl; + switch the default the built-in path to /usr/local/bin/perl on not + too ancient FreeBSD releases. + + * "git status" learned to suggest "merge --abort" during a conflicted + merge, just like it already suggests "rebase --abort" during a + conflicted rebase. + + * The .c/.h sources are marked as such in our .gitattributes file so + that "git diff -W" and friends would work better. + + * Existing autoconf generated test for the need to link with pthread + library did not check all the functions from pthread libraries; + recent FreeBSD has some functions in libc but not others, and we + mistakenly thought linking with libc is enough when it is not. + + * Allow http daemon tests in Travis CI tests. + + * Users of the parse_options_concat() API function need to allocate + extra slots in advance and fill them with OPT_END() when they want + to decide the set of supported options dynamically, which makes the + code error-prone and hard to read. This has been corrected by tweaking + the API to allocate and return a new copy of "struct option" array. + + * The use of strbuf in "git rm" to build filename to remove was a bit + suboptimal, which has been fixed. + + * "git commit --help" said "--no-verify" is only about skipping the + pre-commit hook, and failed to say that it also skipped the + commit-msg hook. + + * "git merge" in Git v2.9 was taught to forbid merging an unrelated + lines of history by default, but that is exactly the kind of thing + the "--rejoin" mode of "git subtree" (in contrib/) wants to do. + "git subtree" has been taught to use the "--allow-unrelated-histories" + option to override the default. + + * The build procedure for "git persistent-https" helper (in contrib/) + has been updated so that it can be built with more recent versions + of Go. + + * There is an optimization used in "git diff $treeA $treeB" to borrow + an already checked-out copy in the working tree when it is known to + be the same as the blob being compared, expecting that open/mmap of + such a file is faster than reading it from the object store, which + involves inflating and applying delta. This however kicked in even + when the checked-out copy needs to go through the convert-to-git + conversion (including the clean filter), which defeats the whole + point of the optimization. The optimization has been disabled when + the conversion is necessary. + + * "git -c grep.patternType=extended log --basic-regexp" misbehaved + because the internal API to access the grep machinery was not + designed well. + + * Windows port was failing some tests in t4130, due to the lack of + inum in the returned values by its lstat(2) emulation. + + * The characters in the label shown for tags/refs for commits in + "gitweb" output are now properly escaped for proper HTML output. + + * FreeBSD can lie when asked mtime of a directory, which made the + untracked cache code to fall back to a slow-path, which in turn + caused tests in t7063 to fail because it wanted to verify the + behaviour of the fast-path. + + * Squelch compiler warnings for netmalloc (in compat/) library. + + * The API documentation for hashmap was unclear if hashmap_entry + can be safely discarded without any other consideration. State + that it is safe to do so. + + * Not-so-recent rewrite of "git am" that started making internal + calls into the commit machinery had an unintended regression, in + that no matter how many seconds it took to apply many patches, the + resulting committer timestamp for the resulting commits were all + the same. + + * "git difftool <paths>..." started in a subdirectory failed to + interpret the paths relative to that directory, which has been + fixed. + Also contains minor documentation updates and code clean-ups. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e8ad978824..500230c054 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -121,6 +121,11 @@ its behaviour. Try to make sure your explanation can be understood without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion. +If you want to reference a previous commit in the history of a stable +branch use the format "abbreviated sha1 (subject, date)". So for example +like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) +noticed [...]". + (3) Generate your patch using Git tools out of your commits. diff --git a/Documentation/config.txt b/Documentation/config.txt index e2571ea8ea..32f065ca6a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1253,6 +1253,16 @@ format.attach:: value as the boundary. See the --attach option in linkgit:git-format-patch[1]. +format.from:: + Provides the default value for the `--from` option to format-patch. + Accepts a boolean value, or a name and email address. If false, + format-patch defaults to `--no-from`, using commit authors directly in + the "From:" field of patch mails. If true, format-patch defaults to + `--from`, using your committer identity in the "From:" field of patch + mails and including a "From:" field in the body of the patch mail if + different. If set to a non-boolean value, format-patch uses that + value instead of your committer identity. Defaults to false. + format.numbered:: A boolean which can enable or disable sequence numbers in patch subjects. It defaults to "auto" which enables it only if there @@ -2507,6 +2517,12 @@ receive.unpackLimit:: especially on slow filesystems. If not set, the value of `transfer.unpackLimit` is used instead. +receive.maxInputSize:: + If the size of the incoming pack stream is larger than this + limit, then git-receive-pack will error out, instead of + accepting the pack file. If not set or set to 0, then the size + is unlimited. + receive.denyDeletes:: If set to true, git-receive-pack will deny a ref update that deletes the ref. Use this to prevent such a ref deletion via a push. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index f163113a6f..83f86b9231 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -263,6 +263,9 @@ The files are read in the order given above, with last value found taking precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. +You may override individual configuration parameters when running any git +command by using the `-c` option. See linkgit:git[1] for details. + All writing options will per default write to the repository specific configuration file. Note that this also affects options like `--replace-all` and `--unset`. *'git config' will only ever change one file at a time*. diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index 7a4e055520..1b4b65d665 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -87,6 +87,8 @@ OPTIONS Specifying 0 will cause Git to auto-detect the number of CPU's and use maximum 3 threads. +--max-input-size=<size>:: + Die, if the pack is larger than <size>. Note ---- diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 078b556665..0d933ac355 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -159,8 +159,7 @@ not accessible in the working tree. + <eolattr> is the attribute that is used when checking out or committing, it is either "", "-text", "text", "text=auto", "text eol=lf", "text eol=crlf". -Note: Currently Git does not support "text=auto eol=lf" or "text=auto eol=crlf", -that may change in the future. +Since Git 2.10 "text=auto eol=lf" and "text=auto eol=crlf" are supported. + Both the <eolinfo> in the index ("i/<eolinfo>") and in the working tree ("w/<eolinfo>") are shown for regular files, diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 19cdcd0341..8973510a41 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -104,8 +104,8 @@ base-name:: out of memory with a large window, but still be able to take advantage of the large window for the smaller objects. The size can be suffixed with "k", "m", or "g". - `--window-memory=0` makes memory usage unlimited, which is the - default. + `--window-memory=0` makes memory usage unlimited. The default + is taken from the `pack.windowMemory` configuration variable. --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index ec514f6cd5..47b77e693b 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -204,10 +204,11 @@ branch we have for it. + `--force-with-lease=<refname>:<expect>` will protect the named ref (alone), if it is going to be updated, by requiring its current value to be -the same as the specified value <expect> (which is allowed to be +the same as the specified value `<expect>` (which is allowed to be different from the remote-tracking branch we have for the refname, or we do not even have to have such a remote-tracking branch when -this form is used). +this form is used). If `<expect>` is the empty string, then the named ref +must not already exist. + Note that all forms other than `--force-with-lease=<refname>:<expect>` that specifies the expected current value of the ref explicitly are diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt index 000ee8dba2..0ccd5fbc78 100644 --- a/Documentation/git-receive-pack.txt +++ b/Documentation/git-receive-pack.txt @@ -33,6 +33,9 @@ post-update hooks found in the Documentation/howto directory. option, which tells it if updates to a ref should be denied if they are not fast-forwards. +A number of other receive.* config options are available to tweak +its behavior, see linkgit:git-config[1]. + OPTIONS ------- <directory>:: diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt index e700bafa47..80afca866c 100644 --- a/Documentation/git-remote-fd.txt +++ b/Documentation/git-remote-fd.txt @@ -17,7 +17,7 @@ fetch, push or archive. If only <infd> is given, it is assumed to be a bidirectional socket connected to remote Git server (git-upload-pack, git-receive-pack or -git-upload-achive). If both <infd> and <outfd> are given, they are assumed +git-upload-archive). If both <infd> and <outfd> are given, they are assumed to be pipes connected to a remote Git server (<infd> being the inbound pipe and <outfd> being the outbound pipe. diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt index c5975234f4..26afe6ed54 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -100,8 +100,10 @@ other objects in that pack they already have locally. out of memory with a large window, but still be able to take advantage of the large window for the smaller objects. The size can be suffixed with "k", "m", or "g". - `--window-memory=0` makes memory usage unlimited, which is the - default. + `--window-memory=0` makes memory usage unlimited. The default + is taken from the `pack.windowMemory` configuration variable. + Note that the actual memory usage will be the limit multiplied + by the number of threads used by linkgit:git-pack-objects[1]. --max-pack-size=<n>:: Maximum size of each output pack file. The size can be suffixed with diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index e1e8f57cdd..725065ef2d 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -32,11 +32,14 @@ OPTIONS --branch:: Show the branch and tracking info even in short-format. ---porcelain:: +--porcelain[=<version>]:: Give the output in an easy-to-parse format for scripts. This is similar to the short output, but will remain stable across Git versions and regardless of user configuration. See below for details. ++ +The version parameter is used to specify the format version. +This is optional and defaults to the original version 'v1' format. --long:: Give the output in the long-format. This is the default. @@ -96,7 +99,7 @@ configuration variable documented in linkgit:git-config[1]. -z:: Terminate entries with NUL, instead of LF. This implies - the `--porcelain` output format if no other format is given. + the `--porcelain=v1` output format if no other format is given. --column[=<options>]:: --no-column:: @@ -180,12 +183,12 @@ in which case `XY` are `!!`. If -b is used the short-format status is preceded by a line -## branchname tracking info + ## branchname tracking info -Porcelain Format -~~~~~~~~~~~~~~~~ +Porcelain Format Version 1 +~~~~~~~~~~~~~~~~~~~~~~~~~~ -The porcelain format is similar to the short format, but is guaranteed +Version 1 porcelain format is similar to the short format, but is guaranteed not to change in a backwards-incompatible way between Git versions or based on user configuration. This makes it ideal for parsing by scripts. The description of the short format above also describes the porcelain @@ -207,6 +210,124 @@ field from the first filename). Third, filenames containing special characters are not specially formatted; no quoting or backslash-escaping is performed. +Porcelain Format Version 2 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Version 2 format adds more detailed information about the state of +the worktree and changed items. Version 2 also defines an extensible +set of easy to parse optional headers. + +Header lines start with "#" and are added in response to specific +command line arguments. Parsers should ignore headers they +don't recognize. + +### Branch Headers + +If `--branch` is given, a series of header lines are printed with +information about the current branch. + + Line Notes + ------------------------------------------------------------ + # branch.oid <commit> | (initial) Current commit. + # branch.head <branch> | (detached) Current branch. + # branch.upstream <upstream_branch> If upstream is set. + # branch.ab +<ahead> -<behind> If upstream is set and + the commit is present. + ------------------------------------------------------------ + +### Changed Tracked Entries + +Following the headers, a series of lines are printed for tracked +entries. One of three different line formats may be used to describe +an entry depending on the type of change. Tracked entries are printed +in an undefined order; parsers should allow for a mixture of the 3 +line types in any order. + +Ordinary changed entries have the following format: + + 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path> + +Renamed or copied entries have the following format: + + 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath> + + Field Meaning + -------------------------------------------------------- + <XY> A 2 character field containing the staged and + unstaged XY values described in the short format, + with unchanged indicated by a "." rather than + a space. + <sub> A 4 character field describing the submodule state. + "N..." when the entry is not a submodule. + "S<c><m><u>" when the entry is a submodule. + <c> is "C" if the commit changed; otherwise ".". + <m> is "M" if it has tracked changes; otherwise ".". + <u> is "U" if there are untracked changes; otherwise ".". + <mH> The octal file mode in HEAD. + <mI> The octal file mode in the index. + <mW> The octal file mode in the worktree. + <hH> The object name in HEAD. + <hI> The object name in the index. + <X><score> The rename or copy score (denoting the percentage + of similarity between the source and target of the + move or copy). For example "R100" or "C75". + <path> The pathname. In a renamed/copied entry, this + is the path in the index and in the working tree. + <sep> When the `-z` option is used, the 2 pathnames are separated + with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09) + byte separates them. + <origPath> The pathname in the commit at HEAD. This is only + present in a renamed/copied entry, and tells + where the renamed/copied contents came from. + -------------------------------------------------------- + +Unmerged entries have the following format; the first character is +a "u" to distinguish from ordinary changed entries. + + u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path> + + Field Meaning + -------------------------------------------------------- + <XY> A 2 character field describing the conflict type + as described in the short format. + <sub> A 4 character field describing the submodule state + as described above. + <m1> The octal file mode in stage 1. + <m2> The octal file mode in stage 2. + <m3> The octal file mode in stage 3. + <mW> The octal file mode in the worktree. + <h1> The object name in stage 1. + <h2> The object name in stage 2. + <h3> The object name in stage 3. + <path> The pathname. + -------------------------------------------------------- + +### Other Items + +Following the tracked entries (and if requested), a series of +lines will be printed for untracked and then ignored items +found in the worktree. + +Untracked items have the following format: + + ? <path> + +Ignored items have the following format: + + ! <path> + +### Pathname Format Notes and -z + +When the `-z` option is given, pathnames are printed as is and +without any quoting and lines are terminated with a NUL (ASCII 0x00) +byte. + +Otherwise, all pathnames will be "C-quoted" if they contain any tab, +linefeed, double quote, or backslash characters. In C-quoting, these +characters will be replaced with the corresponding C-style escape +sequences and the resulting pathname will be double quoted. + + CONFIGURATION ------------- diff --git a/Documentation/git-unpack-objects.txt b/Documentation/git-unpack-objects.txt index 3e887d1610..b3de50d710 100644 --- a/Documentation/git-unpack-objects.txt +++ b/Documentation/git-unpack-objects.txt @@ -44,6 +44,9 @@ OPTIONS --strict:: Don't write objects with broken content or links. +--max-input-size=<size>:: + Die, if the pack is larger than <size>. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git.txt b/Documentation/git.txt index f4dfc9d42c..7913fc2513 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -43,9 +43,15 @@ unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v2.9.2/git.html[documentation for release 2.9.2] +* link:v2.10.0/git.html[documentation for release 2.10] * release notes for + link:RelNotes/2.10.0.txt[2.10]. + +* link:v2.9.3/git.html[documentation for release 2.9.3] + +* release notes for + link:RelNotes/2.9.3.txt[2.9.3], link:RelNotes/2.9.2.txt[2.9.2], link:RelNotes/2.9.1.txt[2.9.1], link:RelNotes/2.9.0.txt[2.9]. diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index b40068bdfd..7aff940202 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -133,7 +133,7 @@ Set to string value "auto":: When `text` is set to "auto", the path is marked for automatic end-of-line conversion. If Git decides that the content is text, its line endings are converted to LF on checkin. - When the file has been commited with CRLF, no conversion is done. + When the file has been committed with CRLF, no conversion is done. Unspecified:: @@ -182,23 +182,6 @@ While Git normally leaves file contents alone, it can be configured to normalize line endings to LF in the repository and, optionally, to convert them to CRLF when files are checked out. -Here is an example that will make Git normalize .txt, .vcproj and .sh -files, ensure that .vcproj files have CRLF and .sh files have LF in -the working directory, and prevent .jpg files from being normalized -regardless of their content. - ------------------------- -* text=auto -*.txt text -*.vcproj text eol=crlf -*.sh text eol=lf -*.jpg -text ------------------------- - -Other source code management systems normalize all text files in their -repositories, and there are two ways to enable similar automatic -normalization in Git. - If you simply want to have CRLF line endings in your working directory regardless of the repository you are working with, you can set the config variable "core.autocrlf" without using any attributes. @@ -208,35 +191,42 @@ config variable "core.autocrlf" without using any attributes. autocrlf = true ------------------------ -This does not force normalization of all text files, but does ensure +This does not force normalization of text files, but does ensure that text files that you introduce to the repository have their line endings normalized to LF when they are added, and that files that are already normalized in the repository stay normalized. -If you want to interoperate with a source code management system that -enforces end-of-line normalization, or you simply want all text files -in your repository to be normalized, you should instead set the `text` -attribute to "auto" for _all_ files. +If you want to ensure that text files that any contributor introduces to +the repository have their line endings normalized, you can set the +`text` attribute to "auto" for _all_ files. ------------------------ * text=auto ------------------------ -This ensures that all files that Git considers to be text will have -normalized (LF) line endings in the repository. The `core.eol` -configuration variable controls which line endings Git will use for -normalized files in your working directory; the default is to use the -native line ending for your platform, or CRLF if `core.autocrlf` is -set. +The attributes allow a fine-grained control, how the line endings +are converted. +Here is an example that will make Git normalize .txt, .vcproj and .sh +files, ensure that .vcproj files have CRLF and .sh files have LF in +the working directory, and prevent .jpg files from being normalized +regardless of their content. + +------------------------ +* text=auto +*.txt text +*.vcproj text eol=crlf +*.sh text eol=lf +*.jpg -text +------------------------ + +NOTE: When `text=auto` conversion is enabled in a cross-platform +project using push and pull to a central repository the text files +containing CRLFs should be normalized. -NOTE: When `text=auto` normalization is enabled in an existing -repository, any text files containing CRLFs should be normalized. If -they are not they will be normalized the next time someone tries to -change them, causing unfortunate misattribution. From a clean working -directory: +From a clean working directory: ------------------------------------------------- -$ echo "* text=auto" >>.gitattributes +$ echo "* text=auto" >.gitattributes $ rm .git/index # Remove the index to force Git to $ git reset # re-scan the working directory $ git status # Show files that will be normalized @@ -377,6 +367,11 @@ substitution. For example: smudge = git-p4-filter --smudge %f ------------------------ +Note that "%f" is the name of the path that is being worked on. Depending +on the version that is being filtered, the corresponding file on disk may +not exist, or may have different contents. So, smudge and clean commands +should not try to access the file on disk, but only act as filters on the +content provided to them on standard input. Interaction between checkin/checkout attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index a68d860fa3..e382dd96df 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list. --left-right:: - Mark which side of a symmetric diff a commit is reachable + Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with a `<` symbol and those from the right with a `>` symbol. diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 07cdd73ab2..10dcc08ff9 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -79,6 +79,11 @@ submodule.<name>.ignore:: "--ignore-submodule" option. The 'git submodule' commands are not affected by this setting. +submodule.<name>.shallow:: + When set to true, a clone of this submodule will be performed as a + shallow clone unless the user explicitly asks for a non-shallow + clone. + EXAMPLES -------- diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt index e903eb7860..27dec5b91d 100644 --- a/Documentation/gitrevisions.txt +++ b/Documentation/gitrevisions.txt @@ -15,9 +15,9 @@ DESCRIPTION Many Git commands take revision parameters as arguments. Depending on the command, they denote a specific commit or, for commands which -walk the revision graph (such as linkgit:git-log[1]), all commits which can -be reached from that commit. In the latter case one can also specify a -range of revisions explicitly. +walk the revision graph (such as linkgit:git-log[1]), all commits which are +reachable from that commit. For commands that walk the revision graph one can +also specify a range of revisions explicitly. In addition, some Git commands (such as linkgit:git-show[1]) also take revision parameters which denote other objects than commits, e.g. blobs diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 29b19b992f..a942d57f73 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -147,8 +147,14 @@ endif::git-rev-list[] "U" for a good signature with unknown validity and "N" for no signature - '%GS': show the name of the signer for a signed commit - '%GK': show the key used to sign a signed commit -- '%gD': reflog selector, e.g., `refs/stash@{1}` -- '%gd': shortened reflog selector, e.g., `stash@{1}` +- '%gD': reflog selector, e.g., `refs/stash@{1}` or + `refs/stash@{2 minutes ago`}; the format follows the rules described + for the `-g` option. The portion before the `@` is the refname as + given on the command line (so `git log -g refs/heads/master` would + yield `refs/heads/master@{0}`). +- '%gd': shortened reflog selector; same as `%gD`, but the refname + portion is shortened for human readability (so `refs/heads/master` + becomes just `master`). - '%gn': reflog identity name - '%gN': reflog identity name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1]) @@ -166,7 +172,7 @@ endif::git-rev-list[] respecting the `auto` settings of the former if we are going to a terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring on the next placeholders until the color is switched again. -- '%m': left, right or boundary mark +- '%m': left (`<`), right (`>`) or boundary (`-`) mark - '%n': newline - '%%': a raw '%' - '%x00': print a byte from a hex code diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index f39cb6d4f5..7e462d3841 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -225,7 +225,7 @@ excluded from the output. --left-only:: --right-only:: - List only commits on the respective side of a symmetric range, + List only commits on the respective side of a symmetric difference, i.e. only those which would be marked `<` resp. `>` by `--left-right`. + @@ -252,10 +252,25 @@ list. + With `--pretty` format other than `oneline` (for obvious reasons), this causes the output to have two extra lines of information -taken from the reflog. By default, 'commit@\{Nth}' notation is -used in the output. When the starting commit is specified as -'commit@\{now}', output also uses 'commit@\{timestamp}' notation -instead. Under `--pretty=oneline`, the commit message is +taken from the reflog. The reflog designator in the output may be shown +as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the +reflog) or as `ref@{timestamp}` (with the timestamp for that entry), +depending on a few rules: ++ +-- +1. If the starting point is specified as `ref@{Nth}`, show the index +format. ++ +2. If the starting point was specified as `ref@{now}`, show the +timestamp format. ++ +3. If neither was used, but `--date` was given on the command line, show +the timestamp in the format requested by `--date`. ++ +4. Otherwise, show the index format. +-- ++ +Under `--pretty=oneline`, the commit message is prefixed with this information on the same line. This option cannot be combined with `--reverse`. See also linkgit:git-reflog[1]. @@ -714,8 +729,8 @@ include::pretty-options.txt[] `iso-local`), the user's local time zone is used instead. + `--date=relative` shows dates relative to the current time, -e.g. ``2 hours ago''. The `-local` option cannot be used with -`--raw` or `--relative`. +e.g. ``2 hours ago''. The `-local` option has no effect for +`--date=relative`. + `--date=local` is an alias for `--date=default-local`. + @@ -735,7 +750,18 @@ format, often found in email messages. + `--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format. + -`--date=raw` shows the date in the internal raw Git format `%s %z` format. +`--date=raw` shows the date as seconds since the epoch (1970-01-01 +00:00:00 UTC), followed by a space, and then the timezone as an offset +from UTC (a `+` or `-` with four digits; the first two are hours, and +the second two are minutes). I.e., as if the timestamp were formatted +with `strftime("%s %z")`). +Note that the `-local` option does not affect the seconds-since-epoch +value (which is always measured in UTC), but does switch the accompanying +timezone value. ++ +`--date=unix` shows the date as a Unix epoch timestamp (seconds since +1970). As with `--raw`, this is always in UTC and therefore `-local` +has no effect. + `--date=format:...` feeds the format `...` to your system `strftime`. Use `--date=format:%c` to show the date in your system locale's @@ -770,7 +796,7 @@ ifdef::git-rev-list[] endif::git-rev-list[] --left-right:: - Mark which side of a symmetric diff a commit is reachable from. + Mark which side of a symmetric difference a commit is reachable from. Commits from the left side are prefixed with `<` and those from the right with `>`. If combined with `--boundary`, those commits are prefixed with `-`. diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index abae363983..4bed5b1ab7 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -237,48 +237,74 @@ SPECIFYING RANGES ----------------- History traversing commands such as `git log` operate on a set -of commits, not just a single commit. To these commands, -specifying a single revision with the notation described in the -previous section means the set of commits reachable from that -commit, following the commit ancestry chain. - -To exclude commits reachable from a commit, a prefix '{caret}' -notation is used. E.g. '{caret}r1 r2' means commits reachable -from 'r2' but exclude the ones reachable from 'r1'. - -This set operation appears so often that there is a shorthand -for it. When you have two commits 'r1' and 'r2' (named according -to the syntax explained in SPECIFYING REVISIONS above), you can ask -for commits that are reachable from r2 excluding those that are reachable -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. - -A similar notation 'r1\...r2' is called symmetric difference -of 'r1' and 'r2' and is defined as -'r1 r2 --not $(git merge-base --all r1 r2)'. -It is the set of commits that are reachable from either one of -'r1' or 'r2' but not from both. - -In these two shorthands, you can omit one end and let it default to HEAD. +of commits, not just a single commit. + +For these commands, +specifying a single revision, using the notation described in the +previous section, means the set of commits `reachable` from the given +commit. + +A commit's reachable set is the commit itself and the commits in +its ancestry chain. + + +Commit Exclusions +~~~~~~~~~~~~~~~~~ + +'{caret}<rev>' (caret) Notation:: + To exclude commits reachable from a commit, a prefix '{caret}' + notation is used. E.g. '{caret}r1 r2' means commits reachable + from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and + its ancestors). + +Dotted Range Notations +~~~~~~~~~~~~~~~~~~~~~~ + +The '..' (two-dot) Range Notation:: + The '{caret}r1 r2' set operation appears so often that there is a shorthand + for it. When you have two commits 'r1' and 'r2' (named according + to the syntax explained in SPECIFYING REVISIONS above), you can ask + for commits that are reachable from r2 excluding those that are reachable + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'. + +The '...' (three dot) Symmetric Difference Notation:: + A similar notation 'r1\...r2' is called symmetric difference + of 'r1' and 'r2' and is defined as + 'r1 r2 --not $(git merge-base --all r1 r2)'. + It is the set of commits that are reachable from either one of + 'r1' (left side) or 'r2' (right side) but not from both. + +In these two shorthand notations, you can omit one end and let it default to HEAD. For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What did I do since I forked from the origin branch?" Similarly, '..origin' is a shorthand for 'HEAD..origin' and asks "What did the origin do since I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an empty range that is both reachable and unreachable from HEAD. -Two other shorthands for naming a set that is formed by a commit -and its parent commits exist. The 'r1{caret}@' notation means all -parents of 'r1'. 'r1{caret}!' includes commit 'r1' but excludes -all of its parents. +Other <rev>{caret} Parent Shorthand Notations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Two other shorthands exist, particularly useful for merge commits, +for naming a set that is formed by a commit and its parent commits. + +The 'r1{caret}@' notation means all parents of 'r1'. + +The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents. +By itself, this notation denotes the single commit 'r1'. + +While '<rev>{caret}<n>' was about specifying a single commit parent, these +two notations consider all its parents. For example you can say +'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'. -To summarize: +Revision Range Summary +---------------------- '<rev>':: - Include commits that are reachable from (i.e. ancestors of) - <rev>. + Include commits that are reachable from <rev> (i.e. <rev> and its + ancestors). '{caret}<rev>':: - Exclude commits that are reachable from (i.e. ancestors of) - <rev>. + Exclude commits that are reachable from <rev> (i.e. <rev> and its + ancestors). '<rev1>..<rev2>':: Include commits that are reachable from <rev2> but exclude @@ -300,16 +326,27 @@ To summarize: as giving commit '<rev>' and then all its parents prefixed with '{caret}' to exclude them (and their ancestors). -Here are a handful of examples: - - D G H D - D F G H I J D F - ^G D H D - ^D B E I J F B - B..C C - B...C G H D E B C - ^D B C E I J F B C - C I J F C - C^@ I J F - C^! C - F^! D G H D F +Here are a handful of examples using the Loeliger illustration above, +with each step in the notation's expansion and selection carefully +spelt out: + + Args Expanded arguments Selected commits + D G H D + D F G H I J D F + ^G D H D + ^D B E I J F B + ^D B C E I J F B C + C I J F C + B..C = ^B C C + B...C = B ^F C G H D E B C + C^@ = C^1 + = F I J F + B^@ = B^1 B^2 B^3 + = D E F D G H E F I J + C^! = C ^C^@ + = C ^C^1 + = C ^F C + B^! = B ^B^@ + = B ^B^1 ^B^2 ^B^3 + = B ^D ^E ^F B + F^! D = F ^I ^J D G H D F diff --git a/Documentation/technical/api-hashmap.txt b/Documentation/technical/api-hashmap.txt index ad7a5bddd2..28f5a8b715 100644 --- a/Documentation/technical/api-hashmap.txt +++ b/Documentation/technical/api-hashmap.txt @@ -104,6 +104,11 @@ If `free_entries` is true, each hashmap_entry in the map is freed as well `entry` points to the entry to initialize. + `hash` is the hash code of the entry. ++ +The hashmap_entry structure does not hold references to external resources, +and it is safe to just discard it once you are done with it (i.e. if +your structure was allocated with xmalloc(), you can just free(3) it, +and if it is on stack, you can just let it go out of scope). `void *hashmap_get(const struct hashmap *map, const void *key, const void *keydata)`:: diff --git a/Documentation/technical/protocol-common.txt b/Documentation/technical/protocol-common.txt index bf30167ae3..ecedb34bba 100644 --- a/Documentation/technical/protocol-common.txt +++ b/Documentation/technical/protocol-common.txt @@ -67,9 +67,9 @@ with non-binary data the same whether or not they contain the trailing LF (stripping the LF if present, and not complaining when it is missing). -The maximum length of a pkt-line's data component is 65520 bytes. -Implementations MUST NOT send pkt-line whose length exceeds 65524 -(65520 bytes of payload + 4 bytes of length data). +The maximum length of a pkt-line's data component is 65516 bytes. +Implementations MUST NOT send pkt-line whose length exceeds 65520 +(65516 bytes of payload + 4 bytes of length data). Implementations SHOULD NOT send an empty pkt-line ("0004"). |