diff options
Diffstat (limited to 'Documentation')
44 files changed, 429 insertions, 278 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 8579530710..32210a4386 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -580,11 +580,14 @@ Writing Documentation: or commands: Literal examples (e.g. use of command-line options, command names, - branch names, configuration and environment variables) must be - typeset in monospace (i.e. wrapped with backticks): + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset in monospace (i.e. wrapped with + backticks): `--pretty=oneline` `git rev-list` `remote.pushDefault` + `http://git.example.com` + `.git/config` `GIT_DIR` `HEAD` diff --git a/Documentation/Makefile b/Documentation/Makefile index 4e4dd7ecf1..6d738f831e 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -12,7 +12,6 @@ MAN1_TXT += $(filter-out \ $(wildcard git-*.txt)) MAN1_TXT += git.txt MAN1_TXT += gitk.txt -MAN1_TXT += gitremote-helpers.txt MAN1_TXT += gitweb.txt MAN5_TXT += gitattributes.txt @@ -30,6 +29,7 @@ MAN7_TXT += gitdiffcore.txt MAN7_TXT += giteveryday.txt MAN7_TXT += gitglossary.txt MAN7_TXT += gitnamespaces.txt +MAN7_TXT += gitremote-helpers.txt MAN7_TXT += gitrevisions.txt MAN7_TXT += gitsubmodules.txt MAN7_TXT += gittutorial-2.txt diff --git a/Documentation/RelNotes/2.22.0.txt b/Documentation/RelNotes/2.22.0.txt index 94100fa403..85e1122966 100644 --- a/Documentation/RelNotes/2.22.0.txt +++ b/Documentation/RelNotes/2.22.0.txt @@ -46,6 +46,27 @@ UI, Workflows & Features configuration (when available), which allows --list-cmds to honour a repository specific setting of completion.commands, for example. + * "git mergetool" learned to offer Sublime Merge (smerge) as one of + its backends. + + * A new hook "post-index-change" is called when the on-disk index + file changes, which can help e.g. a virtualized working tree + implementation. + + * "git difftool" can now run outside a repository. + + * "git checkout -m <other>" was about carrying the differences + between HEAD and the working-tree files forward while checking out + another branch, and ignored the differences between HEAD and the + index. The command has been taught to abort when the index and the + HEAD are different. + + * A progress indicator has been added to the "index-pack" step, which + often makes users wait for completion during "git clone". + + * "git submodule" learns "set-branch" subcommand that allows the + submodule.*.branch settings to be modified. + Performance, Internal Implementation, Development Support etc. @@ -80,6 +101,35 @@ Performance, Internal Implementation, Development Support etc. * "git multi-pack-index verify" did not scale well with the number of packfiles, which is being improved. + * "git stash" has been rewritten in C. + + * The "check-docs" Makefile target to support developers has been + updated. + + * The tests have been updated not to rely on the abbreviated option + names the parse-options API offers, to protect us from an + abbreviated form of an option that used to be unique within the + command getting non-unique when a new option that share the same + prefix is added. + + * The scripted version of "git rebase -i" wrote and rewrote the todo + list many times during a single step of its operation, and the + recent C-rewrite made a faithful conversion of the logic to C. The + implementation has been updated to carry necessary information + around in-core to avoid rewriting the same file over and over + unnecessarily. + + * Test framework update to more robustly clean up leftover files and + processes after tests are done. + + * Conversion from unsigned char[20] to struct object_id continues. + + * While running "git diff" in a lazy clone, we can upfront know which + missing blobs we will need, instead of waiting for the on-demand + machinery to discover them one by one. The code learned to aim to + achieve better performance by batching the request for these + promised blobs. + Fixes since v2.21 ----------------- @@ -203,8 +253,8 @@ Fixes since v2.21 * A corner-case object name ambiguity while the sequencer machinery is working (e.g. "rebase -i -x") has been fixed. - * "git format-patch" used overwrite an existing patch/cover-letter - file. A new "--no-clobber" option stops it. + * "git format-patch" did not diagnose an error while opening the + output file for the cover-letter, which has been corrected. (merge 2fe95f494c jc/format-patch-error-check later to maint). * "git checkout -f <branch>" while the index has an unmerged path @@ -220,6 +270,87 @@ Fixes since v2.21 * dumb-http walker has been updated to share more error recovery strategy with the normal codepath. + * A buglet in configuration parser has been fixed. + (merge 19e7fdaa58 nd/include-if-wildmatch later to maint). + + * The documentation for "git read-tree --reset -u" has been updated. + (merge b5a0bd694c nd/read-tree-reset-doc later to maint). + + * Code clean-up around a much-less-important-than-it-used-to-be + update_server_info() funtion. + (merge b3223761c8 jk/server-info-rabbit-hole later to maint). + + * The message given when "git commit -a <paths>" errors out has been + updated. + (merge 5a1dbd48bc nd/commit-a-with-paths-msg-update later to maint). + + * "git cherry-pick --options A..B", after giving control back to the + user to ask help resolving a conflicted step, did not honor the + options it originally received, which has been corrected. + + * Various glitches in "git gc" around reflog handling have been fixed. + + * The code to read from commit-graph file has been cleanup with more + careful error checking before using data read from it. + + * Performance fix around "git fetch" that grabs many refs. + (merge b764300912 jt/fetch-pack-wanted-refs-optim later to maint). + + * Protocol v2 support in "git fetch-pack" of shallow clones has been + corrected. + + * Performance fix around "git blame", especially in a linear history + (which is the norm we should optimize for). + (merge f892014943 dk/blame-keep-origin-blob later to maint). + + * Performance fix for "rev-list --parents -- pathspec". + (merge 8320b1dbe7 jk/revision-rewritten-parents-in-prio-queue later to maint). + + * Updating the display with progress message has been cleaned up to + deal better with overlong messages. + (merge 545dc345eb sg/overlong-progress-fix later to maint). + + * "git blame -- path" in a non-bare repository starts blaming from + the working tree, and the same command in a bare repository errors + out because there is no working tree by definition. The command + has been taught to instead start blaming from the commit at HEAD, + which is more useful. + (merge a544fb08f8 sg/blame-in-bare-start-at-head later to maint). + + * An underallocation in the code to read the untracked cache + extension has been corrected. + (merge 3a7b45a623 js/untracked-cache-allocfix later to maint). + + * The code is updated to check the result of memory allocation before + it is used in more places, by using xmalloc and/or xcalloc calls. + (merge 999b951b28 jk/xmalloc later to maint). + + * The GETTEXT_POISON test option has been quite broken ever since it + was made runtime-tunable, which has been fixed. + (merge f88b9cb603 jc/gettext-test-fix later to maint). + + * Test fix on APFS that is incapable of store paths in Latin-1. + (merge 3889149619 js/iso8895-test-on-apfs later to maint). + + * "git submodule foreach <command> --quiet" did not pass the option + down correctly, which has been corrected. + (merge a282f5a906 nd/submodule-foreach-quiet later to maint). + + * "git send-email" has been taught to use quoted-printable when the + payload contains carriage-return. The use of the mechanism is in + line with the design originally added the codepath that chooses QP + when the payload has overly long lines. + (merge 74d76a1701 bc/send-email-qp-cr later to maint). + + * The recently added feature to add addresses that are on + anything-by: trailers in 'git send-email' was found to be way too + eager and considered nonsense strings as if they can be legitimate + beginning of *-by: trailer. This has been tightened. + + * Build with gettext breaks on recent macOS w/ Homebrew when + /usr/local/bin is not on PATH, which has been corrected. + (merge 92a1377a2a js/macos-gettext-build later to maint). + * Code cleanup, docfix, build fix, etc. (merge 11f470aee7 jc/test-yes-doc later to maint). (merge 90503a240b js/doc-symref-in-proto-v1 later to maint). @@ -245,3 +376,12 @@ Fixes since v2.21 (merge a7256debd4 nd/checkout-m-doc-update later to maint). (merge 3a9e1ad78d jt/t5551-protocol-v2-does-not-have-half-auth later to maint). (merge 0b918b75af sg/t5318-cleanup later to maint). + (merge 68ed71b53c cb/doco-mono later to maint). + (merge a34dca2451 nd/interpret-trailers-docfix later to maint). + (merge cf7b857a77 en/fast-import-parsing-fix later to maint). + (merge fe61ccbc35 po/rerere-doc-fmt later to maint). + (merge ffea0248bf po/describe-not-necessarily-7 later to maint). + (merge 7cb7283adb tg/ls-files-debug-format-fix later to maint). + (merge f64a21bd82 tz/doc-apostrophe-no-longer-needed later to maint). + (merge dbe7b41019 js/t3301-unbreak-notes-test later to maint). + (merge d8083e4180 km/t3000-retitle later to maint). diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ec8b205145..6d589e118c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -372,15 +372,15 @@ such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". Some parts of the system have dedicated maintainers with their own repositories. -- 'git-gui/' comes from git-gui project, maintained by Pat Thoyts: +- `git-gui/` comes from git-gui project, maintained by Pat Thoyts: git://repo.or.cz/git-gui.git -- 'gitk-git/' comes from Paul Mackerras's gitk project: +- `gitk-git/` comes from Paul Mackerras's gitk project: git://ozlabs.org/~paulus/gitk -- 'po/' comes from the localization coordinator, Jiang Xin: +- `po/` comes from the localization coordinator, Jiang Xin: https://github.com/git-l10n/git-po/ diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt index 88620429ea..ec4f6ae658 100644 --- a/Documentation/config/advice.txt +++ b/Documentation/config/advice.txt @@ -90,4 +90,6 @@ advice.*:: waitingForEditor:: Print a message to the terminal whenever Git is waiting for editor input from the user. + nestedTag:: + Advice shown if a user attempts to recursively tag a tag object. -- diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt index 7e9b6c8f4c..75538d27e7 100644 --- a/Documentation/config/core.txt +++ b/Documentation/config/core.txt @@ -414,7 +414,7 @@ Common unit suffixes of 'k', 'm', or 'g' are supported. core.excludesFile:: Specifies the pathname to the file that contains patterns to describe paths that are not meant to be tracked, in addition - to '.gitignore' (per-directory) and '.git/info/exclude'. + to `.gitignore` (per-directory) and `.git/info/exclude`. Defaults to `$XDG_CONFIG_HOME/git/ignore`. If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/ignore` is used instead. See linkgit:gitignore[5]. @@ -429,8 +429,8 @@ core.askPass:: command-line argument and write the password on its STDOUT. core.attributesFile:: - In addition to '.gitattributes' (per-directory) and - '.git/info/attributes', Git looks into this file for attributes + In addition to `.gitattributes` (per-directory) and + `.git/info/attributes`, Git looks into this file for attributes (see linkgit:gitattributes[5]). Path expansions are made the same way as for `core.excludesFile`. Its default value is `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not @@ -438,10 +438,10 @@ core.attributesFile:: core.hooksPath:: By default Git will look for your hooks in the - '$GIT_DIR/hooks' directory. Set this to different path, - e.g. '/etc/git/hooks', and Git will try to find your hooks in - that directory, e.g. '/etc/git/hooks/pre-receive' instead of - in '$GIT_DIR/hooks/pre-receive'. + `$GIT_DIR/hooks` directory. Set this to different path, + e.g. `/etc/git/hooks`, and Git will try to find your hooks in + that directory, e.g. `/etc/git/hooks/pre-receive` instead of + in `$GIT_DIR/hooks/pre-receive`. + The path can be either absolute or relative. A relative path is taken as relative to the directory where the hooks are run (see diff --git a/Documentation/config/gc.txt b/Documentation/config/gc.txt index 73c08b0c00..02b92b18b5 100644 --- a/Documentation/config/gc.txt +++ b/Documentation/config/gc.txt @@ -1,25 +1,42 @@ gc.aggressiveDepth:: The depth parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 50. + to 50, which is the default for the `--depth` option when + `--aggressive` isn't in use. ++ +See the documentation for the `--depth` option in +linkgit:git-repack[1] for more details. gc.aggressiveWindow:: The window size parameter used in the delta compression algorithm used by 'git gc --aggressive'. This defaults - to 250. + to 250, which is a much more aggressive window size than + the default `--window` of 10. ++ +See the documentation for the `--window` option in +linkgit:git-repack[1] for more details. gc.auto:: When there are approximately more than this many loose objects in the repository, `git gc --auto` will pack them. Some Porcelain commands use this command to perform a light-weight garbage collection from time to time. The - default value is 6700. Setting this to 0 disables it. + default value is 6700. ++ +Setting this to 0 disables not only automatic packing based on the +number of loose objects, but any other heuristic `git gc --auto` will +otherwise use to determine if there's work to do, such as +`gc.autoPackLimit`. gc.autoPackLimit:: When there are more than this many packs that are not marked with `*.keep` file in the repository, `git gc --auto` consolidates them into one larger pack. The default value is 50. Setting this to 0 disables it. + Setting `gc.auto` to 0 will also disable this. ++ +See the `gc.bigPackThreshold` configuration variable below. When in +use, it'll affect how the auto pack limit works. gc.autoDetach:: Make `git gc --auto` return immediately and run in background @@ -36,11 +53,16 @@ Note that if the number of kept packs is more than gc.autoPackLimit, this configuration variable is ignored, all packs except the base pack will be repacked. After this the number of packs should go below gc.autoPackLimit and gc.bigPackThreshold should be respected again. ++ +If the amount of memory estimated for `git repack` to run smoothly is +not available and `gc.bigPackThreshold` is not set, the largest pack +will also be excluded (this is the equivalent of running `git gc` with +`--keep-base-pack`). gc.writeCommitGraph:: 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 + linkgit:git-gc[1] is run. When using `git gc --auto` + the commit-graph will be updated if housekeeping is required. Default is false. See linkgit:git-commit-graph[1] for details. @@ -94,6 +116,12 @@ gc.<pattern>.reflogExpireUnreachable:: With "<pattern>" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the <pattern>. ++ +These types of entries are generally created as a result of using `git +commit --amend` or `git rebase` and are the commits prior to the amend +or rebase occurring. Since these changes are not part of the current +project most users will want to expire them sooner, which is why the +default is more aggressive than `gc.reflogExpire`. gc.rerereResolved:: Records of conflicted merge you resolved earlier are diff --git a/Documentation/config/merge.txt b/Documentation/config/merge.txt index d389c73929..6a313937f8 100644 --- a/Documentation/config/merge.txt +++ b/Documentation/config/merge.txt @@ -39,9 +39,22 @@ merge.renameLimit:: is turned off. merge.renames:: - Whether and how Git detects renames. If set to "false", - rename detection is disabled. If set to "true", basic rename - detection is enabled. Defaults to the value of diff.renames. + Whether Git detects renames. If set to "false", rename detection + is disabled. If set to "true", basic rename detection is enabled. + Defaults to the value of diff.renames. + +merge.directoryRenames:: + Whether Git detects directory renames, affecting what happens at + merge time to new files added to a directory on one side of + history when that directory was renamed on the other side of + history. If merge.directoryRenames is set to "false", directory + rename detection is disabled, meaning that such new files will be + left behind in the old directory. If set to "true", directory + rename detection is enabled, meaning that such new files will be + moved into the new directory. If set to "conflict", a conflict + will be reported for such paths. If merge.renames is false, + merge.directoryRenames is ignored and treated as false. Defaults + to "conflict". merge.renormalize:: Tell Git that canonical representation of files in the diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 56d54a4898..fdc28c041c 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -57,7 +57,7 @@ OPTIONS This is sort of "Git root" - if you run 'git daemon' with '--base-path=/srv/git' on example.com, then if you later try to pull 'git://example.com/hello.git', 'git daemon' will interpret the path - as '/srv/git/hello.git'. + as `/srv/git/hello.git`. --base-path-relaxed:: If --base-path is enabled and repo lookup fails, with this option diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index ccdc5f83d6..a88f6ae2c6 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -139,7 +139,7 @@ at the end. The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". -The hash suffix is "-g" + 7-char abbreviation for the tip commit +The hash suffix is "-g" + unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 24f32e8c54..5c8a2a5e97 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -118,6 +118,7 @@ include::pretty-options.txt[] include::pretty-formats.txt[] + include::diff-format.txt[] GIT diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 43ab3b1637..d65cdb3d08 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -422,7 +422,12 @@ However it is recommended that a `filedeleteall` command precede all `filemodify`, `filecopy`, `filerename` and `notemodify` commands in the same commit, as `filedeleteall` wipes the branch clean (see below). -The `LF` after the command is optional (it used to be required). +The `LF` after the command is optional (it used to be required). Note +that for reasons of backward compatibility, if the commit ends with a +`data` command (i.e. it has has no `from`, `merge`, `filemodify`, +`filedelete`, `filecopy`, `filerename`, `filedeleteall` or +`notemodify` commands) then two `LF` commands may appear at the end of +the command instead of just one. `author` ^^^^^^^^ @@ -966,10 +971,6 @@ might want to refer to in their commit messages. 'get-mark' SP ':' <idnum> LF .... -This command can be used anywhere in the stream that comments are -accepted. In particular, the `get-mark` command can be used in the -middle of a commit but not in the middle of a `data` command. - See ``Responses To Commands'' below for details about how to read this output safely. @@ -996,9 +997,10 @@ Output uses the same format as `git cat-file --batch`: <contents> LF ==== -This command can be used anywhere in the stream that comments are -accepted. In particular, the `cat-blob` command can be used in the -middle of a commit but not in the middle of a `data` command. +This command can be used where a `filemodify` directive can appear, +allowing it to be used in the middle of a commit. For a `filemodify` +using an inline directive, it can also appear right before the `data` +directive. See ``Responses To Commands'' below for details about how to read this output safely. @@ -1011,8 +1013,8 @@ printing a blob from the active commit (with `cat-blob`) or copying a blob or tree from a previous commit for use in the current one (with `filemodify`). -The `ls` command can be used anywhere in the stream that comments are -accepted, including the middle of a commit. +The `ls` command can also be used where a `filemodify` directive can +appear, allowing it to be used in the middle of a commit. Reading from the active commit:: This form can only be used in the middle of a `commit`. @@ -1396,6 +1398,13 @@ deltas are suboptimal (see above) then also adding the `-f` option to force recomputation of all deltas can significantly reduce the final packfile size (30-50% smaller can be quite typical). +Instead of running `git repack` you can also run `git gc +--aggressive`, which will also optimize other things after an import +(e.g. pack loose refs). As noted in the "AGGRESSIVE" section in +linkgit:git-gc[1] the `--aggressive` option will find new deltas with +the `-f` option to linkgit:git-repack[1]. For the reasons elaborated +on above using `--aggressive` after a fast-import is one of the few +cases where it's known to be worthwhile. MEMORY UTILIZATION ------------------ diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index e6f08ab189..6b53dd7e06 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -189,7 +189,7 @@ to other tags will be rewritten to point to the underlying commit. rewriting. When applying a tree filter, the command needs to temporarily check out the tree to some directory, which may consume considerable space in case of large projects. By default it - does this in the '.git-rewrite/' directory but you can override + does this in the `.git-rewrite/` directory but you can override that choice by this parameter. -f:: diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index a7c1b0f60e..247f765604 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -20,17 +20,16 @@ created from prior invocations of 'git add', packing refs, pruning reflog, rerere metadata or stale working trees. May also update ancillary indexes such as the commit-graph. -Users are encouraged to run this task on a regular basis within -each repository to maintain good disk space utilization and good -operating performance. +When common porcelain operations that create objects are run, they +will check whether the repository has grown substantially since the +last maintenance, and if so run `git gc` automatically. See `gc.auto` +below for how to disable this behavior. -Some git commands may automatically run 'git gc'; see the `--auto` flag -below for details. If you know what you're doing and all you want is to -disable this behavior permanently without further considerations, just do: - ----------------------- -$ git config --global gc.auto 0 ----------------------- +Running `git gc` manually should only be needed when adding objects to +a repository without regularly running such porcelain commands, to do +a one-off repository optimization, or e.g. to clean up a suboptimal +mass-import. See the "PACKFILE OPTIMIZATION" section in +linkgit:git-fast-import[1] for more details on the import case. OPTIONS ------- @@ -40,35 +39,17 @@ OPTIONS space |