diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.19.0.txt | 187 | ||||
| -rw-r--r-- | Documentation/config.txt | 71 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 36 | ||||
| -rw-r--r-- | Documentation/fetch-options.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-checkout.txt | 9 | ||||
| -rw-r--r-- | Documentation/git-commit-graph.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-for-each-ref.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-fsck.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-gc.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-grep.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-interpret-trailers.txt | 9 | ||||
| -rw-r--r-- | Documentation/git-merge.txt | 16 | ||||
| -rw-r--r-- | Documentation/git-rebase.txt | 142 | ||||
| -rw-r--r-- | Documentation/git-send-email.txt | 17 | ||||
| -rw-r--r-- | Documentation/git-tag.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-worktree.txt | 9 | ||||
| -rw-r--r-- | Documentation/revisions.txt | 3 | ||||
| -rw-r--r-- | Documentation/technical/commit-graph.txt | 22 | ||||
| -rw-r--r-- | Documentation/technical/directory-rename-detection.txt | 115 | ||||
| -rw-r--r-- | Documentation/technical/pack-protocol.txt | 7 | ||||
| -rw-r--r-- | Documentation/technical/protocol-v2.txt | 28 |
21 files changed, 639 insertions, 80 deletions
diff --git a/Documentation/RelNotes/2.19.0.txt b/Documentation/RelNotes/2.19.0.txt index f2e261abf3..8a0361321f 100644 --- a/Documentation/RelNotes/2.19.0.txt +++ b/Documentation/RelNotes/2.19.0.txt @@ -24,6 +24,32 @@ UI, Workflows & Features is used as a short-hand for "--create-reflog" and warns about the future repurposing of the it when it is used. + * The userdiff pattern for .php has been updated. + + * The content-transfer-encoding of the message "git send-email" sends + out by default was 8bit, which can cause trouble when there is an + overlong line to bust RFC 5322/2822 limit. A new option 'auto' to + automatically switch to quoted-printable when there is such a line + in the payload has been introduced and is made the default. + + * "git checkout" and "git worktree add" learned to honor + checkout.defaultRemote when auto-vivifying a local branch out of a + remote tracking branch in a repository with multiple remotes that + have tracking branches that share the same names. + (merge 8d7b558bae ab/checkout-default-remote later to maint). + + * "git grep" learned the "--only-matching" option. + + * "git rebase --rebase-merges" mode now handles octopus merges as + well. + + * Add a server-side knob to skip commits in exponential/fibbonacci + stride in an attempt to cover wider swath of history with a smaller + number of iterations, potentially accepting a larger packfile + transfer, instead of going back one commit a time during common + ancestor discovery during the "git fetch" transaction. + (merge 42cc7485a2 jt/fetch-negotiator-skipping later to maint). + Performance, Internal Implementation, Development Support etc. @@ -72,6 +98,65 @@ Performance, Internal Implementation, Development Support etc. file, even though it shares the same syntax with configuration files, to read random configuration items from it. + * "git fast-import" has been updated to avoid attempting to create + delta against a zero-byte-long string, which is pointless. + + * The codebase has been updated to compile cleanly with -pedantic + option. + (merge 2b647a05d7 bb/pedantic later to maint). + + * The character display width table has been updated to match the + latest Unicode standard. + (merge 570951eea2 bb/unicode-11-width later to maint). + + * test-lint now looks for broken use of "VAR=VAL shell_func" in test + scripts. + + * Conversion from uchar[40] to struct object_id continues. + + * Recent "security fix" to pay attention to contents of ".gitmodules" + while accepting "git push" was a bit overly strict than necessary, + which has been adjusted. + + * "git fsck" learns to make sure the optional commit-graph file is in + a sane state. + + * "git diff --color-moved" feature has further been tweaked. + + * Code restructuring and a small fix to transport protocol v2 during + fetching. + + * Parsing of -L[<N>][,[<M>]] parameters "git blame" and "git log" + take has been tweaked. + + * lookup_commit_reference() and friends have been updated to find + in-core object for a specific in-core repository instance. + + * Various glitches in the heuristics of merge-recursive strategy have + been documented in new tests. + + * "git fetch" learned a new option "--negotiation-tip" to limit the + set of commits it tells the other end as "have", to reduce wasted + bandwidth and cycles, which would be helpful when the receiving + repository has a lot of refs that have little to do with the + history at the remote it is fetching from. + + * For a large tree, the index needs to hold many cache entries + allocated on heap. These cache entries are now allocated out of a + dedicated memory pool to amortize malloc(3) overhead. + + * Tests to cover various conflicting cases have been added for + merge-recursive. + + * Tests to cover conflict cases that involve submodules have been + added for merge-recursive. + + * Look for broken "&&" chains that are hidden in subshell, many of + which have been found and corrected. + + * The singleton commit-graph in-core instance is made per in-core + repository instance. + Fixes since v2.18 ----------------- @@ -145,6 +230,105 @@ Fixes since v2.18 not turn a case-incapable filesystem into a case-capable one. (merge 48294b512a ms/core-icase-doc later to maint). + * "fsck.skipList" did not prevent a blob object listed there from + being inspected for is contents (e.g. we recently started to + inspect the contents of ".gitmodules" for certain malicious + patterns), which has been corrected. + (merge fb16287719 rj/submodule-fsck-skip later to maint). + + * "git checkout --recurse-submodules another-branch" did not report + in which submodule it failed to update the working tree, which + resulted in an unhelpful error message. + (merge ba95d4e4bd sb/submodule-move-head-error-msg later to maint). + + * "git rebase" behaved slightly differently depending on which one of + the three backends gets used; this has been documented and an + effort to make them more uniform has begun. + (merge b00bf1c9a8 en/rebase-consistency later to maint). + + * The "--ignore-case" option of "git for-each-ref" (and its friends) + did not work correctly, which has been fixed. + (merge e674eb2528 jk/for-each-ref-icase later to maint). + + * "git fetch" failed to correctly validate the set of objects it + received when making a shallow history deeper, which has been + corrected. + (merge cf1e7c0770 jt/connectivity-check-after-unshallow later to maint). + + * Partial clone support of "git clone" has been updated to correctly + validate the objects it receives from the other side. The server + side has been corrected to send objects that are directly + requested, even if they may match the filtering criteria (e.g. when + doing a "lazy blob" partial clone). + (merge a7e67c11b8 jt/partial-clone-fsck-connectivity later to maint). + + * Handling of an empty range by "git cherry-pick" was inconsistent + depending on how the range ended up to be empty, which has been + corrected. + (merge c5e358d073 jk/empty-pick-fix later to maint). + + * "git reset --merge" (hence "git merge ---abort") and "git reset --hard" + had trouble working correctly in a sparsely checked out working + tree after a conflict, which has been corrected. + (merge b33fdfc34c mk/merge-in-sparse-checkout later to maint). + + * Correct a broken use of "VAR=VAL shell_func" in a test. + (merge 650161a277 jc/t3404-one-shot-export-fix later to maint). + + * "git rev-parse ':/substring'" did not consider the history leading + only to HEAD when looking for a commit with the given substring, + when the HEAD is detached. This has been fixed. + (merge 6b3351e799 wc/find-commit-with-pattern-on-detached-head later to maint). + + * Build doc update for Windows. + (merge ede8d89bb1 nd/command-list later to maint). + + * core.commentchar is now honored when preparing the list of commits + to replay in "rebase -i". + + * "git pull --rebase" on a corrupt HEAD caused a segfault. In + general we substitute an empty tree object when running the in-core + equivalent of the diff-index command, and the codepath has been + corrected to do so as well to fix this issue. + (merge 3506dc9445 jk/has-uncommitted-changes-fix later to maint). + + * httpd tests saw occasional breakage due to the way its access log + gets inspected by the tests, which has been updated to make them + less flaky. + (merge e8b3b2e275 sg/httpd-test-unflake later to maint). + + * Tests to cover more D/F conflict cases have been added for + merge-recursive. + + * "git gc --auto" opens file descriptors for the packfiles before + spawning "git repack/prune", which would upset Windows that does + not want a process to work on a file that is open by another + process. The issue has been worked around. + (merge 12e73a3ce4 kg/gc-auto-windows-workaround later to maint). + + * The recursive merge strategy did not properly ensure there was no + change between HEAD and the index before performing its operation, + which has been corrected. + (merge 55f39cf755 en/dirty-merge-fixes later to maint). + + * "git rebase" started exporting GIT_DIR environment variable and + exposing it to hook scripts when part of it got rewritten in C. + Instead of matching the old scripted Porcelains' behaviour, + compensate by also exporting GIT_WORK_TREE environment as well to + lessen the damage. This can harm existing hooks that want to + operate on different repository, but the current behaviour is + already broken for them anyway. + (merge ab5e67d751 bc/sequencer-export-work-tree-as-well later to maint). + + * "git send-email" when using in a batched mode that limits the + number of messages sent in a single SMTP session lost the contents + of the variable used to choose between tls/ssl, unable to send the + second and later batches, which has been fixed. + (merge 636f3d7ac5 jm/send-email-tls-auth-on-batch later to maint). + + * The lazy clone support had a few places where missing but promised + objects were not correctly tolerated, which have been fixed. + * Code cleanup, docfix, build fix, etc. (merge aee9be2ebe sg/update-ref-stdin-cleanup later to maint). (merge 037714252f jc/clean-after-sanity-tests later to maint). @@ -157,3 +341,6 @@ Fixes since v2.18 (merge 51d1863168 tz/exclude-doc-smallfixes later to maint). (merge a9aa3c0927 ds/commit-graph later to maint). (merge 5cf8e06474 js/enhanced-version-info later to maint). + (merge 6aaded5509 tb/config-default later to maint). + (merge 022d2ac1f3 sb/blame-color later to maint). + (merge 5a06a20e0c bp/test-drop-caches-for-windows later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index a32172a43c..fd8d27e761 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -344,6 +344,16 @@ advice.*:: Advice shown when you used linkgit:git-checkout[1] to move to the detach HEAD state, to instruct how to create a local branch after the fact. + checkoutAmbiguousRemoteBranchName:: + Advice shown when the argument to + linkgit:git-checkout[1] ambiguously resolves to a + remote tracking branch on more than one remote in + situations where an unambiguous argument would have + otherwise caused a remote-tracking branch to be + checked out. See the `checkout.defaultRemote` + configuration variable for how to set a given remote + to used by default in some situations where this + advice would be printed. amWorkDir:: Advice that shows the location of the patch file when linkgit:git-am[1] fails to apply it. @@ -907,9 +917,17 @@ core.notesRef:: This setting defaults to "refs/notes/commits", and it can be overridden by the `GIT_NOTES_REF` environment variable. See linkgit:git-notes[1]. -core.commitGraph:: - Enable git commit graph feature. Allows reading from the - commit-graph file. +gc.commitGraph:: + If true, then gc will rewrite the commit-graph file when + linkgit:git-gc[1] is run. When using linkgit:git-gc[1] + '--auto' the commit-graph will be updated if housekeeping is + required. Default is false. See linkgit:git-commit-graph[1] + for details. + +core.useReplaceRefs:: + If set to `false`, behave as if the `--no-replace-objects` + option was given on the command line. See linkgit:git[1] and + linkgit:git-replace[1] for more information. core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in @@ -1101,6 +1119,22 @@ browser.<tool>.path:: browse HTML help (see `-w` option in linkgit:git-help[1]) or a working repository in gitweb (see linkgit:git-instaweb[1]). +checkout.defaultRemote:: + When you run 'git checkout <something>' and only have one + remote, it may implicitly fall back on checking out and + tracking e.g. 'origin/<something>'. This stops working as soon + as you have more than one remote with a '<something>' + reference. This setting allows for setting the name of a + preferred remote that should always win when it comes to + disambiguation. The typical use-case is to set this to + `origin`. ++ +Currently this is used by linkgit:git-checkout[1] when 'git checkout +<something>' will checkout the '<something>' branch on another remote, +and by linkgit:git-worktree[1] when 'git worktree add' refers to a +remote branch. This setting might be used for other checkout-like +commands or functionality in the future. + clean.requireForce:: A boolean to make git-clean do nothing unless given -f, -i or -n. Defaults to true. @@ -1149,6 +1183,11 @@ diff.colorMoved:: true the default color mode will be used. When set to false, moved lines are not colored. +diff.colorMovedWS:: + When moved lines are colored using e.g. the `diff.colorMoved` setting, + this option controls the `<mode>` how spaces are treated + for details of valid modes see '--color-moved-ws' in linkgit:git-diff[1]. + color.diff.<slot>:: Use customized color for diff colorization. `<slot>` specifies which part of the patch to use the specified color, and is one @@ -1497,6 +1536,15 @@ fetch.output:: `full` and `compact`. Default value is `full`. See section OUTPUT in linkgit:git-fetch[1] for detail. +fetch.negotiationAlgorithm:: + Control how information about the commits in the local repository is + sent when negotiating the contents of the packfile to be sent by the + server. Set to "skipping" to use an algorithm that skips commits in an + effort to converge faster, but may result in a larger-than-necessary + packfile; any other value instructs Git to use the default algorithm + that never skips commits (unless the server has acknowledged it or one + of its descendants). + format.attach:: Enable multipart/mixed attachments as the default for 'format-patch'. The value can also be a double quoted string @@ -1836,6 +1884,16 @@ gpg.program:: signed, and the program is expected to send the result to its standard output. +gpg.format:: + Specifies which key format to use when signing with `--gpg-sign`. + Default is "openpgp" and another possible value is "x509". + +gpg.<format>.program:: + Use this to customize the program used for the signing format you + chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still + be used as a legacy synonym for `gpg.openpgp.program`. The default + value for `gpg.x509.program` is "gpgsm". + gui.commitMsgWidth:: Defines how wide the commit message window is in the linkgit:git-gui[1]. "75" is the default. @@ -3489,6 +3547,13 @@ Note that this configuration variable is ignored if it is seen in the repository-level config (this is a safety measure against fetching from untrusted repositories). +uploadpack.allowRefInWant:: + If this option is set, `upload-pack` will support the `ref-in-want` + feature of the protocol version 2 `fetch` command. This feature + is intended for the benefit of load-balanced servers which may + not have the same view of what OIDs their refs point to due to + replication delay. + url.<base>.insteadOf:: Any URL that starts with this value will be rewritten to start, instead, with <base>. In cases where some site serves a diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 41064909ee..0378cd574e 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -276,16 +276,46 @@ plain:: that are added somewhere else in the diff. This mode picks up any moved line, but it is not very useful in a review to determine if a block of code was moved without permutation. -zebra:: +blocks:: Blocks of moved text of at least 20 alphanumeric characters are detected greedily. The detected blocks are - painted using either the 'color.diff.{old,new}Moved' color or + painted using either the 'color.diff.{old,new}Moved' color. + Adjacent blocks cannot be told apart. +zebra:: + Blocks of moved text are detected as in 'blocks' mode. The blocks + are painted using either the 'color.diff.{old,new}Moved' color or 'color.diff.{old,new}MovedAlternative'. The change between the two colors indicates that a new block was detected. -dimmed_zebra:: +dimmed-zebra:: Similar to 'zebra', but additional dimming of uninteresting parts of moved code is performed. The bordering lines of two adjacent blocks are considered interesting, the rest is uninteresting. + `dimmed_zebra` is a deprecated synonym. +-- + +--color-moved-ws=<modes>:: + This configures how white spaces are ignored when performing the + move detection for `--color-moved`. +ifdef::git-diff[] + It can be set by the `diff.colorMovedWS` configuration setting. +endif::git-diff[] + These modes can be given as a comma separated list: ++ +-- +ignore-space-at-eol:: + Ignore changes in whitespace at EOL. +ignore-space-change:: + Ignore changes in amount of whitespace. This ignores whitespace + at line end, and considers all other sequences of one or + more whitespace characters to be equivalent. +ignore-all-space:: + Ignore whitespace when comparing lines. This ignores differences + even if one line has whitespace where the other line has none. +allow-indentation-change:: + Initially ignore any white spaces in the move detection, then + group the moved code blocks only into a block if the change in + whitespace is the same per line. This is incompatible with the + other modes. -- --word-diff[=<mode>]:: diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 97d3217df9..2d09f87b4b 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -42,6 +42,22 @@ the current repository has the same history as the source repository. .git/shallow. This option updates .git/shallow and accept such refs. +--negotiation-tip=<commit|glob>:: + By default, Git will report, to the server, commits reachable + from all local refs to find common commits in an attempt to + reduce the size of the to-be-received packfile. If specified, + Git will only report commits reachable from the given tips. + This is useful to speed up fetches when the user knows which + local ref is likely to have commits in common with the + upstream ref being fetched. ++ +This option may be specified more than once; if so, Git will report +commits reachable from any of the given commits. ++ +The argument to this option may be a glob on ref names, a ref, or the (possibly +abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying +this option multiple times, one for each matching ref name. + ifndef::git-pull[] --dry-run:: Show what would be done, without making any changes. diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index ca5fc9c798..9db02928c4 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -38,6 +38,15 @@ equivalent to $ git checkout -b <branch> --track <remote>/<branch> ------------ + +If the branch exists in multiple remotes and one of them is named by +the `checkout.defaultRemote` configuration variable, we'll use that +one for the purposes of disambiguation, even if the `<branch>` isn't +unique across all remotes. Set it to +e.g. `checkout.defaultRemote=origin` to always checkout remote +branches from there if `<branch>` is ambiguous but exists on the +'origin' remote. See also `checkout.defaultRemote` in +linkgit:git-config[1]. ++ You could omit <branch>, in which case the command degenerates to "check out the current branch", which is a glorified no-op with rather expensive side-effects to show only the tracking information, diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index 4c97b555cc..dececb79d7 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -10,6 +10,7 @@ SYNOPSIS -------- [verse] 'git commit-graph read' [--object-dir <dir>] +'git commit-graph verify' [--object-dir <dir>] 'git commit-graph write' <options> [--object-dir <dir>] @@ -37,12 +38,16 @@ Write a commit graph file based on the commits found in packfiles. + With the `--stdin-packs` option, generate the new commit graph by walking objects only in the specified pack-indexes. (Cannot be combined -with --stdin-commits.) +with `--stdin-commits` or `--reachable`.) + With the `--stdin-commits` option, generate the new commit graph by walking commits starting at the commits specified in stdin as a list of OIDs in hex, one OID per line. (Cannot be combined with ---stdin-packs.) +`--stdin-packs` or `--reachable`.) ++ +With the `--reachable` option, generate the new commit graph by walking +commits starting at all refs. (Cannot be combined with `--stdin-commits` +or `--stdin-packs`.) + With the `--append` option, include all commits that are present in the existing commit-graph file. @@ -52,6 +57,11 @@ existing commit-graph file. Read a graph file given by the commit-graph file and output basic details about the graph file. Used for debugging purposes. +'verify':: + +Read the commit-graph file and verify its contents against the object +database. Used to check for corrupted data. + EXAMPLES -------- diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 085d177d97..901faef1bf 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -57,7 +57,7 @@ OPTIONS `xx`; for example `%00` interpolates to `\0` (NUL), `%09` to `\t` (TAB) and `%0a` to `\n` (LF). ---color[=<when>]: +--color[=<when>]:: Respect any colors specified in the `--format` option. The `<when>` field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index b9f060e3b2..ab9a93fb9b 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -110,6 +110,9 @@ Any corrupt objects you will have to find in backups or other archives (i.e., you can just remove them and do an 'rsync' with some other site in the hopes that somebody else has the object you have corrupted). +If core.commitGraph is true, the commit-graph file will also be inspected +using 'git commit-graph verify'. See linkgit:git-commit-graph[1]. + Extracted Diagnostics --------------------- diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 24b2dd44fe..f5bc98ccb3 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -136,6 +136,10 @@ The optional configuration variable `gc.packRefs` determines if it within all non-bare repos or it can be set to a boolean value. This defaults to true. +The optional configuration variable `gc.commitGraph` determines if +'git gc' should run 'git commit-graph write'. This can be set to a +boolean value. This defaults to false. + The optional configuration variable `gc.aggressiveWindow` controls how much time is spent optimizing the delta compression of the objects in the repository when the --aggressive option is specified. The larger diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 0de3493b80..a3049af1a3 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -17,7 +17,7 @@ SYNOPSIS [-l | --files-with-matches] [-L | --files-without-match] [(-O | --open-files-in-pager) [<pager>]] [-z | --null] - [-c | --count] [--all-match] [-q | --quiet] + [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet] [--max-depth <depth>] [--color[=<when>] | --no-color] [--break] [--heading] [-p | --show-function] @@ -201,6 +201,11 @@ providing this option will cause it to die. Output \0 instead of the character that normally follows a file name. +-o:: +--only-matching:: + Print only the matched (non-empty) parts of a matching line, with each such + part on a separate output line. + -c:: --count:: Instead of showing every matched line, show the number of diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt index 9111c47a1b..b8fafb1e8b 100644 --- a/Documentation/git-interpret-trailers.txt +++ b/Documentation/git-interpret-trailers.txt @@ -88,7 +88,8 @@ OPTIONS Specify where all new trailers will be added. A setting provided with '--where' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of - '--where' or '--no-where'. + '--where' or '--no-where'. Possible values are `after`, `before`, + `end` or `start`. --if-exists <action>:: --no-if-exists:: @@ -96,7 +97,8 @@ OPTIONS least one trailer with the same <token> in the message. A setting provided with '--if-exists' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-exists' or '--no-if-exists'. + '--if-exists' or '--no-if-exists'. Possible actions are `addIfDifferent`, + `addIfDifferentNeighbor`, `add`, `replace` and `doNothing`. --if-missing <action>:: --no-if-missing:: @@ -104,7 +106,8 @@ OPTIONS trailer with the same <token> in the message. A setting provided with '--if-missing' overrides all configuration variables and applies to all '--trailer' options until the next occurrence of - '--if-missing' or '--no-if-missing'. + '--if-missing' or '--no-if-missing'. Possible actions are `doNothing` + or `add`. --only-trailers:: Output only the trailers, not any other parts of the input. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 6a5c00e2c2..eb36837f86 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]] [--[no-]allow-unrelated-histories] - [--[no-]rerere-autoupdate] [-m <msg>] [<commit>...] + [--[no-]rerere-autoupdate] [-m <msg>] [-F <file>] [<commit>...] 'git merge' --abort 'git merge' --continue @@ -75,6 +75,14 @@ The 'git fmt-merge-msg' command can be used to give a good default for automated 'git merge' invocations. The automated message can include the branch description. +-F <file>:: +--file=<file>:: + Read the commit message to be used for the merge commit (in + case one is created). ++ +If `--log` is specified, a shortlog of the commits being merged +will be appended to the specified message. + --[no-]rerere-autoupdate:: Allow the rerere mechanism to update the index with the result of auto-conflict resolution if possible. @@ -122,9 +130,9 @@ merge' may need to update. To avoid recording unrelated changes in the merge commit, 'git pull' and 'git merge' will also abort if there are any changes -registered in the index relative to the `HEAD` commit. (One -exception is when the changed index entries are in the state that -would result from the merge already.) +registered in the index relative to the `HEAD` commit. (Special +narrow exceptions to this rule may exist depending on which merge +strategy is in use, but generally, the index must match HEAD.) If all named commits are already ancestors of `HEAD`, 'git merge' will exit early with the message "Already up to date." diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 091eb53faa..1fbc6ebcde 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -243,11 +243,15 @@ leave out at most one of A and B, in which case it defaults to HEAD. --keep-empty:: Keep the commits that do not change anything from its parents in the result. ++ +See also INCOMPATIBLE OPTIONS below. --allow-empty-message:: By default, rebasing commits with an empty message will fail. This option overrides that behavior, allowing commits with empty messages to be rebased. ++ +See also INCOMPATIBLE OPTIONS below. --skip:: Restart the rebasing process by skipping the current patch. @@ -271,6 +275,8 @@ branch on top of the <upstream> branch. Because of this, when a merge conflict happens, the side reported as 'ours' is the so-far rebased series, starting with <upstream>, and 'theirs' is the working branch. In other words, the sides are swapped. ++ +See also INCOMPATIBLE OPTIONS below. -s <strategy>:: --strategy=<strategy>:: @@ -280,8 +286,10 @@ other words, the sides are swapped. + Because 'git rebase' replays each commit from the working branch on top of the <upstream> branch using the given strategy, using -the 'ours' strategy simply discards all patches from the <branch>, +the 'ours' strategy simply empties all patches from the <branch>, which makes little sense. ++ +See also INCOMPATIBLE OPTIONS below. -X <strategy-option>:: --strategy-option=<strategy-option>:: @@ -289,6 +297,8 @@ which makes little sense. This implies `--merge` and, if no strategy has been specified, `-s recursive`. Note the reversal of 'ours' and 'theirs' as noted above for the `-m` option. ++ +See also INCOMPATIBLE OPTIONS below. -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -324,17 +334,21 @@ which makes little sense. and after each change. When fewer lines of surrounding context exist they all must match. By default no context is ever ignored. ++ +See also INCOMPATIBLE OPTIONS below. --f:: +--no-ff:: --force-rebase:: - Force a rebase even if the current branch is up to date and - the command without `--force` would return without doing anything. +-f:: + Individually replay all rebased commits instead of fast-forwarding + over the unchanged ones. This ensures that the entire history of + the rebased branch is composed of new commits. + -You may find this (or --no-ff with an interactive rebase) helpful after -reverting a topic branch merge, as this option recreates the topic branch with -fresh commits so it can be remerged successfully without needing to "revert -the reversion" (see the -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). +You may find this helpful after reverting a topic branch merge, as this option +recreates the topic branch with fresh commits so it can be remerged +successfully without needing to "revert the reversion" (see the +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for +details). --fork-point:: --no-fork-point:: @@ -355,19 +369,22 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. --whitespace=<option>:: These flag are passed to the 'git apply' program (see linkgit:git-apply[1]) that applies the patch. - Incompatible with the --interactive option. ++ +See also INCOMPATIBLE OPTIONS below. --committer-date-is-author-date:: --ignore-date:: These flags are passed to 'git am' to easily change the dates of the rebased commits (see linkgit:git-am[1]). - Incompatible with the --interactive option. ++ +See also INCOMPATIBLE OPTIONS below. --signoff:: Add a Signed-off-by: trailer to all the rebased commits. Note that if `--interactive` is given then only commits marked to be - picked, edited or reworded will have the trailer added. Incompatible - with the `--preserve-merges` option. + picked, edited or reworded will have the trailer added. ++ +See also INCOMPATIBLE OPTIONS below. -i:: --interactive:: @@ -378,6 +395,8 @@ default is `--no-fork-point`, otherwise the default is `--fork-point`. The commit list format can be changed by setting the configuration option rebase.instructionFormat. A customized instruction format will automatically have the long commit hash prepended to the format. ++ +See also INCOMPATIBLE OPTIONS below. -r:: --rebase-merges[=(rebase-cousins|no-rebase-cousins)]:: @@ -404,7 +423,7 @@ It is currently only possible to recreate the merge commits using the `recursive` merge strategy; Different merge strategies can be used only via explicit `exec git merge -s <strategy> [...]` commands. + -See also REBASING MERGES below. +See also REBASING MERGES and INCOMPATIBLE OPTIONS below. -p:: --preserve-merges:: @@ -415,6 +434,8 @@ See also REBASING MERGES below. This uses the `--interactive` machinery internally, but combining it with the `--interactive` option explicitly is generally not a good idea unless you know what you are doing (see BUGS below). ++ +See also INCOMPATIBLE OPTIONS below. -x <cmd>:: --exec <cmd>:: @@ -437,6 +458,8 @@ squash/fixup series. + This uses the `--interactive` machinery internally, but it can be run without an explicit `--interactive`. ++ +See also INCOMPATIBLE OPTIONS below. --root:: Rebase all commits reachable from <branch>, instead of @@ -447,6 +470,8 @@ without an explicit `--interactive`. When used together with both --onto and --preserve-merges, 'all' root commits will be rewritten to have <newbase> as parent instead. ++ +See also INCOMPATIBLE OPTIONS below. --autosquash:: --no-autosquash:: @@ -461,11 +486,11 @@ without an explicit `--interactive`. too. The recommended way to create fixup/squash commits is by using the `--fixup`/`--squash` options of linkgit:git-commit[1]. + -This option is only valid when the `--interactive` option is used. -+ If the `--autosquash` option is enabled by default using the configuration variable `rebase.autoSquash`, this option can be used to override and disable this setting. ++ +See also INCOMPATIBLE OPTIONS below. --autostash:: --no-autostash:: @@ -475,17 +500,73 @@ used to override and disable this setting. with care: the final stash application after a successful rebase might result in non-trivial conflicts. ---no-ff:: - With --interactive, cherry-pick all rebased commits instead of - fast-forwarding over the unchanged ones. This ensures that the - entire history of the rebased branch is composed of new commits. -+ -Without --interactive, this is a synonym for --force-rebase. -+ -You may find this helpful after reverting a topic branch merge, as this option -recreates the topic branch with fresh commits so it can be remerged -successfully without needing to "revert the reversion" (see the -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). +INCOMPATIBLE OPTIONS +-------------------- + +git-rebase has many flags that are incompatible with each other, +predominantly due to the fact that it has three different underlying +implementations: + + * one based on linkgit:git-am[1] (the default) + * one based on git-merge-recursive (merge backend) + * one based on linkgit:git-cherry-pick[1] (interactive backend) + +Flags only understood by the am backend: + + * --committer-date-is-author-date + * --ignore-date + * --whitespace + * --ignore-whitespace + * -C + +Flags understood by both merge and interactive backends: + + * --merge + * --strategy + * --strategy-option + * --allow-empty-message + +Flags only understood by the interactive backend: + + * --[no-]autosquash + * --rebase-merges + * --preserve-merges + * --interactive + * --exec + * --keep-empty + * --autosquash + * --edit-todo + * --root when used in combination with --onto + +Other incompatible flag pairs: + + * --preserve-merges and --interactive + * --preserve-merges and --signoff + * --preserve-merges and --rebase-merges + * --rebase-merges and --strategy + * --rebase-merges and --strategy-option + +BEHAVIORAL DIFFERENCES +----------------------- + + * empty commits: + + am-based rebase will drop any "empty" commits, whether the + commit started empty (had no changes relative to its parent to + start with) or ended empty (all changes were already applied + upstream in other commits). + + merge-based rebase does the same. + + interactive-based rebase will by default drop commits that + started empty and halt if it hits a commit that ended up empty. + The `--keep-empty` option exists for interactive rebases to allow + it to keep commits that started empty. + + * directory rename detection: + + merge-based and interactive-based rebases work fine with + directory rename detection. am-based rebases sometimes do not. include::merge-strategies.txt[] @@ -879,8 +960,8 @@ rescheduled immediately, with a helpful message how to edit the todo list (this typically happens when a `reset` command was inserted into the todo list manually and contains a typo). -The `merge` command will merge the specified revision into whatever is -HEAD at that time. With `-C <original-commit>`, the commit message of +The `merge` command will merge the specified revision(s) into whatever +is HEAD at that time. With `-C <original-commit>`, the commit message of the specified merge commit will be used. When the `-C` is changed to a lower-case `-c`, the message will be opened in an editor after a successful merge so that the user can edit the message. @@ -889,7 +970,8 @@ If a `merge` command fails for any reason other than merge conflicts (i.e. when the merge operation did not even start), it is rescheduled immediately. At this time, the `merge` command will *always* use the `recursive` -merge strategy, with no way to choose a different one. To work around +merge strategy for regular merges, and `octopus` for octopus merges, +strategy, with no way to choose a different one. To work around this, an `exec` command can be used to call `git merge` explicitly, using the fact that the labels are worktree-local refs (the ref `refs/rewritten/onto` would correspond to the label `onto`, for example). diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 4f3efde80c..465a4ecbed 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -137,15 +137,17 @@ Note that no attempts whatsoever are made to validate the encoding. Specify encoding of compose message. Default is the value of the 'sendemail.composeencoding'; if that is unspecified, UTF-8 is assumed. ---transfer-encoding=(7bit|8bit|quoted-printable|base64):: +--transfer-encoding=(7bit|8bit|quoted-printable|base64|auto):: Specify the transfer encoding to be used to send the message over SMTP. 7bit will fail upon encountering a non-ASCII message. quoted-printable can be useful when the repository contains files that contain carriage returns, but makes the raw patch email file (as saved from a MUA) much harder to inspect manually. base64 is even more fool proof, but also - even more opaque. Default is the value of the `sendemail.transferEncoding` - configuration value; if that is unspecified, git will use 8bit and not - add a Content-Transfer-Encoding header. + even more opaque. auto will use 8bit when possible, and quoted-printable + otherwise. ++ +Default is the value of the `sendemail.transferEncoding` configuration +value; if that is unspecified, default to `auto`. --xmailer:: --no-xmailer:: @@ -398,8 +400,11 @@ have been specified, in which case default to 'compose'. + -- * Invoke the sendemail-validate hook if present (see linkgit:githooks[5]). - * Warn of patches that contain lines longer than 998 characters; this - is due to SMTP limits as described by http://www.ietf.org/rfc/rfc2821.txt. + * Warn of patches that contain lines longer than + 998 characters unless a suitable transfer encoding + ('auto', 'base64', or 'quoted-printable') is used; + this is due to SMTP limits as described by + http://www.ietf.org/rfc/rfc5322.txt. -- + Default is the value of `sendemail.validate`; if this is not set, diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 87c4288ffc..92f9c12b87 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -115,7 +115,7 @@ options for details. variable if it exists, or lexicographic order otherwise. See linkgit:git-config[1]. ---color[=<when>]: +--color[=<when>]:: Respect any colors specified in the `--format` option. The `<when>` field must be one of `always`, `never`, or `auto` (if `<when>` is absent, behave as if `always` was given). diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index afc6576a14..9c26be40f4 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -60,6 +60,15 @@ with a matching name, treat as equivalent to: $ git worktree add --track -b <branch> <path> <remote>/<branch> ------------ + +If the branch exists in multiple remotes and one of them is named by +the `checkout.defaultRemote` configuration variable, we'll use that +one for the purposes of disambiguation, even if the `<branch>` isn't +unique across all remotes. Set it to +e.g. `checkout.defaultRemote=origin` to always checkout remote +branches from there if `<branch>` is ambiguous but exists on the +'origin' remote. See also `checkout.defaultRemote` in +linkgit:git-config[1]. ++ If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, then, as a convenience, the new worktree is associated with a branch (call it `<branch>`) named after `$(basename <path>)`. If `<branch>` diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 7d1bd44094..72daa20e76 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -184,7 +184,8 @@ existing tag object. A colon, followed by a slash, followed by a text, names a commit whose commit message matches the specified regular expression. This name returns the youngest matching commit which is - reachable from any ref. The regular expression can match any part of the + reachable from any ref, including HEAD. + The regular expression can match any part of the commit message. To match messages starting with a string, one can use e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a diff --git a/Documentation/technical/commit-graph.txt b/Documentation/technical/commit-graph.txt index e1a883eb46..c664acbd76 100644 --- a/Documentation/technical/commit-graph.txt +++ b/Documentation/technical/commit-graph.txt @@ -118,9 +118,6 @@ Future Work - The commit graph feature currently does not honor commit grafts. This can be remedied by duplicating or refactoring the current graft logic. -- The 'commit-graph' subcommand does not have a "verify" mode that is - necessary for integration with fsck. - - After computing and storing generation numbers, we must make graph walks aware of generation numbers to gain the performance benefits they enable. This will mostly be accomplished by swapping a commit-date-ordered @@ -130,25 +127,6 @@ Future Work - 'log --topo-order' - 'tag --merged' -- Currently, parse_commit_gently() requires filling in the root tree - object for a commit. This passes through lookup_tree() and consequently - lookup_object(). Also, it calls lookup_commit() when loading the parents. - These method calls check the ODB for object existence, even if the - consumer does not need the content. For example, we do not need the - tree contents when computing merge bases. Now that commit parsing is - removed from the computation time, these lookup operations are the - slowest operations keeping graph walks from being fast. Consider - loading these objects without verifying their existence in the ODB and - only loading them fully when consumers need them. Consider a method - such as "ensure_tree_loaded(commit)" that fully loads a tree before - using commit->tree. - -- The current design uses the 'commit-graph' subcommand to generate the graph. - When this feature stabilizes enough to recommend to most users, we should - add automatic graph writes to common operations that create many commits. - For example, one could compute a graph on 'clone', 'fetch', or 'repack' - commands. - - A server could provide a commit graph file as part of the network protocol to avoid extra calculations by clients. This feature is only of benefit if the user is willing to trust the file, because verifying the file is correct diff --git a/Documentation/technical/directory-rename-detection.txt b/Documentation/technical/directory-rename-detection.txt new file mode 100644 index 0000000000..1c0086e287 --- /dev/null +++ b/Documentation/technical/directory-rename-detection.txt @@ -0,0 +1,115 @@ +Directory rename detection +========================== + +Rename detection logic in diffcore-rename that checks for renames of +individual files is aggregated and analyzed in merge-recursive for cases +where combinations of renames indicate that a full directory has been +renamed. + +Scope of abilities +------------------ + +It is perhaps easiest to start with an example: + + * When all of x/a, x/b and x/c have moved to z/a, z/b and z/c, it is + likely that x/d added in the meantime would also want to move to z/d by + taking the hint that the entire directory 'x' moved to 'z'. + +More interesting possibilities exist, though, such as: + + * one side of history renames x -> z, and the other renames some file to + x/e, causing the need for the merge to do a transitive rename. + + * one side of history renames x -> z, but also renames all files within + x. For example, x/a -> z/alpha, x/b -> z/bravo, etc. + + * both 'x' and 'y' being merged into a single directory 'z', with a + directory rename being detected for both x->z and y->z. + + * not all files in a directory being renamed to the same location; + i.e. perhaps most the files in 'x' are now found under 'z', but a few + are found under 'w'. + + * a directory being renamed, which also contained a subdirectory that was + renamed to some entirely different location. (And perhaps the inner + directory itself contained inner directories that were renamed to yet + other locations). + + * combinations of the above; see t/t6043-merge-rename-directories.sh for + various interesting cases. + +Limitations -- applicability of directory renames +------------------------------------------------- + +In order to prevent edge and corner cases resulting in either conflicts +that cannot be represented in the index or which might be too complex for +users to try to understand and resolve, a couple basic rules limit when +directory rename detection applies: + + 1) If a given directory still exists on both sides of a merge, we do + not consider it to have been renamed. + + 2) If a subset of to-be-renamed files have a file or directory in the + way (or would be in the way of each other), "turn off" the directory + rename for those specific sub-paths and report the conflict to the + user. + + 3) If the other side of history did a directory rename to a path that + your side of history renamed away, then ignore that particular + rename from the other side of history for any implicit directory + renames (but warn the user). + +Limitations -- detailed rules and testcases +------------------------------------------- + +t/t6043-merge-rename-directories.sh contains extensive tests and commentary +which generate and explore the rules listed above. It also lists a few +additional rules: + + a) If renames split a directory into two or more others, the directory + with the most renames, "wins". + + b) Avoid directory-rename-detection for a path, if that path is the + source of a rename on either side of a merge. + + c) Only apply implicit directory renames to directories if the other side + of history is the one doing the renaming. + +Limitations -- support in different commands +-------------------------------------------- + +Directory rename detection is supported by 'merge' and 'cherry-pick'. +Other git commands which users might be surprised to see limited or no +directory rename detection support in: + + * diff + + Folks have requested in the past that `git diff` detect directory + renames and somehow simplify its output. It is not clear whether this + would be desirable or how the output should be simplified, so this was + simply not implemented. Further, to implement this, directory rename + detection logic would need to move from merge-recursive to + diffcore-rename. + + * am + + git-am tries to avoid a full three way merge, instead calling + git-apply. That prevents us from detecting renames at all, which may + defeat the directory rename detection. There is a fallback, though; if + the initial git-apply fails and the user has specified the -3 option, + git-am will fall back to a three way merge. However, git-am lacks the + necessary information to do a "real" three way merge. Instead, it has + to use build_fake_ancestor() to get a merge base that is missing files + whose rename may have been important to detect for directory rename + detection to function. + + * rebase + + Since am-based rebases work by first generating a bunch of patches + (which no longer record what the original commits were and thus don't + have the necessary info from which we can find a real merge-base), and + then calling git-am, this implies that am-based rebases will not always + successfully detect directory renames either (see the 'am' section + above). merged-based rebases (rebase -m) and cherry-pick-based rebases + (rebase -i) are not affected by this shortcoming, and fully support + directory rename detection. diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index 7fee6b780a..6ac774d5f6 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -50,7 +50,8 @@ Each Extra Parameter takes the form of `<key>=<value>` or `<key>`. Servers that receive any such Extra Parameters MUST ignore all unrecognized keys. Currently, the only Extra Parameter recognized is -"version=1". +"version" with a value of '1' or '2'. See protocol-v2.txt for more +information on protocol version 2. Git Transport ------------- @@ -284,7 +285,9 @@ information is sent back to the client in the next step. The client can optionally request that pack-objects omit various objects from the packfile using one of several filtering techniques. These are intended for use with partial clone and partial fetch -operations. See `rev-list` for possible "filter-spec" values. +operations. An object that does not meet a filter-spec value is +omitted unless explicitly requested in a 'want' line. See `rev-list` +for possible filter-spec values. Once all the 'want's and 'shallow's (and optional 'deepen') are transferred, clients MUST send a flush-pkt, to tell the server side diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index f58f24b1ef..09e4e0273f 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -298,12 +298,21 @@ included in the client's request: for use with partial clone and partial fetch operations. See `rev-list` for possible "filter-spec" values. +If the 'ref-in-want' feature is advertised, the following argument can +be included in the client's request as well as the potential addition of +the 'wanted-refs' section in the server's response as explained below. + + want-ref <ref> + Indicates to the server that the client wants to retrieve a + particular ref, where <ref> is the full name of a ref on the + server. + The response of `fetch` is broken into a number of sections separated by delimiter packets (0001), with each section beginning with its section header. output = *section - section = (acknowledgments | shallow-info | packfile) + section = (acknowledgments | shallow-info | wanted-refs | packfile) (flush-pkt | delim-pkt) acknowledgments = PKT-LINE("acknowledgments" LF) @@ -318,6 +327,10 @@ header. shallow = "shallow" SP obj-id unshallow = "unshallow" SP obj-id + wanted-refs = PKT-LINE("wanted-refs" LF) + *PKT-LINE(wanted-ref LF) + wanted-ref = obj-id SP refname + packfile = PKT-LINE("packfile" LF) *PKT-LINE(%x01-03 *%x00-ff) @@ -378,6 +391,19 @@ header. * This section is only included if a packfile section is also included in the response. + wanted-refs section + * This section is only included if the client has requested a + ref using a 'want-ref' line and if a packfile section is also + included in the response. + + * Always begins with the section header "wanted-refs". + + * The server will send a ref listing ("<oid> <refname>") for + each reference requested using 'want-ref' lines. + + * The server MUST NOT send any refs which were not requested + using 'want-ref' lines. + packfile section * This section is only included if the client has sent 'want' lines in its request and either requested that no more |