diff options
Diffstat (limited to 'Documentation')
29 files changed, 396 insertions, 80 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 390ceece52..227f46ae40 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -95,10 +95,6 @@ For shell scripts specifically (not exhaustive): - We use Arithmetic Expansion $(( ... )). - - Inside Arithmetic Expansion, spell shell variables with $ in front - of them, as some shells do not grok $((x)) while accepting $(($x)) - just fine (e.g. dash older than 0.5.4). - - We do not use Process Substitution <(list) or >(list). - Do not write control structures on a single line with semicolon. @@ -236,6 +232,18 @@ For C programs: while( condition ) func (bar+1); + - Do not explicitly compare an integral value with constant 0 or '\0', + or a pointer value with constant NULL. For instance, to validate that + counted array <ptr, cnt> is initialized but has no elements, write: + + if (!ptr || cnt) + BUG("empty array expected"); + + and not: + + if (ptr == NULL || cnt != 0); + BUG("empty array expected"); + - We avoid using braces unnecessarily. I.e. if (bla) { diff --git a/Documentation/RelNotes/2.27.0.txt b/Documentation/RelNotes/2.27.0.txt index 3f5c0bd875..15518d06c1 100644 --- a/Documentation/RelNotes/2.27.0.txt +++ b/Documentation/RelNotes/2.27.0.txt @@ -24,6 +24,10 @@ Backward compatibility notes users may find annoying---those who prefer not to rebase need to set the variable to false to squelch the warning. + * The transport protocol version 2, which was promoted to the default + in Git 2.26 release, turned out to have some remaining rough edges, + so it has been demoted from the default. + UI, Workflows & Features @@ -96,6 +100,25 @@ UI, Workflows & Features check for the paths that were modified at each commit using Bloom filters. + * The approxidate parser learns to parse seconds with fraction and + ignore fractional part. + + * The userdiff patterns for Markdown documents have been added. + + * The sparse-checkout patterns have been forbidden from excluding all + paths, leaving an empty working tree, for a long time. This + limitation has been lifted. + + * "git restore --staged --worktree" now defaults to take the contents + out of "HEAD", instead of erring out. + + * "git p4" learned to recover from a (broken) state where a directory + and a file are recorded at the same path in the Perforce repository + the same way as their clients do. + + * "git multi-pack-index repack" has been taught to honor some + repack.* configuration variables. + Performance, Internal Implementation, Development Support etc. @@ -149,6 +172,21 @@ Performance, Internal Implementation, Development Support etc. * The "bugreport" tool has been added. + * The object walk with object filter "--filter=tree:0" can now take + advantage of the pack bitmap when available. + + * Instead of always building all branches at GitHub via Actions, + users can specify which branches to build. + + * Codepaths that show progress meter have been taught to also use the + start_progress() and the stop_progress() calls as a "region" to be + traced. + + * Instead of downloading Windows SDK for CI jobs for windows builds + from an external site (wingit.blob.core.windows.net), use the one + created in the windows-build job, to work around quota issues at + the external site. + Fixes since v2.26 ----------------- @@ -355,6 +393,107 @@ Fixes since v2.26 credential material embedded in URLs. (merge d192fa5006 js/anonymise-push-url-in-errors later to maint). + * Update the parser used for credential.<URL>.<variable> + configuration, to handle <URL>s with '/' in them correctly. + (merge b44d0118ac bc/wildcard-credential later to maint). + + * Recent updates broke parsing of "credential.<url>.<key>" where + <url> is not a full URL (e.g. [credential "https://"] helper = ...) + stopped working, which has been corrected. + (merge 9a121b0d22 js/partial-urlmatch-2.17 later to maint). + (merge cd93e6c029 js/partial-urlmatch later to maint). + + * Some of the files commit-graph subsystem keeps on disk did not + correctly honor the core.sharedRepository settings and some were + left read-write. + + * In error messages that "git switch" mentions its option to create a + new branch, "-b/-B" options were shown, where "-c/-C" options + should be, which has been corrected. + (merge 7c16ef7577 dl/switch-c-option-in-error-message later to maint). + + * With the recent tightening of the code that is used to parse + various parts of a URL for use in the credential subsystem, a + hand-edited credential-store file causes the credential helper to + die, which is a bit too harsh to the users. Demote the error + behaviour to just ignore and keep using well-formed lines instead. + (merge c03859a665 cb/credential-store-ignore-bogus-lines later to maint). + + * The samples in the credential documentation has been updated to + make it clear that we depict what would appear in the .git/config + file, by adding appropriate quotes as needed.. + (merge 177681a07e jk/credential-sample-update later to maint). + + * "git branch" and other "for-each-ref" variants accepted multiple + --sort=<key> options in the increasing order of precedence, but it + had a few breakages around "--ignore-case" handling, and tie-breaking + with the refname, which have been fixed. + (merge 7c5045fc18 jk/for-each-ref-multi-key-sort-fix later to maint). + + * The coding guideline for shell scripts instructed to refer to a + variable with dollar-sign inside arithmetic expansion to work + around a bug in old versions of dash, which is a thing of the past. + Now we are not forbidden from writing $((var+1)). + (merge 32b5fe7f0e jk/arith-expansion-coding-guidelines later to maint). + + * The <stdlib.h> header on NetBSD brings in its own definition of + hmac() function (eek), which conflicts with our own and unrelated + function with the same name. Our function has been renamed to work + around the issue. + (merge 3013118eb8 cb/avoid-colliding-with-netbsd-hmac later to maint). + + * The basic test did not honor $TEST_SHELL_PATH setting, which has + been corrected. + (merge 0555e4af58 cb/t0000-use-the-configured-shell later to maint). + + * Minor in-code comments and documentation updates around credential + API. + (merge 1aed817f99 cb/credential-doc-fixes later to maint). + + * Teach "am", "commit", "merge" and "rebase", when they are run with + the "--quiet" option, to pass "--quiet" down to "gc --auto". + (merge 7c3e9e8cfb jc/auto-gc-quiet later to maint). + + * The code to skip unmerged paths in the index when sparse checkout + is in use would have made out-of-bound access of the in-core index + when the last path was unmerged, which has been corrected. + + * Serving a "git fetch" client over "git://" and "ssh://" protocols + using the on-wire protocol version 2 was buggy on the server end + when the client needs to make a follow-up request to + e.g. auto-follow tags. + (merge 08450ef791 cc/upload-pack-v2-fetch-fix later to maint). + + * "git bisect replay" had trouble with input files when they used + CRLF line ending, which has been corrected. + (merge 6c722cbe5a cw/bisect-replay-with-dos later to maint). + + * "rebase -i" segfaulted when rearranging a sequence that has a + fix-up that applies another fix-up (which may or may not be a + fix-up of yet another step). + (merge 02471e7e20 js/rebase-autosquash-double-fixup-fix later to maint). + + * "git fsck" ensures that the paths recorded in tree objects are + sorted and without duplicates, but it failed to notice a case where + a blob is followed by entries that sort before a tree with the same + name. This has been corrected. + (merge 9068cfb20f rs/fsck-duplicate-names-in-trees later to maint). + + * Code clean-up by removing a compatibility implementation of a + function we no longer use. + (merge 84b0115f0d cb/no-more-gmtime later to maint). + + * When a binary file gets modified and renamed on both sides of history + to different locations, both files would be written to the working + tree but both would have the contents from "ours". This has been + corrected so that the path from each side gets their original content. + + * Fix for a copy-and-paste error introduced during 2.20 era. + (merge e68a5272b1 ds/multi-pack-verify later to maint). + + * Update an unconditional use of "grep -a" with a perl script in a test. + (merge 1eb7371236 dd/t5703-grep-a-fix later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 564956f358 jc/maintain-doc later to maint). (merge 7422b2a0a1 sg/commit-slab-clarify-peek later to maint). @@ -381,3 +520,6 @@ Fixes since v2.26 (merge 39102cf4fe ms/doc-revision-illustration-fix later to maint). (merge 4d9378bfad eb/gitweb-more-trailers later to maint). (merge bdccbf7047 mt/doc-worktree-ref later to maint). + (merge ce9baf234f dl/push-recurse-submodules-fix later to maint). + (merge 4153274052 bc/doc-credential-helper-value later to maint). + (merge 5c7bb0146e jc/codingstyle-compare-with-null later to maint). diff --git a/Documentation/RelNotes/2.28.0.txt b/Documentation/RelNotes/2.28.0.txt new file mode 100644 index 0000000000..b1a23e94c9 --- /dev/null +++ b/Documentation/RelNotes/2.28.0.txt @@ -0,0 +1,83 @@ +Git 2.28 Release Notes +====================== + +Updates since v2.27 +------------------- + +Backward compatibility notes + + * "feature.experimental" configuration variable is to let volunteers + easily opt into a set of newer features, which use of the v2 + transport protocol is now a part of. + + +UI, Workflows & Features + + * The commands in the "diff" family learned to honor "diff.relative" + configuration variable. + + * The check in "git fsck" to ensure that the tree objects are sorted + still had corner cases it missed unsorted entries. + + +Performance, Internal Implementation, Development Support etc. + + * Code optimization for a common case. + (merge 8777616e4d an/merge-single-strategy-optim later to maint). + + * We've adopted a convention that any on-stack structure can be + initialized to have zero values in all fields with "= { 0 }", + even when the first field happens to be a pointer, but sparse + complained that a null pointer should be spelled NULL for a long + time. Start using -Wno-universal-initializer option to squelch + it (the latest sparse has it on by default). + + * "git log -L..." now takes advantage of the "which paths are touched + by this commit?" info stored in the commit-graph system. + + * As FreeBSD is not the only platform whose regexp library reports + a REG_ILLSEQ error when fed invalid UTF-8, add logic to detect that + automatically and skip the affected tests. + + * "git bugreport" learns to report what shell is in use. + + * Support for GIT_CURL_VERBOSE has been rewritten in terms of + GIT_TRACE_CURL. + + +Fixes since v2.27 +----------------- + + * The "--prepare-p4-only" option of "git p4" is supposed to stop + after replaying one changeset, but kept going (by mistake?) + + * The error message from "git checkout -b foo -t bar baz" was + confusing. + + * Some repositories in the wild have commits that record nonsense + committer timezone (e.g. rails.git); "git fast-import" learned an + option to pass these nonsense timestamps intact to allow recreating + existing repositories as-is. + (merge d42a2fb72f en/fast-import-looser-date later to maint). + + * The command line completion script (in contrib/) tried to complete + "git stash -p" as if it were "git stash push -p", but it was too + aggressive and also affected "git stash show -p", which has been + corrected. + (merge fffd0cf520 vs/complete-stash-show-p-fix later to maint). + + * On-the-wire protocol v2 easily falls into a deadlock between the + remote-curl helper and the fetch-pack process when the server side + prematurely throws an error and disconnects. The communication has + been updated to make it more robust. + + * "git checkout -p" did not handle a newly added path at all. + (merge 2c8bd8471a js/checkout-p-new-file later to maint). + + * The code to parse "git bisect start" command line was lax in + validating the arguments. + (merge 4d9005ff5d cb/bisect-helper-parser-fix later to maint). + + * Other code cleanup, docfix, build fix, etc. + (merge 2c31a7aa44 jx/pkt-line-doc-count-fix later to maint). + (merge d63ae31962 cb/t5608-cleanup later to maint). diff --git a/Documentation/config/credential.txt b/Documentation/config/credential.txt index 60fb3189e1..9d01641c28 100644 --- a/Documentation/config/credential.txt +++ b/Documentation/config/credential.txt @@ -1,9 +1,13 @@ credential.helper:: Specify an external helper to be called when a username or password credential is needed; the helper may consult external - storage to avoid prompting the user for the credentials. Note - that multiple helpers may be defined. See linkgit:gitcredentials[7] - for details. + storage to avoid prompting the user for the credentials. This is + normally the name of a credential helper with possible + arguments, but may also be an absolute path with arguments or, if + preceded by `!`, shell commands. ++ +Note that multiple helpers may be defined. See linkgit:gitcredentials[7] +for details and examples. credential.useHttpPath:: When acquiring credentials, consider the "path" component of an http diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index ff09f1cf73..c3ae136eba 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -105,6 +105,10 @@ diff.mnemonicPrefix:: diff.noprefix:: If set, 'git diff' does not show any source or destination prefix. +diff.relative:: + If set to 'true', 'git diff' does not show changes outside of the directory + and show pathnames relative to the current directory. + diff.orderFile:: File indicating how to order files within a diff. See the '-O' option to linkgit:git-diff[1] for details. diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt index 4e3a5c0ceb..28c33602d5 100644 --- a/Documentation/config/feature.txt +++ b/Documentation/config/feature.txt @@ -22,6 +22,10 @@ existing commit-graph file(s). Occasionally, these files will merge and the write may take longer. Having an updated commit-graph file helps performance of many Git commands, including `git merge-base`, `git push -f`, and `git log --graph`. ++ +* `protocol.version=2` speeds up fetches from repositories with many refs by +allowing the client to specify which refs to list before the server lists +them. feature.manyFiles:: Enable config options that optimize for repos with many files in the diff --git a/Documentation/config/protocol.txt b/Documentation/config/protocol.txt index 0b40141613..c46e9b3d00 100644 --- a/Documentation/config/protocol.txt +++ b/Documentation/config/protocol.txt @@ -48,7 +48,8 @@ protocol.version:: If set, clients will attempt to communicate with a server using the specified protocol version. If the server does not support it, communication falls back to version 0. - If unset, the default is `0`. + If unset, the default is `0`, unless `feature.experimental` + is enabled, in which case the default is `2`. Supported versions: + -- diff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt index 6926e0a4c8..f1097fac69 100644 --- a/Documentation/date-formats.txt +++ b/Documentation/date-formats.txt @@ -20,7 +20,9 @@ RFC 2822:: ISO 8601:: Time and date specified by the ISO 8601 standard, for example `2005-04-07T22:13:13`. The parser accepts a space instead of the - `T` character as well. + `T` character as well. Fractional parts of a second will be ignored, + for example `2005-04-07T22:13:13.019` will be treated as + `2005-04-07T22:13:13`. + NOTE: In addition, the date part is accepted in the following formats: `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index bb31f0c42b..7987d72b02 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -643,15 +643,18 @@ ifndef::git-format-patch[] -R:: Swap two inputs; that is, show differences from index or on-disk file to tree contents. +endif::git-format-patch[] --relative[=<path>]:: +--no-relative:: When run from a subdirectory of the project, it can be told to exclude changes outside the directory and show pathnames relative to it with this option. When you are not in a subdirectory (e.g. in a bare repository), you can name which subdirectory to make the output relative to by giving a <path> as an argument. -endif::git-format-patch[] + `--no-relative` can be used to countermand both `diff.relative` config + option and previous `--relative`. -a:: --text:: diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt index 643d1b2884..66e88c2e31 100644 --- a/Documentation/git-bugreport.txt +++ b/Documentation/git-bugreport.txt @@ -28,6 +28,8 @@ The following information is captured automatically: - 'git version --build-options' - uname sysname, release, version, and machine strings - Compiler-specific info string + - A list of enabled hooks + - $SHELL This tool is invoked via the typical Git setup process, which means that in some cases, it might not be able to launch - for example, if a relevant config file @@ -45,7 +47,7 @@ OPTIONS --suffix <format>:: Specify an alternate suffix for the bugreport name, to create a file named 'git-bugreport-<formatted suffix>'. This should take the form of a - link:strftime[3] format string; the current local time will be used. + strftime(3) format string; the current local time will be used. GIT --- diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index 53a650225a..8ca1764d3d 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -47,8 +47,10 @@ 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` or `--reachable`.) +of OIDs in hex, one OID per line. OIDs that resolve to non-commits +(either directly, or by peeling tags) are silently ignored. OIDs that +are malformed, or do not exist generate an error. (Cannot be combined +with `--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` @@ -58,7 +60,7 @@ With the `--append` option, include all commits that are present in the existing commit-graph file. + With the `--changed-paths` option, compute and write information about the -paths changed between a commit and it's first parent. This operation can +paths changed between a commit and its first parent. This operation can take a while on large repositories. It provides significant performance gains for getting history of a directory or a file with `git log -- <path>`. + @@ -68,6 +70,7 @@ chain of multiple commit-graph files stored in strategy and other splitting options. The new commits not already in the commit-graph are added in a new "tip" file. This file is merged with the existing file if the following merge conditions are met: ++ * If `--split=no-merge` is specified, a merge is never performed, and the remaining options are ignored. `--split=replace` overwrites the existing chain with a new one. A bare `--split` defers to the remaining diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 693dd9d9d7..76b0798856 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -94,6 +94,10 @@ stored on its own line as a URL like: https://user:pass@example.com ------------------------------ +No other kinds of lines (e.g. empty lines or comment lines) are +allowed in the file, even though some may be silently ignored. Do +not view or edit the file with editors. + When Git needs authentication for a particular URL context, credential-store will consider that context a pattern to match against each entry in the credentials file. If the protocol, hostname, and diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 6f0c7ca80f..31c81c4c02 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -103,17 +103,20 @@ INPUT/OUTPUT FORMAT `git credential` reads and/or writes (depending on the action used) credential information in its standard input/output. This information can correspond either to keys for which `git credential` will obtain -the login/password information (e.g. host, protocol, path), or to the -actual credential data to be obtained (login/password). +the login information (e.g. host, protocol, path), or to the actual +credential data to be obtained (username/password). The credential is split into a set of named attributes, with one -attribute per line. Each attribute is -specified by a key-value pair, separated by an `=` (equals) sign, -followed by a newline. The key may contain any bytes except `=`, -newline, or NUL. The value may contain any bytes except newline or NUL. +attribute per line. Each attribute is specified by a key-value pair, +separated by an `=` (equals) sign, followed by a newline. + +The key may contain any bytes except `=`, newline, or NUL. The value may +contain any bytes except newline or NUL. + In both cases, all bytes are treated as-is (i.e., there is no quoting, and one cannot transmit a value with newline or NUL in it). The list of attributes is terminated by a blank line or end-of-file. + Git understands the following attributes: `protocol`:: @@ -123,7 +126,8 @@ Git understands the following attributes: `host`:: - The remote hostname for a network credential. + The remote hostname for a network credential. This includes + the port number if one was specified (e.g., "example.com:8088"). `path`:: @@ -134,7 +138,7 @@ Git understands the following attributes: `username`:: The credential's username, if we already have one (e.g., from a - URL, from the user, or from a previously run helper). + URL, the configuration, the user, or from a previously run helper). `password`:: @@ -146,8 +150,12 @@ Git understands the following attributes: value is parsed as a URL and treated as if its constituent parts were read (e.g., `url=https://example.com` would behave as if `protocol=https` and `host=example.com` had been provided). This - can help callers avoid parsing URLs themselves. Note that any - components which are missing from the URL (e.g., there is no - username in the example above) will be set to empty; if you want - to provide a URL and override some attributes, provide the URL - attribute first, followed by any overrides. + can help callers avoid parsing URLs themselves. ++ +Note that specifying a protocol is mandatory and if the URL +doesn't specify a hostname (e.g., "cert:///path/to/file") the +credential will contain a hostname attribute whose value is an +empty string. ++ +Components which are missing from the URL (e.g., there is no +username in the example above) will be left unset. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 77c6b3d001..7d9aad2a7e 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -293,7 +293,14 @@ by users who are located in the same location and time zone. In this case a reasonable offset from UTC could be assumed. + Unlike the `rfc2822` format, this format is very strict. Any -variation in formatting will cause fast-import to reject the value. +variation in formatting will cause fast-import to reject the value, +and some sanity checks on the numeric values may also be performed. + +`raw-permissive`:: + This is the same as `raw` except that no sanity checks on + the numeric epoch and local offset are performed. This can + be useful when trying to filter or import an existing history + with e.g. bogus timezone values. `rfc2822`:: This is the standard email format as described by RFC 2822. diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index ec06b2f8c2..3819fadac1 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -106,12 +106,12 @@ commit or stash your changes before running 'git merge'. `MERGE_HEAD` is present unless `MERGE_AUTOSTASH` is also present in which case 'git merge --abort' applies the stash entry to the worktree whereas 'git reset --merge' will save the stashed changes in the stash -reflog. +list. --quit:: Forget about the current merge in progress. Leave the index and the working tree as-is. If `MERGE_AUTOSTASH` is present, the - stash entry will be saved to the stash reflog. + stash entry will be saved to the stash list. --continue:: After a 'git merge' stops due to conflicts you can conclude the diff --git a/Documentation/git-multi-pack-index.txt b/Documentation/git-multi-pack-index.txt index 642d9ac5b7..0c6619493c 100644 --- a/Documentation/git-multi-pack-index.txt +++ b/Documentation/git-multi-pack-index.txt @@ -56,6 +56,9 @@ repack:: file is created, rewrite the multi-pack-index to reference the new pack-file. A later run of 'git multi-pack-index expire' will delete the pack-files that were part of this batch. ++ +If `repack.packKeptObjects` is `false`, then any pack-files with an +associated `.keep` file will not be selected for the batch to repack. EXAMPLES diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 794f2f39f1..4624cfd288 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -257,7 +257,7 @@ See also INCOMPATIBLE OPTIONS below. Abort the rebase operation but HEAD is not reset back to the original branch. The index and working tree are also left unchanged as a result. If a temporary stash entry was created - using --autostash, it will be saved to the stash reflog. + using --autostash, it will be saved to the stash list. --apply: Use applying strategies to rebase (calling `git-am` diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 8e3b339802..84c6c40010 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -22,9 +22,8 @@ The command can also be used to restore the content in the index with `--staged`, or restore both the working tree and the index with `--staged --worktree`. -By default, the restore sources for working tree and the index are the -index and `HEAD` respectively. `--source` could be used to specify a -commit as the restore source. +By default, if `--staged` is given, the contents are restored from `HEAD`, +otherwise from the index. Use `--source` to restore from a different commit. See "Reset, restore and revert" in linkgit:git[1] for the differences between the three commands. @@ -39,10 +38,8 @@ OPTIONS tree. It is common to specify the source tree by naming a commit, branch or tag associated with it. + -If not specified, the default restore source for the working tree is -the index, and the default restore source for the index is -`HEAD`. When both `--staged` and `--worktree` are specified, -`--source` must also be specified. +If not specified, the contents are restored from `HEAD` if `--staged` is +given, otherwise from the index. -p:: --patch:: diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 1a3ace6082..7c8943af7a 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -70,7 +70,7 @@ C-style quoted strings. `core.sparseCheckoutCone` is enabled, the given patterns are interpreted as directory names as in the 'set' subcommand. -'reapply:: +'reapply':: Reapply the sparsity pattern rules to paths in the working tree. Commands like merge or rebase can materialize paths to do their work (e.g. in order to show you a conflict), and other diff --git a/Documentation/git.txt b/Documentation/git.txt index 9d6769e95a..40bd32f590 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -493,7 +493,7 @@ double-quotes and respecting backslash escapes. E.g., the value details. This variable has lower precedence than other path variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY... -`GIT_DEFAULT_HASH_ALGORITHM`:: +`GIT_DEFAULT_HASH`:: If this variable is set, the default hash algorithm for new repositories will be set to this value. This value is currently ignored when cloning; the setting of the remote repository @@ -721,8 +721,6 @@ of clones and fetches. Enables a curl full trace dump of all incoming and outgoing data, including descriptive information, of the git transport protocol. This is similar to doing curl `--trace-ascii` on the command line. - This option overrides setting the `GIT_CURL_VERBOSE` environment - variable. See `GIT_TRACE` for available trace output options. `GIT_TRACE_CURL_NO_DATA`:: diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 508fe713c4..2d0a03715b 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -824,6 +824,8 @@ patterns are available: - `java` suitable for source code in the Java language. +- `markdown` suitable for Markdown documents. + - `matlab` suitable for source code in the MATLAB and Octave languages. - `objc` suitable for source code in the Objective-C language. diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt index 1814d2d23c..9e481aec85 100644 --- a/Documentation/gitcredentials.txt +++ b/Documentation/gitcredentials.txt @@ -216,20 +216,26 @@ Here are some example specifications: ---------------------------------------------------- # run "git credential-foo" -foo +[credential] + helper = foo # same as above, but pass an argument to the helper -foo --bar=baz +[credential] + helper = "foo --bar=baz" # the arguments are parsed by the shell, so use shell # quoting if necessary -foo --bar="whitespace arg" +[credential] + helper = "foo --bar='whitespace arg'" # you can also use an absolute path, which will not use the git wrapper -/path/to/my/helper --with-arguments +[credential] + helper = "/path/to/my/helper --with-arguments" # or you can specify your own shell snippet -!f() { echo "password=`cat $HOME/.secret`"; }; f +[credential "https://example.com"] + username = your_user + helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f" ---------------------------------------------------- Generally speaking, rule (3) above is the simplest for users to specify. @@ -262,16 +268,26 @@ For a `get` operation, the helper should produce a list of attributes on stdout in the same format (see linkgit:git-credential[1] for common attributes). A helper is free to produce a subset, or even no values at all if it has nothing useful to provide. Any provided attributes will -overwrite those already known about by Git. If a helper outputs a -`quit` attribute with a value of `true` or `1`, no further helpers will -be consulted, nor will the user be prompted (if no credential has been -provided, the operation will then fail). +overwrite those already known about by Git's credential subsystem. + +While it is possible to override all attributes, well behaving helpers +should refrain from doing so for any attribute other than username and +password. + +If a helper outputs a `quit` attribute with a value of `true` or `1`, +no further helpers will be consulted, nor will the user be prompted +(if no credential has been provided, the operation will then fail). + +Similarly, no more helpers will be consulted once both username and +password had been provided. For a `store` or `erase` operation, the helper's output is ignored. -If it fails to perform the requested operation, it may complain to -stderr to inform the user. If it does not support the requested -operation (e.g., a read-only store), it should silently ignore the -request. + +If a helper fails to perform the requested operation or needs to notify +the user of a potential issue, it may write to stderr. + +If it does not support the requested operation (e.g., a read-only store), +it should silently ignore the request. If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index 1cf83df118..9cd7a592ac 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -223,6 +223,24 @@ a file checked into the repository which is a template or set of defaults which can then be copied alongside and modified as appropriate. This second, modified file is usually ignored to prevent accidentally committing it. +[[files-in-gitignore-are-tracked]] +I asked Git to ignore various files, yet they are still tracked:: + A `gitignore` file ensures that certain file(s) which are not + tracked by Git remain untracked. However, sometimes particular + file(s) may have been tracked before adding them into the + `.gitignore`, hence they still remain tracked. To untrack and + ignore files/patterns, use `git rm --cached <file/pattern>` + and add a pattern to `.gitignore` that matches the <file>. + See linkgit:gitignore[5] for details. + +[[fetching-and-pulling]] +How do I know if I want to do a fetch or a pull?:: + A fetch stores a copy of the latest changes from the remote + repository, without modifying the working tree or current branch. + You can then at your leisure inspect, merge, rebase on top of, or + ignore the upstream changes. A pull consists of a fetch followed + immediately by either a merge or rebase. See linkgit:git-pull[1]. + Hooks ----- diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index f48a031dc3..93baeeb029 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -405,7 +405,9 @@ Supported if the helper has the "connect" capability. trying to fall back). After line feed terminating the positive (empty) response, the output of the service starts. Messages (both request and response) must consist of zero or more - PKT-LINEs, terminating in a flush packet. The client must not + PKT-LINEs, terminating in a flush packet. Response messages will + then have a response end packet after the flush packet to + indicate the end of a response. The client must not expect the server to store any state in between request-response pairs. After the connection ends, the remote helper exits. + diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 04ad7dd36e..b01b2b6773 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -581,12 +581,12 @@ option does. Applied to the 'D..M' range, it results in: Before discussing another option, `--show-pulls`, we need to create a new example history. -+ + A common problem users face when looking at simplified history is that a commit they know changed a file somehow does not appear in the file's simplified history. Let's demonstrate a new example and show how options such as `--full-history` and `--simplify-merges` works in that case: -+ + ----------------------------------------------------------------------- .-A---M-----C--N---O---P / / \ \ \/ / / @@ -595,7 +595,7 @@ such as `--full-history` and `--simplify-merges` works in that case: \ / /\ / `---X--' `---Y--' ----------------------------------------------------------------------- -+ + For this example, suppose `I` created `file.txt` which was modified by `A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`, and `Y` do not change `file.txt`. The merge commit `M` was created by @@ -607,19 +607,19 @@ the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`. The merge commits `O` and `P` are TREESAME to their first parents, but not to their second parents, `Z` and `Y` respectively. -+ + When using the default mode, `N` and `R` both have a TREESAME parent, so those edges are walked and the others are ignored. The resulting history graph is: -+ + ----------------------------------------------------------------------- I---X ----------------------------------------------------------------------- -+ + When using `--full-history`, Git walks every edge. This will discover the commits `A` and `B` and the merge `M`, but also will reveal the merge commits `O` and `P`. With parent rewriting, the resulting graph is: -+ + ----------------------------------------------------------------------- .-A---M--------N---O---P / / \ \ \/ / / @@ -628,21 +628,21 @@ merge commits `O` and `P`. With parent rewriting, the resulting graph is: \ / /\ / `---X--' `------' ----------------------------------------------------------------------- -+ + Here, the merge commits `O` and `P` contribute extra noise, as they did not actually contribute a change to `file.txt`. They only merged a topic that was based on an older version of `file.txt`. This is a common issue in repositories using a workflow where many contributors work in parallel and merge their topic branches along a single trunk: manu unrelated merges appear in the `--full-history` results. -+ + When using the `--simplify-merges` option, the commits `O` and `P` disappear from the results. This is because the rewritten second parents of `O` and `P` are reachable from their first parents. Those edges are removed and then the commits look like single-parent commits that are TREESAME to their parent. This also happens to the commit `N`, resulting in a history view as follows: -+ + ----------------------------------------------------------------------- .-A---M--. / / \ @@ -651,18 +651,18 @@ in a history view as follows: \ / / `---X--' ----------------------------------------------------------------------- -+ + In this view, we see all of the important single-parent changes from `A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the not-so-carefully-resolved merge `R`. This is usually enough information to determine why the commits `A` and `B` "disappeared" from history in the default view. However, there are a few issues with this approach. -+ + The first issue is performance. Unlike any previous option, the `--simplify-merges` option requires walking the entire commit history before returning a single result. This can make the option difficult to use for very large repositories. -+ + The second issue is one of auditing. When many contributors are working on the same repository, it is important which merge commits introduced a change into an important branch. The problematic merge `R` above is @@ -671,10 +671,13 @@ important branch. Instead, the merge `N` was used to merge `R` and `X` into the important branch. This commit may have information about why the change `X` came to override the changes from `A` and `B` in its commit message. + +--show-pulls:: + In addition to the commits shown in the default history, show + each merge commit that is not TREESAME to its first parent but + is TREESAME to a later parent. + -The `--show-pulls` option helps with both of these issues by adding more -merge commits to the history results. If a merge is not TREESAME to its -first parent but is TREESAME to a later parent, then that merge is +When a merge commit is included by `--show-pulls`, the merge is treated as if it "pulled" the change from another branch. When using `--show-pulls` on this example (and no other options) the resulting graph is: diff --git a/Documentation/technical/commit-graph-format.txt b/Documentation/technical/commit-graph-format.txt index de56f9f1ef..1beef17182 100644 --- a/Documentation/technical/commit-graph-format.txt +++ b/Documentation/technical/commit-graph-format.txt @@ -97,10 +97,10 @@ CHUNK DATA: bit on. The other bits correspond to the position of the last parent. Bloom Filter Index (ID: {'B', 'I', 'D', 'X'}) (N * 4 bytes) [Optional] - * The ith entry, BIDX[i], stores the number of 8-byte word blocks in all - Bloom filters from commit 0 to commit i (inclusive) in lexicographic - order. The Bloom filter for the i-th commit spans from BIDX[i-1] to - BIDX[i] (plus header length), where BIDX[-1] is 0. + * The ith entry, BIDX[i], stores the number of bytes in all Bloom filters + from commit 0 to commit i (inclusive) in lexicographic order. The Bloom + filter for the i-th commit spans from BIDX[i-1] to BIDX[i] (plus header + length), where BIDX[-1] is 0. * The BIDX chunk is ignored if the BDAT chunk is not present. Bloom Filter Data (ID: {'B', 'D', 'A', 'T'}) [Optional] diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 9c5b6f0fac..51a79e63de 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -216,7 +216,7 @@ smart server reply: S: 001e# service=git-upload-pack\n S: 0000 S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n - S: 0042d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n + S: 003fd049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n S: 0000 diff --git a/Documentation/technical/pack-protocol.txt b/Documentation/technical/pack-protocol.txt index d5ce4eea8a..a4573d12ce 100644 --- a/Documentation/technical/pack-protocol.txt +++ b/Documentation/technical/pack-protocol.txt @@ -96,7 +96,7 @@ Basically what the Git client is doing to connect to an 'upload-pack' process on the server side over the Git protocol is this: $ echo -e -n \ - "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" | + "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" | nc -v example.com 9418 @@ -171,9 +171,9 @@ with a version number (if "version=1" is sent as an Extra Parameter), and a listing of each reference it has (all branches and tags) along with the object name that each reference currently points to. - $ echo -e -n "0044git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" | + $ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" | nc -v example.com 9418 - 000aversion 1 + 000eversion 1 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack side-band side-band-64k ofs-delta shallow no-progress include-tag 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration diff --git a/Documentation/technical/protocol-v2.txt b/Documentation/technical/protocol-v2.txt index 7e3766cafb..3996d70891 100644 --- a/Documentation/technical/protocol-v2.txt +++ b/Documentation/technical/protocol-v2.txt @@ -33,6 +33,8 @@ In protocol v2 these special packets will have the following semantics: * '0000' Flush Packet (flush-pkt) - indicates the end of a message * '0001' Delimiter Packet (delim-pkt) - separates sections of a message + * '0002' Message Packet (response-end-pkt) - indicates the end of a response + for stateless connections Initial Client Request ---------------------- |