git/Documentation/git-push.txt, branch v2.40.2

Doc: document push.recurseSubmodules=only

2022-11-14T21:55:50Z

Git learned pushing submodules without pushing the superproject by the user specifying --recurse-submodules=only through 6c656c3fe4 ("submodules: add RECURSE_SUBMODULES_ONLY value", 2016-12-20) and 225e8bf778 ("push: add option to push only submodules", 2016-12-20). For users who use this feature regularly, it is desirable to have an equivalent configuration. It turns out that such a configuration (push.recurseSubmodules=only) is already supported, even though it is neither documented nor mentioned in the commit messages, due to the way the --recurse-submodules=only feature was implemented (a function used to parse --recurse-submodules was updated to support "only", but that same function is used to parse push.recurseSubmodules too). What is left is to document it and test it, which is what this commit does. There is a possible point of confusion when recursing into a submodule that itself has the push.recurseSubmodules=only configuration, because if a repository has only its submodules pushed and not itself, its superproject can never be pushed. Therefore, treat such configurations as being "on-demand", and print a warning message. Signed-off-by: Jonathan Tan Signed-off-by: Taylor Blau

docs: add CONFIGURATION sections that map to a built-in

2022-09-07T16:46:06Z

Add a CONFIGURATION section to the documentation of various built-ins, for those cases where the relevant config/NAME.txt describes configuration that is only used by the relevant built-in documented in git-NAME.txt. Subsequent commits will handle more complex cases. Signed-off-by: Ævar Arnfjörð Bjarmason Reviewed-by: Matheus Tavares Signed-off-by: Junio C Hamano

Merge branch 'ds/gender-neutral-doc'

2021-07-17T00:42:53Z

Update the documentation not to assume users are of certain gender and adds to guidelines to do so. * ds/gender-neutral-doc: *: fix typos comments: avoid using the gender of our users doc: avoid using the gender of other people

doc: avoid using the gender of other people

2021-06-16T02:25:09Z

Using gendered pronouns for an anonymous person applies a gender where none is known and further excludes readers who do not use gendered pronouns. Avoid such examples in the documentation by using "they" or passive voice to avoid the need for a pronoun. Inspired-by: Derrick Stolee Signed-off-by: Felipe Contreras Signed-off-by: Derrick Stolee Signed-off-by: Junio C Hamano

Documentation/git-push.txt: correct configuration typo

2021-03-13T23:41:45Z

In the EXAMPLES section, git-push(1) says that 'git push origin' pushes the current branch to the value of the 'remote.origin.merge' configuration. This wording (which dates back to b2ed944af7 (push: switch default from "matching" to "simple", 2013-01-04)) is incorrect. There is no such configuration as 'remote..merge'. This likely was originally intended to read "branch..merge" instead. Indeed, when 'push.default' is 'simple' (which is the default value, and is applicable in this scenario per "without additional configuration"), setup_push_upstream() dies if the branch's local name does not match 'branch..merge'. Correct this long-standing typo to resolve some recent confusion on the intended behavior of this example. Reported-by: Adam Sharafeddine Reported-by: Fabien Terrani Signed-off-by: Taylor Blau Reviewed-by: Jonathan Nieder Signed-off-by: Junio C Hamano

t, doc: update tests, reference for "--force-if-includes"

2020-10-03T16:59:19Z

Update test cases for the new option, and document its usage and update related references. Update test cases for the new option, and document its usage and update related references. - t/t5533-push-cas.sh: Update test cases for "compare-and-swap" when used along with "--force-if-includes" helps mitigate overwrites when remote refs are updated in the background; allows forced updates when changes from remote are integrated locally. - Documentation: Add reference for the new option, configuration setting ("push.useForceIfIncludes") and advise messages. Signed-off-by: Srinidhi Kaushik Signed-off-by: Junio C Hamano

doc: fix repeated words

2019-08-12T00:40:07Z

Inspired by 21416f0a07 ("restore: fix typo in docs", 2019-08-03), I ran "git grep -E '(\b[a-zA-Z]+) \1\b' -- Documentation/" to find other cases where words were duplicated, e.g. "the the", and in most cases removed one of the repeated words. There were many false positives by this grep command, including deliberate repeated words like "really really" or valid uses of "that that" which I left alone, of course. I also did not correct any of the legitimate, accidentally repeated words in old RelNotes. Signed-off-by: Mark Rushakoff Acked-by: Jeff King Signed-off-by: Junio C Hamano

push doc: document the DWYM behavior pushing to unqualified

2018-11-14T06:27:56Z

Document the DWYM behavior that kicks in when pushing to an unqualified reference. This behavior was added in f88395ac23 ("Renaming push.", 2005-08-03) and f8aae12034 ("push: allow unqualified dest refspecs to DWIM", 2008-04-23), and somewhat documented in bb9fca80ce ("git-push: Update description of refspecs and add examples", 2007-06-09), but has never been fully documented. The closest we got to having documented it was the description in the commit message for f8aae12034, which I've borrowed from in writing this documentation. Let's also refer to this new documentation from the existing documentation we had (added in bb9fca80ce). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

push doc: add spacing between two words

2018-09-19T19:43:50Z

Fix a formatting error introduced in my recently landed fe802bd21e ("push doc: correct lies about how push refspecs work", 2018-08-31). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

push doc: correct lies about how push refspecs work

2018-08-31T21:04:06Z

There's complex rules governing whether a push is allowed to take place depending on whether we're pushing to refs/heads/*, refs/tags/* or refs/not-that/*. See is_branch() in refs.c, and the various assertions in refs/files-backend.c. (e.g. "trying to write non-commit object %s to branch '%s'"). This documentation has never been quite correct, but went downhill after dbfeddb12e ("push: require force for refs under refs/tags/", 2012-11-29) when we started claiming that couldn't be a tag object, which is incorrect. After some of the logic in that patch was changed in 256b9d70a4 ("push: fix "refs/tags/ hierarchy cannot be updated without --force"", 2013-01-16) the docs weren't updated, and we've had some version of documentation that confused whether was a tag or not with whether would accept either an annotated tag object or the commit it points to. This makes the intro somewhat more verbose & complex, perhaps we should have a shorter description here and split the full complexity into a dedicated section. Very few users will find themselves needing to e.g. push blobs or trees to refs/custom-namespace/* (or blobs or trees at all), and that could be covered separately as an advanced topic. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano