Re: [PATCH v2 1/4] doc: git-push: clarify intro

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 12, 2025, 20:54 UTC
Message-ID: <xmqqjz23l7ci.fsf@gitster.g>
In-Reply-To: <270edd2b00e63ef396ae69a9a7e9113a54f0df82.1757703309.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 5 quoted lines

> From: Julia Evans <julia@jvns.ca>
>
> From user feedback, 5 users are unsure what "ref" and/or "objects" means
> in this context. 3 users said they don't know what "complete the refs"
> means.

Well, "this concept I do not understand" from many users is not necessarily mean that the concept does not have to be taught.

Show 5 quoted lines

> -Updates remote refs using local refs, while sending objects
> -necessary to complete the given refs.
>
> +Updates one or more branches, tags, or other references in a remote
> +repository from your local repository.

This is a very good rewrite of the first half of the sentence. Complete loss of the latter is a bit disturbing.

    Send data that records commits, directories, and files
    (collectively called "objects"), and update branches, tags and
    other references at the remote repository, to make newer part of
    the history available there.

or something?

Show 10 quoted lines

> @@ -44,6 +40,9 @@ corresponding upstream branch, but as a safety measure, the push is
>  aborted if the upstream branch does not have the same name as the
>  local one.
>  
> +You can make interesting things happen to a repository
> +every time you push into it, by setting up 'hooks' there.  See
> +documentation for linkgit:git-receive-pack[1].
>  
>  OPTIONS[[OPTIONS]]
>  ------------------

Moving the description of the secondary effect down like this is a welcome change.

The original had two blank lines to separate the previous section and the subsequent OPTIONS section, but now we have only one. It would not make a difference in the rendered output, but having a blank lines between paragraphs and two blank lines between sections, if done consistently, would help reading the documentation in the source form.

Thanks.