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

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

push doc: move mention of "tag " later in the prose

2018-08-31T21:04:06Z

This change will be followed-up with a subsequent change where I'll change both sides of this mention of "tag " to be something that's best read without interruption. To make that change smaller, let's move this mention of "tag " to the end of the "..." section, it's now somewhere in the middle. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

push doc: remove confusing mention of remote merger

2018-08-31T21:04:06Z

Saying that "git push :" won't push a merger of and to is clear from the rest of the context here, so mentioning it is redundant, furthermore the mention of "EXAMPLES below" isn't specific or useful. This phrase was originally added in 149f6ddfb3 ("Docs: Expand explanation of the use of + in git push refspecs.", 2009-02-19), as can be seen in that change the point of the example being cited was to show that force pushing can leave unreferenced commits on the remote. It's enough that we explain that in its own section, it doesn't need to be mentioned here. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano

Merge branch 'ah/misc-doc-updates'

2018-05-23T05:38:23Z

Misc doc fixes. * ah/misc-doc-updates: doc: normalize [--options] to [options] in git-diff doc: add note about shell quoting to revision.txt git-svn: remove ''--add-author-from' for 'commit-diff' doc: add '-d' and '-o' for 'git push' doc: clarify ignore rules for git ls-files doc: align 'diff --no-index' in text and synopsis doc: improve formatting in githooks.txt

Merge branch 'nd/doc-header'

2018-05-23T05:38:22Z

Doc formatting fix. * nd/doc-header: doc: keep first level section header in upper case

doc: add '-d' and '-o' for 'git push'

2018-05-06T09:38:43Z

Add the missing `-o` shortcut for `--push-option` to the synopsis. Add the missing `-d` shortcut for `--delete` in the main section. Signed-off-by: Andreas Heiduk Reviewed-by: Martin Ågren Signed-off-by: Junio C Hamano

doc: keep first level section header in upper case

2018-05-02T08:03:33Z

When formatted as a man page, 1st section header is always in upper case even if we write it otherwise. Make all 1st section headers uppercase to keep it close to the final output. This does affect html since case is kept there, but I still think it's a good idea to maintain a consistent style for 1st section headers. Some sections perhaps should become second sections instead, where case is kept, and for better organization. I will update if anyone has suggestions about this. While at there I also make some header more consistent (e.g. examples vs example) and fix a couple minor things here and there. Signed-off-by: Nguyễn Thái Ngọc Duy Signed-off-by: Junio C Hamano

doc: convert \--option to --option

2018-04-18T03:49:26Z

Rather than using a backslash in \--foo, with or without ''-quoting, write `--foo` for better rendering. As explained in commit 1c262bb7b (doc: convert \--option to --option, 2015-05-13), the backslash is not needed for the versions of AsciiDoc that we support, but is rendered literally by Asciidoctor. Signed-off-by: Martin Ågren