diff options
Diffstat (limited to 'Documentation')
24 files changed, 675 insertions, 102 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 2ab65561af..4ae9ba5c86 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -39,6 +39,7 @@ MAN7_TXT += gitworkflows.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) +GIT_MAN_REF = master OBSOLETE_HTML += everyday.html OBSOLETE_HTML += git-remote-helpers.html @@ -437,14 +438,14 @@ require-manrepo:: then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi quick-install-man: require-manrepo - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF) require-htmlrepo:: @if test ! -d $(HTML_REPO); \ then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi quick-install-html: require-htmlrepo - '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) + '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF) print-man1: @for i in $(MAN1_TXT); do echo $$i; done diff --git a/Documentation/RelNotes/2.16.0.txt b/Documentation/RelNotes/2.16.0.txt index 073a126a9c..0c81c5915f 100644 --- a/Documentation/RelNotes/2.16.0.txt +++ b/Documentation/RelNotes/2.16.0.txt @@ -62,8 +62,11 @@ UI, Workflows & Features * The SubmittingPatches document has been converted to produce an HTML version via AsciiDoc/Asciidoctor. - * We learned to talk to watchman to speed up "git status" and other - operations that need to see which paths have been modified. + * We learned to optionally talk to a file system monitor via new + fsmonitor extension to speed up "git status" and other operations + that need to see which paths have been modified. Currently we only + support "watchman". See File System Monitor section of + git-update-index(1) for more detail. * The "diff" family of commands learned to ignore differences in carriage return at the end of line. @@ -120,6 +123,31 @@ UI, Workflows & Features who are used to seeing abbreviated object names and find them confusing with the range syntax. + * With a configuration variable rebase.abbreviateCommands set, + "git rebase -i" produces the todo list with a single-letter + command names. + + * "git worktree add" learned to run the post-checkout hook, just like + "git checkout" does, after the initial checkout. + + * "git svn" has been updated to strip CRs in the commit messages, as + recent versions of Subversion rejects them. + + * "git imap-send" did not correctly quote the folder name when + making a request to the server, which has been corrected. + + * Error messages from "git rebase" have been somewhat cleaned up. + + * Git has been taught to support an https:// URL used for http.proxy + when using recent versions of libcurl. + + * "git merge" learned to pay attention to merge.verifySignatures + configuration variable and pretend as if '--verify-signatures' + option was given from the command line. + + * "git describe" was taught to dig trees deeper to find a + <commit-ish>:<path> that refers to a given blob object. + Performance, Internal Implementation, Development Support etc. @@ -183,6 +211,23 @@ Performance, Internal Implementation, Development Support etc. * The tracing infrastructure has been optimized for cases where no tracing is requested. + * In preparation for implementing narrow/partial clone, the object + walking machinery has been taught a way to tell it to "filter" some + objects from enumeration. + + * A few structures and variables that are implementation details of + the decorate API have been renamed and then the API got documented + better. + + * Assorted updates for TravisCI integration. + (merge 4f26366679 sg/travis-fixes later to maint). + + * Introduce a helper to simplify code to parse a common pattern that + expects either "--key" or "--key=<something>". + + * "git version --build-options" learned to report the host CPU and + the exact commit object name the binary was built from. + Also contains various documentation updates and code clean-ups. @@ -299,7 +344,7 @@ Fixes since v2.15 * Command line completion (in contrib/) has been taught about the "--copy" option of "git branch". - * When "git rebase" prepared an mailbox of changes and fed it to "git + * When "git rebase" prepared a mailbox of changes and fed it to "git am" to replay them, it was confused when a stray "From " happened to be in the log message of one of the replayed changes. This has been corrected. @@ -374,6 +419,40 @@ Fixes since v2.15 lost. (merge abfb04d0c7 ls/editor-waiting-message later to maint). + * The "safe crlf" check incorrectly triggered for contents that does + not use CRLF as line endings, which has been corrected. + (merge 649f1f0948 tb/check-crlf-for-safe-crlf later to maint). + + * "git clone --shared" to borrow from a (secondary) worktree did not + work, even though "git clone --local" did. Both are now accepted. + (merge b3b05971c1 es/clone-shared-worktree later to maint). + + * The build procedure now allows not just the repositories but also + the refs to be used to take pre-formatted manpages and html + documents to install. + (merge 65289e9dcd rb/quick-install-doc later to maint). + + * Update the shell prompt script (in contrib/) to strip trailing CR + from strings read from various "state" files. + (merge 041fe8fc83 ra/prompt-eread-fix later to maint). + + * "git merge -s recursive" did not correctly abort when the index is + dirty, if the merged tree happened to be the same as the current + HEAD, which has been fixed. + + * Bytes with high-bit set were encoded incorrectly and made + credential helper fail. + (merge 4c267f2ae3 jd/fix-strbuf-add-urlencode-bytes later to maint). + + * "git rebase -p -X<option>" did not propagate the option properly + down to underlying merge strategy backend. + (merge dd6fb0053c js/fix-merge-arg-quoting-in-rebase-p later to maint). + + * "git merge -s recursive" did not correctly abort when the index is + dirty, if the merged tree happened to be the same as the current + HEAD, which has been fixed. + (merge f309e8e768 ew/empty-merge-with-dirty-index-maint later to maint). + * Other minor doc, test and build updates and code cleanups. (merge 1a1fc2d5b5 rd/man-prune-progress later to maint). (merge 0ba014035a rd/man-reflog-add-n later to maint). @@ -384,3 +463,20 @@ Fixes since v2.15 (merge 5e83cca0b8 jk/no-optional-locks later to maint). (merge 826c778f7c js/hashmap-update-sample later to maint). (merge 176b2d328c sg/setup-doc-update later to maint). + (merge 1b09073514 rs/am-builtin-leakfix later to maint). + (merge addcf6cfde rs/fmt-merge-msg-string-leak-fix later to maint). + (merge c3ff8f6c14 rs/strbuf-read-once-reset-length later to maint). + (merge 6b0eb884f9 db/doc-workflows-neuter-the-maintainer later to maint). + (merge 8c87bdfb21 jk/cvsimport-quoting later to maint). + (merge 176cb979fe rs/fmt-merge-msg-leakfix later to maint). + (merge 5a03360e73 tb/delimit-pretty-trailers-args-with-comma later to maint). + (merge d0e6326026 ot/pretty later to maint). + (merge 44103f4197 sb/test-helper-excludes later to maint). + (merge 170078693f jt/transport-no-more-rsync later to maint). + (merge c07b3adff1 bw/path-doc later to maint). + (merge bf9d7df950 tz/lib-git-svn-svnserve-tests later to maint). + (merge dec366c9a8 sr/http-sslverify-config-doc later to maint). + (merge 3f824e91c8 jk/test-suite-tracing later to maint). + (merge 1feb061701 db/doc-config-section-names-with-bs later to maint). + (merge 74dea0e13c jh/memihash-opt later to maint). + (merge 2e9fdc795c ma/bisect-leakfix later to maint). diff --git a/Documentation/RelNotes/2.16.1.txt b/Documentation/RelNotes/2.16.1.txt new file mode 100644 index 0000000000..66e64361fd --- /dev/null +++ b/Documentation/RelNotes/2.16.1.txt @@ -0,0 +1,11 @@ +Git v2.16.1 Release Notes +========================= + +Fixes since v2.16 +----------------- + + * "git clone" segfaulted when cloning a project that happens to + track two paths that differ only in case on a case insensitive + filesystem. + +Does not contain any other documentation updates or code clean-ups. diff --git a/Documentation/RelNotes/2.17.0.txt b/Documentation/RelNotes/2.17.0.txt new file mode 100644 index 0000000000..985786add9 --- /dev/null +++ b/Documentation/RelNotes/2.17.0.txt @@ -0,0 +1,19 @@ +Git 2.17 Release Notes +====================== + +Updates since v2.16 +------------------- + +UI, Workflows & Features + + +Performance, Internal Implementation, Development Support etc. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.16 +----------------- + + * Other minor doc, test and build updates and code cleanups. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3ef30922ec..a1d0feca36 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -261,7 +261,7 @@ not a text/plain, it's something else. Send your patch with "To:" set to the mailing list, with "cc:" listing people who are involved in the area you are touching (the output from -+git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to +`git blame $path` and `git shortlog --no-merges $path` would help to identify them), to solicit comments and reviews. :1: footnote:[The current maintainer: gitster@pobox.com] diff --git a/Documentation/config.txt b/Documentation/config.txt index b18c0f97fe..0e25b2c92b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -41,11 +41,13 @@ in the section header, like in the example below: -------- Subsection names are case sensitive and can contain any characters except -newline (doublequote `"` and backslash can be included by escaping them -as `\"` and `\\`, respectively). Section headers cannot span multiple -lines. Variables may belong directly to a section or to a given subsection. -You can have `[section]` if you have `[section "subsection"]`, but you -don't need to. +newline and the null byte. Doublequote `"` and backslash can be included +by escaping them as `\"` and `\\`, respectively. Backslashes preceding +other characters are dropped when reading; for example, `\t` is read as +`t` and `\0` is read as `0` Section headers cannot span multiple lines. +Variables may belong directly to a section or to a given subsection. You +can have `[section]` if you have `[section "subsection"]`, but you don't +need to. There is also a deprecated `[section.subsection]` syntax. With this syntax, the subsection name is converted to lower-case and is also @@ -1968,8 +1970,8 @@ empty string. http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing - over HTTPS. Can be overridden by the `GIT_SSL_NO_VERIFY` environment - variable. + over HTTPS. Defaults to true. Can be overridden by the + `GIT_SSL_NO_VERIFY` environment variable. http.sslCert:: File containing the SSL certificate when fetching or pushing @@ -2736,36 +2738,7 @@ push.recurseSubmodules:: is retained. You may override this configuration at time of push by specifying '--recurse-submodules=check|on-demand|no'. -rebase.stat:: - Whether to show a diffstat of what changed upstream since the last - rebase. False by default. - -rebase.autoSquash:: - If set to true enable `--autosquash` option by default. - -rebase.autoStash:: - When set to true, automatically create a temporary stash entry - before the operation begins, and apply it after the operation - ends. This means that you can run rebase on a dirty worktree. - However, use with care: the final stash application after a - successful rebase might result in non-trivial conflicts. - Defaults to false. - -rebase.missingCommitsCheck:: - If set to "warn", git rebase -i will print a warning if some - commits are removed (e.g. a line was deleted), however the - rebase will still proceed. If set to "error", it will print - the previous warning and stop the rebase, 'git rebase - --edit-todo' can then be used to correct the error. If set to - "ignore", no checking is done. - To drop a commit without warning or error, use the `drop` - command in the todo-list. - Defaults to "ignore". - -rebase.instructionFormat:: - A format string, as specified in linkgit:git-log[1], to be used for - the instruction list during an interactive rebase. The format will automatically - have the long commit hash prepended to the format. +include::rebase-config.txt[] receive.advertiseAtomic:: By default, git-receive-pack will advertise the atomic push diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9d1586b956..c330c01ff0 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -469,6 +469,12 @@ ifndef::git-format-patch[] + Also, these upper-case letters can be downcased to exclude. E.g. `--diff-filter=ad` excludes added and deleted paths. ++ +Note that not all diffs can feature all types. For instance, diffs +from the index to the working tree can never have Added entries +(because the set of paths included in the diff is limited by what is in +the index). Similarly, copied and renamed entries cannot appear if +detection for those types is disabled. -S<string>:: Look for differences that change the number of occurrences of @@ -502,6 +508,15 @@ occurrences of that string did not change). See the 'pickaxe' entry in linkgit:gitdiffcore[7] for more information. +--find-object=<object-id>:: + Look for differences that change the number of occurrences of + the specified object. Similar to `-S`, just the argument is different + in that it doesn't search for a specific string but for a specific + object id. ++ +The object can be a blob or a submodule commit. It implies the `-t` option in +`git-log` to also find trees. + --pickaxe-all:: When `-S` or `-G` finds a change, show all the changes in that changeset, not just the files that contain the change @@ -510,6 +525,7 @@ information. --pickaxe-regex:: Treat the <string> given to `-S` as an extended POSIX regular expression to match. + endif::git-format-patch[] -O<orderfile>:: diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index cf0a0b7df2..d9de992585 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -79,16 +79,21 @@ reference name expressions (see linkgit:gitrevisions[7]): With the `--branch` option, the command takes a name and checks if it can be used as a valid branch name (e.g. when creating a new -branch). The rule `git check-ref-format --branch $name` implements +branch). But be cautious when using the +previous checkout syntax that may refer to a detached HEAD state. +The rule `git check-ref-format --branch $name` implements may be stricter than what `git check-ref-format refs/heads/$name` says (e.g. a dash may appear at the beginning of a ref component, but it is explicitly forbidden at the beginning of a branch name). When run with `--branch` option in a repository, the input is first -expanded for the ``previous branch syntax'' -`@{-n}`. For example, `@{-1}` is a way to refer the last branch you -were on. This option should be used by porcelains to accept this -syntax anywhere a branch name is expected, so they can act as if you -typed the branch name. +expanded for the ``previous checkout syntax'' +`@{-n}`. For example, `@{-1}` is a way to refer the last thing that +was checked out using "git checkout" operation. This option should be +used by porcelains to accept this syntax anywhere a branch name is +expected, so they can act as if you typed the branch name. As an +exception note that, the ``previous checkout operation'' might result +in a commit object name when the N-th last thing checked out was not +a branch. OPTIONS ------- @@ -116,7 +121,7 @@ OPTIONS EXAMPLES -------- -* Print the name of the previous branch: +* Print the name of the previous thing checked out: + ------------ $ git check-ref-format --branch @{-1} diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index c924c945ba..e027fb8c4b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -3,14 +3,14 @@ git-describe(1) NAME ---- -git-describe - Describe a commit using the most recent tag reachable from it - +git-describe - Give an object a human readable name based on an available ref SYNOPSIS -------- [verse] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] +'git describe' <blob> DESCRIPTION ----------- @@ -24,6 +24,12 @@ By default (without --all or --tags) `git describe` only shows annotated tags. For more information about creating annotated tags see the -a and -s options to linkgit:git-tag[1]. +If the given object refers to a blob, it will be described +as `<commit-ish>:<path>`, such that the blob can be found +at `<path>` in the `<commit-ish>`, which itself describes the +first commit in which this blob occurs in a reverse revision walk +from HEAD. + OPTIONS ------- <commit-ish>...:: @@ -186,6 +192,14 @@ selected and output. Here fewest commits different is defined as the number of commits which would be shown by `git log tag..input` will be the smallest number of commits possible. +BUGS +---- + +Tree objects as well as tag objects not pointing at commits, cannot be described. +When describing blobs, the lightweight tags pointing at blobs are ignored, +but the blob is still described as <committ-ish>:<path> despite the lightweight +tag being favorable. + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 7436c64a95..d8c8f11c9f 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -157,6 +157,12 @@ The p4 changes will be created as the user invoking 'git p4 submit'. The according to the author of the Git commit. This option requires admin privileges in p4, which can be granted using 'p4 protect'. +To shelve changes instead of submitting, use `--shelve` and `--update-shelve`: + +---- +$ git p4 submit --shelve +$ git p4 submit --update-shelve 1234 --update-shelve 2345 +---- OPTIONS ------- @@ -310,7 +316,7 @@ These options can be used to modify 'git p4 submit' behavior. --update-shelve CHANGELIST:: Update an existing shelved changelist with this commit. Implies - --shelve. + --shelve. Repeat for multiple shelved changelists. --conflict=(ask|skip|quit):: Conflicts can occur when applying a commit to p4. When this diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index 473a16135a..aa403d02f3 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -12,7 +12,8 @@ SYNOPSIS 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] [--no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental] [--window=<n>] [--depth=<n>] - [--revs [--unpacked | --all]] [--stdout | base-name] + [--revs [--unpacked | --all]] + [--stdout [--filter=<filter-spec>] | base-name] [--shallow] [--keep-true-parents] < object-list @@ -236,6 +237,25 @@ So does `git bundle` (see linkgit:git-bundle[1]) when it creates a bundle. With this option, parents that are hidden by grafts are packed nevertheless. +--filter=<filter-spec>:: + Requires `--stdout`. Omits certain objects (usually blobs) from + the resulting packfile. See linkgit:git-rev-list[1] for valid + `<filter-spec>` forms. + +--no-filter:: + Turns off any previous `--filter=` argument. + +--missing=<missing-action>:: + A debug option to help with future "partial clone" development. + This option specifies how missing objects are handled. ++ +The form '--missing=error' requests that pack-objects stop with an error if +a missing object is encountered. This is the default action. ++ +The form '--missing=allow-any' will allow object traversal to continue +if a missing object is encountered. Missing objects will silently be +omitted from the results. + SEE ALSO -------- linkgit:git-rev-list[1] diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 3cedfb0fd2..8a861c1e0d 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -203,24 +203,7 @@ Alternatively, you can undo the 'git rebase' with CONFIGURATION ------------- -rebase.stat:: - Whether to show a diffstat of what changed upstream since the last - rebase. False by default. - -rebase.autoSquash:: - If set to true enable `--autosquash` option by default. - -rebase.autoStash:: - If set to true enable `--autostash` option by default. - -rebase.missingCommitsCheck:: - If set to "warn", print warnings about removed commits in - interactive mode. If set to "error", print the warnings and - stop the rebase. If set to "ignore", no checking is - done. "ignore" by default. - -rebase.instructionFormat:: - Custom commit list format to use during an `--interactive` rebase. +include::rebase-config.txt[] OPTIONS ------- diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index ef22f1775b..88609ff435 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -47,7 +47,9 @@ SYNOPSIS [ --fixed-strings | -F ] [ --date=<format>] [ [ --objects | --objects-edge | --objects-edge-aggressive ] - [ --unpacked ] ] + [ --unpacked ] + [ --filter=<filter-spec> [ --filter-print-omitted ] ] ] + [ --missing=<missing-action> ] [ --pretty | --header ] [ --bisect ] [ --bisect-vars ] diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 81cab9aefb..72bfb87f66 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -149,14 +149,15 @@ the status.relativePaths config option below. Short Format ~~~~~~~~~~~~ -In the short-format, the status of each path is shown as +In the short-format, the status of each path is shown as one of these +forms - XY PATH1 -> PATH2 + XY PATH + XY ORIG_PATH -> PATH -where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is -shown only when `PATH1` corresponds to a different path in the -index/worktree (i.e. the file is renamed). The `XY` is a two-letter -status code. +where `ORIG_PATH` is where the renamed/copied contents came +from. `ORIG_PATH` is only shown when the entry is renamed or +copied. The `XY` is a two-letter status code. The fields (including the `->`) are separated from each other by a single space. If a filename contains whitespace or other nonprintable @@ -192,6 +193,8 @@ in which case `XY` are `!!`. [MARC] index and work tree matches [ MARC] M work tree changed since index [ MARC] D deleted in work tree + [ D] R renamed in work tree + [ D] C copied in work tree ------------------------------------------------- D D unmerged, both deleted A U unmerged, added by us @@ -309,13 +312,13 @@ Renamed or copied entries have the following format: 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. + is the target path. <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. + <origPath> The pathname in the commit at HEAD or in the index. + 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 diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index f850e8ffb6..41585f535d 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -118,7 +118,7 @@ OPTIONS --[no-]guess-remote:: With `worktree add <path>`, without `<commit-ish>`, instead of creating a new branch from HEAD, if there exists a tracking - branch in exactly one remote matching the basename of `<path>, + branch in exactly one remote matching the basename of `<path>`, base the new branch on the remote-tracking branch, and mark the remote-tracking branch as "upstream" from the new branch. + diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index b63f2ea860..f877f7b7cd 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -170,7 +170,8 @@ This hook cannot affect the outcome of 'git checkout'. It is also run after 'git clone', unless the --no-checkout (-n) option is used. The first parameter given to the hook is the null-ref, the second the -ref of the new HEAD and the flag is always 1. +ref of the new HEAD and the flag is always 1. Likewise for 'git worktree add' +unless --no-checkout is used. This hook can be used to perform repository validity checks, auto-display differences from the previous HEAD if different, or set working dir metadata diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 02569d0614..926e044d09 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -407,8 +407,8 @@ follows. `git pull <url> <branch>` ===================================== -Occasionally, the maintainer may get merge conflicts when he tries to -pull changes from downstream. In this case, he can ask downstream to +Occasionally, the maintainer may get merge conflicts when they try to +pull changes from downstream. In this case, they can ask downstream to do the merge and resolve the conflicts themselves (perhaps they will know better how to resolve them). It is one of the rare cases where downstream 'should' merge from upstream. diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh index 327f69bcf5..17231d8e59 100755 --- a/Documentation/install-doc-quick.sh +++ b/Documentation/install-doc-quick.sh @@ -3,11 +3,12 @@ repository=${1?repository} destdir=${2?destination} +GIT_MAN_REF=${3?master} -head=master GIT_DIR= +GIT_DIR= for d in "$repository/.git" "$repository" do - if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1 + if GIT_DIR="$d" git rev-parse "$GIT_MAN_REF" >/dev/null 2>&1 then GIT_DIR="$d" export GIT_DIR @@ -27,12 +28,12 @@ export GIT_INDEX_FILE GIT_WORK_TREE rm -f "$GIT_INDEX_FILE" trap 'rm -f "$GIT_INDEX_FILE"' 0 -git read-tree $head +git read-tree "$GIT_MAN_REF" git checkout-index -a -f --prefix="$destdir"/ if test -n "$GZ" then - git ls-tree -r --name-only $head | + git ls-tree -r --name-only "$GIT_MAN_REF" | xargs printf "$destdir/%s\n" | xargs gzip -f fi diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index df3ea3779b..12b6bbf591 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -26,6 +26,10 @@ merge.ff:: allowed (equivalent to giving the `--ff-only` option from the command line). +merge.verifySignatures:: + If true, this is equivalent to the --verify-signatures command + line option. See linkgit:git-merge[1] for details. + include::fmt-merge-msg-config.txt[] merge.renameLimit:: diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index d433d50f81..e664c088a5 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -204,11 +204,13 @@ endif::git-rev-list[] than given and there are spaces on its left, use those spaces - '%><(<N>)', '%><|(<N>)': similar to '% <(<N>)', '%<|(<N>)' respectively, but padding both sides (i.e. the text is centered) -- %(trailers): display the trailers of the body as interpreted by - linkgit:git-interpret-trailers[1]. If the `:only` option is given, - omit non-trailer lines from the trailer block. If the `:unfold` - option is given, behave as if interpret-trailer's `--unfold` option - was given. E.g., `%(trailers:only:unfold)` to do both. +- %(trailers[:options]): display the trailers of the body as interpreted + by linkgit:git-interpret-trailers[1]. The `trailers` string may be + followed by a colon and zero or more comma-separated options. If the + `only` option is given, omit non-trailer lines from the trailer block. + If the `unfold` option is given, behave as if interpret-trailer's + `--unfold` option was given. E.g., `%(trailers:only,unfold)` to do + both. NOTE: Some placeholders may depend on other options given to the revision traversal engine. For example, the `%g*` reflog options will diff --git a/Documentation/rebase-config.txt b/Documentation/rebase-config.txt new file mode 100644 index 0000000000..42e1ba7575 --- /dev/null +++ b/Documentation/rebase-config.txt @@ -0,0 +1,52 @@ +rebase.stat:: + Whether to show a diffstat of what changed upstream since the last + rebase. False by default. + +rebase.autoSquash:: + If set to true enable `--autosquash` option by default. + +rebase.autoStash:: + When set to true, automatically create a temporary stash entry + before the operation begins, and apply it after the operation + ends. This means that you can run rebase on a dirty worktree. + However, use with care: the final stash application after a + successful rebase might result in non-trivial conflicts. + This option can be overridden by the `--no-autostash` and + `--autostash` options of linkgit:git-rebase[1]. + Defaults to false. + +rebase.missingCommitsCheck:: + If set to "warn", git rebase -i will print a warning if some + commits are removed (e.g. a line was deleted), however the + rebase will still proceed. If set to "error", it will print + the previous warning and stop the rebase, 'git rebase + --edit-todo' can then be used to correct the error. If set to + "ignore", no checking is done. + To drop a commit without warning or error, use the `drop` + command in the todo list. + Defaults to "ignore". + +rebase.instructionFormat:: + A format string, as specified in linkgit:git-log[1], to be used for the + todo list during an interactive rebase. The format will + automatically have the long commit hash prepended to the format. + +rebase.abbreviateCommands:: + If set to true, `git rebase` will use abbreviated command names in the + todo list resulting in something like this: ++ +------------------------------------------- + p deadbee The oneline of the commit + p fa1afe1 The oneline of the next commit + ... +------------------------------------------- ++ +instead of: ++ +------------------------------------------- + pick deadbee The oneline of the commit + pick fa1afe1 The oneline of the next commit + ... +------------------------------------------- ++ +Defaults to false. diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 13501e1556..22f5c9b43d 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -686,6 +686,11 @@ ifdef::git-rev-list[] all object IDs which I need to download if I have the commit object _bar_ but not _foo_''. +--in-commit-order:: + Print tree and blob ids in order of the commits. The tree + and blob ids are printed after they are first referenced + by a commit. + --objects-edge:: Similar to `--objects`, but also print the IDs of excluded commits prefixed with a ``-'' character. This is used by @@ -706,6 +711,47 @@ ifdef::git-rev-list[] --unpacked:: Only useful with `--objects`; print the object IDs that are not in packs. + +--filter=<filter-spec>:: + Only useful with one of the `--objects*`; omits objects (usually + blobs) from the list of printed objects. The '<filter-spec>' + may be one of the following: ++ +The form '--filter=blob:none' omits all blobs. ++ +The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes +or units. n may be zero. The suffixes k, m, and g can be used to name +units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same +as 'blob:limit=1024'. ++ +The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout +specification contained in the blob (or blob-expression) '<blob-ish>' +to omit blobs that would not be not required for a sparse checkout on +the requested refs. ++ +The form '--filter=sparse:path=<path>' similarly uses a sparse-checkout +specification contained in <path>. + +--no-filter:: + Turn off any previous `--filter=` argument. + +--filter-print-omitted:: + Only useful with `--filter=`; prints a list of the objects omitted + by the filter. Object IDs are prefixed with a ``~'' character. + +--missing=<missing-action>:: + A debug option to help with future "partial clone" development. + This option specifies how missing objects are handled. ++ +The form '--missing=error' requests that rev-list stop with an error if +a missing object is encountered. This is the default action. ++ +The form '--missing=allow-any' will allow object traversal to continue +if a missing object is encountered. Missing objects will silently be +omitted from the results. ++ +The form '--missing=print' is like 'allow-any', but will also print a +list of the missing objects. Object IDs are prefixed with a ``?'' character. endif::git-rev-list[] --no-walk[=(sorted|unsorted)]:: diff --git a/Documentation/technical/api-decorate.txt b/Documentation/technical/api-decorate.txt deleted file mode 100644 index 1d52a6ce14..0000000000 --- a/Documentation/technical/api-decorate.txt +++ /dev/null @@ -1,6 +0,0 @@ -decorate API -============ - -Talk about <decorate.h> - -(Linus) diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt new file mode 100644 index 0000000000..0bed2472c8 --- /dev/null +++ b/Documentation/technical/partial-clone.txt @@ -0,0 +1,324 @@ +Partial Clone Design Notes +========================== + +The "Partial Clone" feature is a performance optimization for Git that +allows Git to function without having a complete copy of the repository. +The goal of this work is to allow Git better handle extremely large +repositories. + +During clone and fetch operations, Git downloads the complete contents +and history of the repository. This includes all commits, trees, and +blobs for the complete life of the repository. For extremely large +repositories, clones can take hours (or days) and consume 100+GiB of disk +space. + +Often in these repositories there are many blobs and trees that the user +does not need such as: + + 1. files outside of the user's work area in the tree. For example, in + a repository with 500K directories and 3.5M files in every commit, + we can avoid downloading many objects if the user only needs a + narrow "cone" of the source tree. + + 2. large binary assets. For example, in a repository where large build + artifacts are checked into the tree, we can avoid downloading all + previous versions of these non-mergeable binary assets and only + download versions that are actually referenced. + +Partial clone allows us to avoid downloading such unneeded objects *in +advance* during clone and fetch operations and thereby reduce download +times and disk usage. Missing objects can later be "demand fetched" +if/when needed. + +Use of partial clone requires that the user be online and the origin +remote be available for on-demand fetching of missing objects. This may +or may not be problematic for the user. For example, if the user can +stay within the pre-selected subset of the source tree, they may not +encounter any missing objects. Alternatively, the user could try to +pre-fetch various objects if they know that they are going offline. + + +Non-Goals +--------- + +Partial clone is a mechanism to limit the number of blobs and trees downloaded +*within* a given range of commits -- and is therefore independent of and not +intended to conflict with existing DAG-level mechanisms to limit the set of +requested commits (i.e. shallow clone, single branch, or fetch '<refspec>'). + + +Design Overview +--------------- + +Partial clone logically consists of the following parts: + +- A mechanism for the client to describe unneeded or unwanted objects to + the server. + +- A mechanism for the server to omit such unwanted objects from packfiles + sent to the client. + +- A mechanism for the client to gracefully handle missing objects (that + were previously omitted by the server). + +- A mechanism for the client to backfill missing objects as needed. + + +Design Details +-------------- + +- A new pack-protocol capability "filter" is added to the fetch-pack and + upload-pack negotiation. + + This uses the existing capability discovery mechanism. + See "filter" in Documentation/technical/pack-protocol.txt. + +- Clients pass a "filter-spec" to clone and fetch which is passed to the + server to request filtering during packfile construction. + + There are various filters available to accommodate different situations. + See "--filter=<filter-spec>" in Documentation/rev-list-options.txt. + +- On the server pack-objects applies the requested filter-spec as it + creates "filtered" packfiles for the client. + + These filtered packfiles are *incomplete* in the traditional sense because + they may contain objects that reference objects not contained in the + packfile and that the client doesn't already have. For example, the + filtered packfile may contain trees or tags that reference missing blobs + or commits that reference missing trees. + +- On the client these incomplete packfiles are marked as "promisor packfiles" + and treated differently by various commands. + +- On the client a repository extension is added to the local config to + prevent older versions of git from failing mid-operation because of + missing objects that they cannot handle. + See "extensions.partialClone" in Documentation/technical/repository-version.txt" + + +Handling Missing Objects +------------------------ + +- An object may be missing due to a partial clone or fetch, or missing due + to repository corruption. To differentiate these cases, the local + repository specially indicates such filtered packfiles obtained from the + promisor remote as "promisor packfiles". + + These promisor packfiles consist of a "<name>.promisor" file with + arbitrary contents (like the "<name>.keep" files), in addition to + their "<name>.pack" and "<name>.idx" files. + +- The local repository considers a "promisor object" to be an object that + it knows (to the best of its ability) that the promisor remote has promised + that it has, either because the local repository has that object in one of + its promisor packfiles, or because another promisor object refers to it. + + When Git encounters a missing object, Git can see if it a promisor object + and handle it appropriately. If not, Git can report a corruption. + + This means that there is no need for the client to explicitly maintain an + expensive-to-modify list of missing objects.[a] + +- Since almost all Git code currently expects any referenced object to be + present locally and because we do not want to force every command to do + a dry-run first, a fallback mechanism is added to allow Git to attempt + to dynamically fetch missing objects from the promisor remote. + + When the normal object lookup fails to find an object, Git invokes + fetch-object to try to get the object from the server and then retry + the object lookup. This allows objects to be "faulted in" without + complicated prediction algorithms. + + For efficiency reasons, no check as to whether the missing object is + actually a promisor object is performed. + + Dynamic object fetching tends to be slow as objects are fetched one at + a time. + +- `checkout` (and any other command using `unpack-trees`) has been taught + to bulk pre-fetch all required missing blobs in a single batch. + +- `rev-list` has been taught to print missing objects. + + This can be used by other commands to bulk prefetch objects. + For example, a "git log -p A..B" may internally want to first do + something like "git rev-list --objects --quiet --missing=print A..B" + and prefetch those objects in bulk. + +- `fsck` has been updated to be fully aware of promisor objects. + +- `repack` in GC has been updated to not touch promisor packfiles at all, + and to only repack other objects. + +- The global variable "fetch_if_missing" is used to control whether an + object lookup will attempt to dynamically fetch a missing object or + report an error. + + We are not happy with this global variable and would like to remove it, + but that requires significant refactoring of the object code to pass an + additional flag. We hope that concurrent efforts to add an ODB API can + encompass this. + + +Fetching Missing Objects +------------------------ + +- Fetching of objects is done using the existing transport mechanism using + transport_fetch_refs(), setting a new transport option + TRANS_OPT_NO_DEPENDENTS to indicate that only the objects themselves are + desired, not any object that they refer to. + + Because some transports invoke fetch_pack() in the same process, fetch_pack() + has been updated to not use any object flags when the corresponding argument + (no_dependents) is set. + +- The local repository sends a request with the hashes of all requested + objects as "want" lines, and does not perform any packfile negotiation. + It then receives a packfile. + +- Because we are reusing the existing fetch-pack mechanism, fetching + currently fetches all objects referred to by the requested objects, even + though they are not necessary. + + +Current Limitations +------------------- + +- The remote used for a partial clone (or the first partial fetch + following a regular clone) is marked as the "promisor remote". + + We are currently limited to a single promisor remote and only that + remote may be used for subsequent partial fetches. + + We accept this limitation because we believe initial users of this + feature will be using it on repositories with a strong single central + server. + +- Dynamic object fetching will only ask the promisor remote for missing + objects. We assume that the promisor remote has a complete view of the + repository and can satisfy all such requests. + +- Repack essentially treats promisor and non-promisor packfiles as 2 + distinct partitions and does not mix them. Repack currently only works + on non-promisor packfiles and loose objects. + +- Dynamic object fetching invokes fetch-pack once *for each item* + because most algorithms stumble upon a missing object and need to have + it resolved before continuing their work. This may incur significant + overhead -- and multiple authentication requests -- if many objects are + needed. + +- Dynamic object fetching currently uses the existing pack protocol V0 + which means that each object is requested via fetch-pack. The server + will send a full set of info/refs when the connection is established. + If there are large number of refs, this may incur significant overhead. + + +Future Work +----------- + +- Allow more than one promisor remote and define a strategy for fetching + missing objects from specific promisor remotes or of iterating over the + set of promisor remotes until a missing object is found. + + A user might want to have multiple geographically-close cache servers + for fetching missing blobs while continuing to do filtered `git-fetch` + commands from the central server, for example. + + Or the user might want to work in a triangular work flow with multiple + promisor remotes that each have an incomplete view of the repository. + +- Allow repack to work on promisor packfiles (while keeping them distinct + from non-promisor packfiles). + +- Allow non-pathname-based filters to make use of packfile bitmaps (when + present). This was just an omission during the initial implementation. + +- Investigate use of a long-running process to dynamically fetch a series + of objects, such as proposed in [5,6] to reduce process startup and + overhead costs. + + It would be nice if pack protocol V2 could allow that long-running + process to make a series of requests over a single long-running + connection. + +- Investigate pack protocol V2 to avoid the info/refs broadcast on + each connection with the server to dynamically fetch missing objects. + +- Investigate the need to handle loose promisor objects. + + Objects in promisor packfiles are allowed to reference missing objects + that can be dynamically fetched from the server. An assumption was + made that loose objects are only created locally and therefore should + not reference a missing object. We may need to revisit that assumption + if, for example, we dynamically fetch a missing tree and store it as a + loose object rather than a single object packfile. + + This does not necessarily mean we need to mark loose objects as promisor; + it may be sufficient to relax the object lookup or is-promisor functions. + + +Non-Tasks +--------- + +- Every time the subject of "demand loading blobs" comes up it seems + that someone suggests that the server be allowed to "guess" and send + additional objects that may be related to the requested objects. + + No work has gone into actually doing that; we're just documenting that + it is a common suggestion. We're not sure how it would work and have + no plans to work on it. + + It is valid for the server to send more objects than requested (even + for a dynamic object fetch), but we are not building on that. + + +Footnotes +--------- + +[a] expensive-to-modify list of missing objects: Earlier in the design of + partial clone we discussed the need for a single list of missing objects. + This would essentially be a sorted linear list of OIDs that the were + omitted by the server during a clone or subsequent fetches. + + This file would need to be loaded into memory on every object lookup. + It would need to be read, updated, and re-written (like the .git/index) + on every explicit "git fetch" command *and* on any dynamic object fetch. + + The cost to read, update, and write this file could add significant + overhead to every command if there are many missing objects. For example, + if there are 100M missing blobs, this file would be at least 2GiB on disk. + + With the "promisor" concept, we *infer* a missing object based upon the + type of packfile that references it. + + +Related Links +------------- +[0] https://bugs.chromium.org/p/git/issues/detail?id=2 + Chromium work item for: Partial Clone + +[1] https://public-inbox.org/git/20170113155253.1644-1-benpeart@microsoft.com/ + Subject: [RFC] Add support for downloading blobs on demand + Date: Fri, 13 Jan 2017 10:52:53 -0500 + +[2] https://public-inbox.org/git/cover.1506714999.git.jonathantanmy@google.com/ + Subject: [PATCH 00/18] Partial clone (from clone to lazy fetch in 18 patches) + Date: Fri, 29 Sep 2017 13:11:36 -0700 + +[3] https://public-inbox.org/git/20170426221346.25337-1-jonathantanmy@google.com/ + Subject: Proposal for missing blob support in Git repos + Date: Wed, 26 Apr 2017 15:13:46 -0700 + +[4] https://public-inbox.org/git/1488999039-37631-1-git-send-email-git@jeffhostetler.com/ + Subject: [PATCH 00/10] RFC Partial Clone and Fetch + Date: Wed, 8 Mar 2017 18:50:29 +0000 + +[5] https://public-inbox.org/git/20170505152802.6724-1-benpeart@microsoft.com/ + Subject: [PATCH v7 00/10] refactor the filter process code into a reusable module + Date: Fri, 5 May 2017 11:27:52 -0400 + +[6] https://public-inbox.org/git/20170714132651.170708-1-benpeart@microsoft.com/ + Subject: [RFC/PATCH v2 0/1] Add support for downloading blobs on demand + Date: Fri, 14 Jul 2017 09:26:50 -0400 |