From: Julia Evans Date: Tue, 16 Sep 2025 18:46:00 GMT Subject: Re: [PATCH v2 1/4] doc: git-push: clarify intro Message-ID: <3f9f511f-7f9c-4179-85e1-87d76b748db3@app.fastmail.com> In-Reply-To: >> 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.