Re: [PATCH] Notes that tags need to pushed explicitely

[Junio C Hamano <gitster@pobox.com>]

Steffen Daode Nurpmeso <sdaoden@googlemail.com> writes:

> ---

Sign-off?

>  Documentation/git-tag.txt     |    3 ++-
>  Documentation/gittutorial.txt |    1 +
>  2 files changed, 3 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index d82f621..242837f 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -27,7 +27,8 @@ Unless `-f` is given, the tag to be created must not yet exist in the
>  If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
>  creates a 'tag' object, and requires a tag message.  Unless
>  `-m <msg>` or `-F <file>` is given, an editor is started for the user to type
> -in the tag message.
> +in the tag message.  Tag objects can be pushed upstream with
> +linkgit:git-push[1].
>  
>  If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>`
>  are absent, `-a` is implied.

This part of the patch looks sane and uncontroversial.

> diff --git a/Documentation/gittutorial.txt b/Documentation/gittutorial.txt
> index 0982f74..08c0c3a 100644
> --- a/Documentation/gittutorial.txt
> +++ b/Documentation/gittutorial.txt
> @@ -520,6 +520,7 @@ names.  For example:
>  
>  -------------------------------------
>  $ git diff v2.5 HEAD	 # compare the current HEAD to v2.5
> +$ git push v2.5		 # push the tag upstream
>  $ git branch stable v2.5 # start a new branch named "stable" based
>  			 # at v2.5
>  $ git reset --hard HEAD^ # reset your current branch and working

This feels way out of place in the context of the story the tutorial is
telling. These are examples that various ways to spell object names are
used to identify a commit to commands that want to be given commits, but
"git push <tagname>" is _not_ an example of such a command.  Also there is
nothing in the vicinity that pushes a branch that contains the tagged
commit out; if the earlier example to create this v2.5 tag were done to
mark a commit in an existing history you obtained from elsewhere, pushing
the tag alone might make sense, but usually you push branches out and then
optionally tags that refer to commits on those branches.

How about adding an example in git-push section instead?

 Documentation/git-push.txt |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 88acfcd..363d3df 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -371,6 +371,11 @@ git push origin HEAD:master::
 	`origin` repository. This form is convenient to push the current
 	branch without thinking about its local name.
 
+git push origin tag v1.5::
+	Push the `v1.5` tag to the `origin` repository. A newly created
+	tag needs to be published explicitly like this, just like a newly
+	created branch does not get published automatically.
+
 git push origin master:refs/heads/experimental::
 	Create the branch `experimental` in the `origin` repository
 	by copying the current `master` branch.  This form is only