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

From: Julia Evans <julia@jvns.ca>
Date: Sep 16, 2025, 18:46 UTC
Message-ID: <3f9f511f-7f9c-4179-85e1-87d76b748db3@app.fastmail.com>
In-Reply-To: <xmqq7bxzcgsj.fsf@gitster.g>

Show 14 quoted lines

>> 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.
>
> Yes.  I do not partculary see the point of deliberately trying to be
> vague by saying "data" (in "all necessary data") instead of "tags,
> commits, trees, and blobs (collectively known as objects), but I
> agree with the stated goal here.

What we're trying to prevent here is readers getting distracted by trying to learn concepts which are not necessary to understand how `git push` works. For example, one user commented:

> I had to look up what the term "object" meant...

It's not necessary to know what an "object" is to understand how to use `git push` (though if you have an example of why it is necessary, I would love to hear it!) If it's not necessary to understand the command, readers should not feel like they have to look it up to understand its documentation.

I think "..., and sends all necessary commits or other objects that aren't already on the remote." might work if we want to add more detail, since it gives users a hint that maybe they can ignore the "or other objects" part if they're not sure what an "object" is.