path: root/Documentation
diff options
Diffstat (limited to 'Documentation')
14 files changed, 214 insertions, 46 deletions
diff --git a/Documentation/RelNotes/2.27.0.txt b/Documentation/RelNotes/2.27.0.txt
new file mode 100644
index 0000000..7a5c7ff
--- /dev/null
+++ b/Documentation/RelNotes/2.27.0.txt
@@ -0,0 +1,94 @@
+Git 2.27 Release Notes
+Updates since v2.26
+Backward compatibility notes
+ * When "git describe C" finds that commit C is pointed by a signed or
+ annotated tag, which records T as its tagname in the object, the
+ command gives T as its answer. Even if the user renames or moves
+ such a tag from its natural location in the "refs/tags/" hierarchy,
+ "git describe C" would still give T as the answer, but in such a
+ case "git show T^0" would no longer work as expected. There may be
+ nothing at "refs/tags/T" or even worse there may be a different tag
+ instead.
+ Starting from this version, "git describe" will always use the
+ "long" version, as if the "--long" option were given, when giving
+ its output based on such a misplaced tag to work around the problem.
+ * "git pull" issues a warning message until the pull.rebase
+ configuration variable is explicitly given, which some existing
+ users may find annoying---those who prefer not to rebase need to
+ set the variable to false to squelch the warning.
+UI, Workflows & Features
+ * A handful of options to configure SSL when talking to proxies have
+ been added.
+ * Smudge/clean conversion filters are now given more information
+ (e.g. the object of the tree-ish in which the blob being converted
+ appears, in addition to its path, which has already been given).
+ * When "git describe C" finds an annotated tag with tagname A to be
+ the best name to explain commit C, and the tag is stored in a
+ "wrong" place in the refs/tags hierarchy, e.g. refs/tags/B, the
+ command gave a warning message but used A (not B) to describe C.
+ If C is exactly at the tag, the describe output would be "A", but
+ "git rev-parse A^0" would not be equal as "git rev-parse C^0". The
+ behavior of the command has been changed to use the "long" form
+ i.e. A-0-gOBJECTNAME, which is correctly interpreted by rev-parse.
+ * "git pull" learned to warn when no pull.rebase configuration
+ exists, and neither --[no-]rebase nor --ff-only is given (which
+ would result a merge).
+Performance, Internal Implementation, Development Support etc.
+ * The advise API has been revamped to allow more systematic enumeration of
+ advice knobs in the future.
+ * SHA-256 transition continues.
+ * The code to interface with GnuPG has been refactored.
+ * "git stash" has kept an escape hatch to use the scripted version
+ for a few releases, which got stale. It has been removed.
+Fixes since v2.26
+ * The real_path() convenience function can easily be misused; with a
+ bit of code refactoring in the callers' side, its use has been
+ eliminated.
+ (merge 49d3c4b481 am/real-path-fix later to maint).
+ * Update "git p4" to work with Python 3.
+ (merge 6bb40ed20a yz/p4-py3 later to maint).
+ * The mechanism to prevent "git commit" from making an empty commit
+ or amending during an interrupted cherry-pick was broken during the
+ rewrite of "git rebase" in C, which has been corrected.
+ (merge 430b75f720 pw/advise-rebase-skip later to maint).
+ * Fix "git checkout --recurse-submodules" of a nested submodule
+ hierarchy.
+ (merge 846f34d351 pb/recurse-submodules-fix later to maint).
+ * The "--fork-point" mode of "git rebase" regressed when the command
+ was rewritten in C back in 2.20 era, which has been corrected.
+ (merge f08132f889 at/rebase-fork-point-regression-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).
+ (merge 9c688735f6 rs/doc-passthru-fetch-options later to maint).
+ (merge 757c2ba3e2 en/oidset-uninclude-hashmap later to maint).
+ (merge 8312aa7d74 jc/config-tar later to maint).
+ (merge d00a5bdd50 ss/submodule-foreach-cb later to maint).
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 08b13ba..2450589 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -447,6 +447,8 @@ include::config/submodule.txt[]
diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt
index 875f8c8..4e3a5c0 100644
--- a/Documentation/config/feature.txt
+++ b/Documentation/config/feature.txt
@@ -12,9 +12,6 @@ feature.experimental::
setting if you are interested in providing feedback on experimental
features. The new default values are:
-* `pack.useSparse=true` uses a new algorithm when constructing a pack-file
-which can improve `git push` performance in repos with many files.
* `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by
skipping more commits at a time, reducing the number of round trips.
diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index e806033..3968fbb 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -29,6 +29,27 @@ http.proxyAuthMethod::
* `ntlm` - NTLM authentication (compare the --ntlm option of `curl(1)`)
+ The pathname of a file that stores a client certificate to use to authenticate
+ with an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_CERT` environment
+ variable.
+ The pathname of a file that stores a private key to use to authenticate with
+ an HTTPS proxy. Can be overridden by the `GIT_PROXY_SSL_KEY` environment
+ variable.
+ Enable Git's password prompt for the proxy SSL certificate. Otherwise OpenSSL
+ will prompt the user, possibly many times, if the certificate or private key
+ is encrypted. Can be overriden by the `GIT_PROXY_SSL_CERT_PASSWORD_PROTECTED`
+ environment variable.
+ Pathname to the file containing the certificate bundle that should be used to
+ verify the proxy with when using an HTTPS proxy. Can be overriden by the
+ `GIT_PROXY_SSL_CAINFO` environment variable.
Attempt authentication without seeking a username or password. This
can be used to attempt GSS-Negotiate authentication without specifying
diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index 0dac580..837f1b1 100644
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -119,8 +119,8 @@ pack.useSparse::
objects. This can have significant performance benefits when
computing a pack to send a small change. However, it is possible
that extra objects are added to the pack-file if the included
- commits contain certain types of direct renames. Default is `false`
- unless `feature.experimental` is enabled.
+ commits contain certain types of direct renames. Default is
+ `true`.
pack.writeBitmaps (deprecated)::
This is a deprecated synonym for `repack.writeBitmaps`.
diff --git a/Documentation/config/stash.txt b/Documentation/config/stash.txt
index abc7ef4..00eb354 100644
--- a/Documentation/config/stash.txt
+++ b/Documentation/config/stash.txt
@@ -1,17 +1,9 @@
- Set to `false` to use the legacy shell script implementation of
- linkgit:git-stash[1]. Is `true` by default, which means use
- the built-in rewrite of it in C.
-The C rewrite is first included with Git version 2.22 (and Git for Windows
-version 2.19). This option serves as an escape hatch to re-enable the
-legacy version in case any bugs are found in the rewrite. This option and
-the shell script version of linkgit:git-stash[1] will be removed in some
-future release.
-If you find some reason to set this option to `false`, other than
-one-off testing, you should report the behavior difference as a bug in
-Git (see for details).
+ Unused configuration variable. Used in Git versions 2.22 to
+ 2.26 as an escape hatch to enable the legacy shellscript
+ implementation of stash. Now the built-in rewrite of it in C
+ is always used. Setting this will emit a warning, to alert any
+ remaining users that setting this now does nothing.
If this is set to true, the `git stash show` command without an
diff --git a/Documentation/config/tag.txt b/Documentation/config/tag.txt
index 6d9110d..5062a05 100644
--- a/Documentation/config/tag.txt
+++ b/Documentation/config/tag.txt
@@ -15,10 +15,3 @@ tag.gpgSign::
convenient to use an agent to avoid typing your gpg passphrase
several times. Note that this option doesn't affect tag signing
behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options.
- This variable can be used to restrict the permission bits of
- tar archive entries. The default is 0002, which turns off the
- world write bit. The special value "user" indicates that the
- archiving user's umask will be used instead. See umask(2) and
- linkgit:git-archive[1].
diff --git a/Documentation/config/tar.txt b/Documentation/config/tar.txt
new file mode 100644
index 0000000..de8ff48
--- /dev/null
+++ b/Documentation/config/tar.txt
@@ -0,0 +1,6 @@
+ This variable can be used to restrict the permission bits of
+ tar archive entries. The default is 0002, which turns off the
+ world write bit. The special value "user" indicates that the
+ archiving user's umask will be used instead. See umask(2) and
+ linkgit:git-archive[1].
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index a115a1a..00d03ec 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -61,10 +61,8 @@ this option multiple times, one for each matching ref name.
See also the `fetch.negotiationAlgorithm` configuration variable
documented in linkgit:git-config[1].
Show what would be done, without making any changes.
@@ -95,6 +93,7 @@ ifndef::git-pull[]
Write a commit-graph after fetching. This overrides the config
setting `fetch.writeCommitGraph`.
@@ -107,6 +106,7 @@ ifndef::git-pull[]
was cloned with the --mirror option), then they are also
subject to pruning. Supplying `--prune-tags` is a shorthand for
providing the tag refspec.
See the PRUNING section below for more details.
@@ -133,7 +133,6 @@ endif::git-pull[]
behavior for a remote may be specified with the remote.<name>.tagOpt
setting. See linkgit:git-config[1].
When fetching refs listed on the command line, use the
specified refspec (can be given more than once) to map the
@@ -154,6 +153,7 @@ ifndef::git-pull[]
is used (though tags may be pruned anyway if they are also the
destination of an explicit refspec; see `--prune`).
This option controls if and under what conditions new commits of
populated submodules should be fetched too. It can be used as a
@@ -164,6 +164,7 @@ ifndef::git-pull[]
when the superproject retrieves a commit that updates the submodule's
reference to a commit that isn't already in the local submodule
@@ -177,9 +178,11 @@ parallel. To control them independently, use the config settings
Typically, parallel recursive and multi-remote fetches will be faster. By
default fetches are performed sequentially, not in parallel.
Disable recursive fetching of submodules (this has the same effect as
using the `--recurse-submodules=no` option).
If the remote is fetched successfully, pull and add upstream
@@ -188,6 +191,7 @@ default fetches are performed sequentially, not in parallel.
see `branch.<name>.merge` and `branch.<name>.remote` in
Prepend <path> to paths printed in informative messages
such as "Fetching submodule foo". This option is used
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 7889f95..77c6b3d 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -122,6 +122,26 @@ Locations of Marks Files
Relative and non-relative marks may be combined by interweaving
--(no-)-relative-marks with the --(import|export)-marks= options.
+Submodule Rewriting
+ Rewrite the object IDs for the submodule specified by <name> from the values
+ used in the from <file> to those used in the to <file>. The from marks should
+ have been created by `git fast-export`, and the to marks should have been
+ created by `git fast-import` when importing that same submodule.
+<name> may be any arbitrary string not containing a colon character, but the
+same value must be used with both options when specifying corresponding marks.
+Multiple submodules may be specified with different values for <name>. It is an
+error not to use these options in corresponding pairs.
+These options are primarily useful when converting a repository from one hash
+algorithm to another; without them, fast-import will fail if it encounters a
+submodule because it has no way of writing the object ID into the new hash
Performance and Compression Tuning
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 32880aa..adc6adf 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -10,7 +10,7 @@ SYNOPSIS
'git init' [-q | --quiet] [--bare] [--template=<template_directory>]
- [--separate-git-dir <git dir>]
+ [--separate-git-dir <git dir>] [--object-format=<format]
[--shared[=<permissions>]] [directory]
@@ -48,6 +48,11 @@ Only print error and warning messages; all other output will be suppressed.
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
current working directory.
+Specify the given object format (hash algorithm) for the repository. The valid
+values are 'sha1' and (if enabled) 'sha256'. 'sha1' is the default.
Specify the directory from which templates will be used. (See the "TEMPLATE
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index fecdf26..eaa2f2a 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -14,7 +14,7 @@ SYNOPSIS
[--local] [--incremental] [--window=<n>] [--depth=<n>]
[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
[--stdout [--filter=<filter-spec>] | base-name]
- [--shallow] [--keep-true-parents] [--sparse] < object-list
+ [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list
@@ -196,14 +196,16 @@ depth is 4095.
Add --no-reuse-object if you want to force a uniform compression
level on all data no matter the source.
- Use the "sparse" algorithm to determine which objects to include in
+ Toggle the "sparse" algorithm to determine which objects to include in
the pack, when combined with the "--revs" option. This algorithm
only walks trees that appear in paths that introduce new objects.
This can have significant performance benefits when computing
a pack to send a small change. However, it is possible that extra
objects are added to the pack-file if the included commits contain
- certain types of direct renames.
+ certain types of direct renames. If this option is not included,
+ it defaults to the value of `pack.useSparse`, which is true unless
+ otherwise specified.
Create a "thin" pack by omitting the common objects between a
diff --git a/Documentation/git.txt b/Documentation/git.txt
index b0672bd..9d6769e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -493,6 +493,12 @@ double-quotes and respecting backslash escapes. E.g., the value
details. This variable has lower precedence than other path
+ 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
+ is used instead. The default is "sha1".
Git Commits
diff --git a/Documentation/howto/maintain-git.txt b/Documentation/howto/maintain-git.txt
index ca43787..73be8b4 100644
--- a/Documentation/howto/maintain-git.txt
+++ b/Documentation/howto/maintain-git.txt
@@ -154,15 +154,17 @@ by doing the following:
- Anything unobvious that is applicable to 'master' (in other
words, does not depend on anything that is still in 'next'
and not in 'master') is applied to a new topic branch that
- is forked from the tip of 'master'. This includes both
+ is forked from the tip of 'master' (or the last feature release,
+ which is a bit older than 'master'). This includes both
enhancements and unobvious fixes to 'master'. A topic
branch is named as ai/topic where "ai" is two-letter string
named after author's initial and "topic" is a descriptive name
of the topic (in other words, "what's the series is about").
- An unobvious fix meant for 'maint' is applied to a new
- topic branch that is forked from the tip of 'maint'. The
- topic is named as ai/maint-topic.
+ topic branch that is forked from the tip of 'maint' (or the
+ oldest and still relevant maintenance branch). The
+ topic may be named as ai/maint-topic.
- Changes that pertain to an existing topic are applied to
the branch, but:
@@ -174,24 +176,40 @@ by doing the following:
- Replacement patches to an existing topic are accepted only
for commits not in 'next'.
- The above except the "replacement" are all done with:
+ The initial round is done with:
$ git checkout ai/topic ;# or "git checkout -b ai/topic master"
$ git am -sc3 mailbox
- while patch replacement is often done by:
+ and replacing an existing topic with subsequent round is done with:
- $ git format-patch ai/topic~$ ;# export existing
+ $ git checkout ;# try to reapply to the same base
+ $ git am -sc3 mailbox
+ to prepare the new round on a detached HEAD, and then
+ $ git range-diff @{-1}...
+ $ git diff @{-1}
- then replace some parts with the new patch, and reapplying:
+ to double check what changed since the last round, and finally
- $ git checkout ai/topic
- $ git reset --hard ai/topic~$n
- $ git am -sc3 -s 000*.txt
+ $ git checkout -B @{-1}
+ to conclude (the last step is why a topic already in 'next' is
+ not replaced but updated incrementally).
+ Whether it is the initial round or a subsequent round, the topic
+ may not build even in isolation, or may break the build when
+ merged to integration branches due to bugs. There may already
+ be obvious and trivial improvements suggested on the list. The
+ maintainer often adds an extra commit, with "SQUASH???" in its
+ title, to fix things up, before publishing the integration
+ branches to make it usable by other developers for testing.
+ These changes are what the maintainer is not 100% committed to
+ (trivial typofixes etc. are often squashed directly into the
+ patches that need fixing, without being applied as a separate
+ "SQUASH???" commit), so that they can be removed easily as needed.
- The full test suite is always run for 'maint' and 'master'
- after patch application; for topic branches the tests are run
- as time permits.
- Merge maint to master as needed:
@@ -371,6 +389,14 @@ Some observations to be made.
be included in the next feature release. Being in the
'master' branch typically is.
+ * Due to the nature of "SQUASH???" fix-ups, if the original author
+ agrees with the suggested changes, it is OK to squash them to
+ appropriate patches in the next round (when the suggested change
+ is small enough, the author should not even bother with
+ "Helped-by"). It is also OK to drop them from the next round
+ when the original author does not agree with the suggestion, but
+ the author is expected to say why somewhere in the discussion.