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

From: Julia Evans <julia@jvns.ca>
Date: Sep 15, 2025, 20:00 UTC
Message-ID: <70034c35-8f08-4ee0-9017-7faf6f55ae14@app.fastmail.com>
In-Reply-To: <xmqqjz23l7ci.fsf@gitster.g>

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

That's true. I'll try to explain in more detail why I think terms can be omitted (or why they can't!) in the future. Here we're talking about two terms: refs and objects.

Re "refs": I think "refs" is pretty relevant to `git push`, which is why I left it in (as "or other references", to give readers a hint that a branch is a type of ref/reference).

Re "objects": I can't think right now of a common reason why it would be useful to understand the details of how Git's object database works in the context of "git push", do you have an example? I think `git show` is a much better example of a command where the term "object" is relevant, because you can use `git show` to show blob objects.

Show 15 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?

Will try this:

    Updates one or more branches, tags, or other references in a remote
    repository from your local repository, and sends all necessary data in
   those branches or tags that isn't already on the remote.

The goal there is to make sure the reader knows that git push may need to send a significant amount of data, depending on what's in the new commits you're pushing.

Show 8 quoted lines

>>  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.

Will fix.