Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 23 additions & 20 deletions Documentation/git-push.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -19,31 +19,34 @@ SYNOPSIS
DESCRIPTION
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "D. Ben Knoble" wrote (reply to this):

On Tue, Aug 26, 2025 at 4:40 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> - Users don't understand what a "ref" is, expand it
[snip]
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index d1978650d60a..e73b64f61fd0 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -19,12 +19,8 @@ SYNOPSIS
>  DESCRIPTION
>  -----------
>
> -Updates remote refs using local refs, while sending objects
> -necessary to complete the given refs.
> -
> -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].
> +Updates one or more branches, tags, or other references in a remote
> +repository from your local repository.

Considering the glossary entry[1] is for "ref", not "reference", what about

(a) linking to the glossary (is this possible?), and/or
(b) saying something like

    Updates one or more branches, tags, or other references (called "refs")…

?

[1]: "git help glossary", or
https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-ref

>
>  When the command line does not specify where to push with the
>  `<repository>` argument, `branch.*.remote` configuration for the
> @@ -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].

Seems reasonable to me. Thanks!

-- 
D. Ben Knoble

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"D. Ben Knoble" <[email protected]> writes:

>> +Updates one or more branches, tags, or other references in a remote
>> +repository from your local repository.
>
> Considering the glossary entry[1] is for "ref", not "reference", what about
>
> (a) linking to the glossary (is this possible?), and/or
> (b) saying something like
>
>     Updates one or more branches, tags, or other references (called "refs")…
>
> ?
>
> [1]: "git help glossary", or
> https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-ref

Both sound good ideas.  We should make sure that readers are aware
of the glossary by linking into it from more places. 

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Julia Evans" wrote (reply to this):

> Considering the glossary entry[1] is for "ref", not "reference", what about
>
> (a) linking to the glossary (is this possible?), and/or

I like this idea. Over on the HTML docs side
(https://github.com/git/git-scm.com/pull/2040)
I've been working on a way to show an interactive tooltip from the glossary when
people hover over "jargon" terms. The goal there is to make the glossary a lot
more discoverable.

Right now it only works for terms inside angle brackets (like `<ref>`), but
I've been thinking of adding a `linkgitglossary:` AsciiDoc macro or something
(similar to `linkgit:`) to link terms to specific glossary entries. It's hard
to tell what that should do in the terminal version of the man pages 
(maybe nothing!), but it could make the HTML versions a lot easier to use.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "D. Ben Knoble" wrote (reply to this):

+cc Junio due to his reply to my reply

On Thu, Aug 28, 2025 at 1:48 PM Julia Evans <[email protected]> wrote:
>
> > Considering the glossary entry[1] is for "ref", not "reference", what about
> >
> > (a) linking to the glossary (is this possible?), and/or
>
> I like this idea. Over on the HTML docs side
> (https://github.com/git/git-scm.com/pull/2040)
> I've been working on a way to show an interactive tooltip from the glossary when
> people hover over "jargon" terms. The goal there is to make the glossary a lot
> more discoverable.
>
> Right now it only works for terms inside angle brackets (like `<ref>`), but
> I've been thinking of adding a `linkgitglossary:` AsciiDoc macro or something
> (similar to `linkgit:`) to link terms to specific glossary entries. It's hard
> to tell what that should do in the terminal version of the man pages
> (maybe nothing!), but it could make the HTML versions a lot easier to use.

I think we could so similar to existing "linkgit:" and expand to
"gitglossary(7)" (or "git help glossary")

-- 
D. Ben Knoble

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this):

On Thu, Aug 28, 2025, at 18:18, Junio C Hamano wrote:
> "D. Ben Knoble" <[email protected]> writes:
>
>>> +Updates one or more branches, tags, or other references in a remote
>>> +repository from your local repository.
>>
>> Considering the glossary entry[1] is for "ref", not "reference", what about
>>
>> (a) linking to the glossary (is this possible?), and/or
>> (b) saying something like
>>
>>     Updates one or more branches, tags, or other references (called "refs")…
>>
>> ?
>>
>> [1]: "git help glossary", or
>> https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-ref
>
> Both sound good ideas.  We should make sure that readers are aware
> of the glossary by linking into it from more places.

I wonder if the essential commands that everyone is likely to use ought
to have footnotes which point to the glossary for all the jargon.  That
way people can skim past them if they don’t care, especially if there is
(say) at most one footnote after every sentence.

I imagine you could get a lot of parentheticals without this approach.

-- 
Kristoffer Haugsbakk

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans via GitGitGadget" <[email protected]> writes:

> From: Julia Evans <[email protected]>
>
> 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.

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

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Julia Evans" wrote (reply to this):

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

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

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans" <[email protected]> writes:

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

I have (and I didn't have) no issues with "refs" -> "references".

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Julia Evans" wrote (reply to this):

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

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Ben Knoble wrote (reply to this):

> Le 16 sept. 2025 à 14:46, Julia Evans <[email protected]> a écrit :
> 
> 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.

Nit, without wading into the above discussion: shouldn’t that be « and other objects »?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Ben Knoble <[email protected]> writes:

>> Le 16 sept. 2025 à 14:46, Julia Evans <[email protected]> a écrit :
>> 
>> 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.
>
> Nit, without wading into the above discussion: shouldn’t that be « and other objects »?

You could push a tag that points at a blob, so it is possible that
the push transfers only "other objects", but "necessary commits and
other objects" would naturally cover the case where the number of
necessary commits is zero ;-), so I tend to agree that *and* would
read better in that sentence.

But if we really want to do the progressive disclosure, I am OK with
the idea that hiding the details behind a vague words like "transfer
data necessary for updated branches" without saying what these data
are would work OK.

Thanks.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Junio C Hamano <[email protected]> writes:

> "Julia Evans" <[email protected]> writes:
>
>> 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).
>
> I have (and I didn't have) no issues with "refs" -> "references".
>
>> 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.

Let me change my mind here.

If you are trying to avoid overwhelming the readers by carefully
trying not to write things that do not have to be said at each point
in the teaching, I do agree that the deliberate vagueness I
mentioned above is a good idea.  You seem to have better "taste" of
knowing what the right amount of detail to give, a lot better than I
do.

Please keep these goodness coming.

Thanks.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Julia Evans" wrote (reply to this):

> Let me change my mind here.
>
> If you are trying to avoid overwhelming the readers by carefully
> trying not to write things that do not have to be said at each point
> in the teaching, I do agree that the deliberate vagueness I
> mentioned above is a good idea.  You seem to have better "taste" of
> knowing what the right amount of detail to give, a lot better than I
> do.
>
> Please keep these goodness coming.

Thanks so much for the encouragement, it really helps a lot. I've
appreciated your detailed reviews.

let's keep going!
- Julia

-----------

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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans via GitGitGadget" <[email protected]> writes:

> From: Julia Evans <[email protected]>
>
> Signed-off-by: Julia Evans <[email protected]>
>
> Be clearer about what we're describing ("which repository" instead of
> "what to push"), and start with a positive "try X, then Y, then Z"
> instead of a negative ("if X is not specified..").

Since I like this simple rule so much, if it is generally applicable
everywhere, I'd like to have it or a variant of it in one of our
developer facing documentation as a tip to write better
documentation.


> Signed-off-by: Julia Evans <[email protected]>

There is some funny ordering problem with the commit log body and
sign-off.

> ---
>  Documentation/git-push.adoc | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index e73b64f61fd0..5c934486c33d 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -22,10 +22,10 @@ DESCRIPTION
>  Updates one or more branches, tags, or other references in a remote
>  repository from your local repository.
>  
> -When the command line does not specify where to push with the
> -`<repository>` argument, `branch.*.remote` configuration for the
> -current branch is consulted to determine where to push.  If the
> -configuration is missing, it defaults to 'origin'.
> +To decide which repository to push to, Git uses the `<repository>`
> +argument (for example `git push dev`), then if that's not specified the
> +`branch.*.remote` configuration for the current branch, and then defaults
> +to `origin`.

Very nicely done.

>  When the command line does not specify what to push with `<refspec>...`
>  arguments or `--all`, `--mirror`, `--tags` options, the command finds

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans via GitGitGadget" <[email protected]> writes:

> -When the command line does not specify where to push with the
> -`<repository>` argument, `branch.*.remote` configuration for the
> -current branch is consulted to determine where to push.  If the
> -configuration is missing, it defaults to 'origin'.
> +To decide which repository to push to, Git uses the `<repository>`
> +argument (for example `git push dev`), then if that's not specified the
> +upstream configuration for the current branch, and then defaults
> +to `origin`.

OK.  Much less awkward and much clearer.  Nice.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Julia Evans via GitGitGadget" <[email protected]> writes:

> From: Julia Evans <[email protected]>
>
> Be clearer about what we're describing ("which repository" instead of
> "what to push"), and start with a positive "try X, then Y, then Z"

I forgot to say, even though I did spot:

    "what to push" -> "where to push"

"what to push" is the topic of the next patch.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Julia Evans" wrote (reply to this):

>> Be clearer about what we're describing ("which repository" instead of
>> "what to push"), and start with a positive "try X, then Y, then Z"
>
> I forgot to say, even though I did spot:
>
>     "what to push" -> "where to push"
>
> "what to push" is the topic of the next patch.

Thanks for spotting that. Will fix.

repository from your local repository, and sends all necessary data
that isn't already on the remote.

To decide which repository to push to, Git uses the `<repository>`
argument (for example `git push dev`), then if that's not specified the
upstream configuration for the current branch, and then defaults
to `origin`.

To decide which branches, tags, or other refs to push, Git uses
(in order of precedence):

1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
or the `--all`, `--mirror`, or `--tags` options
2. The `remote.*.push` configuration for the repository being pushed to
3. The `push.default` configuration. The default is `push.default=simple`,
which will push to a branch with the same name as the current branch.
See the CONFIGURATION section below for more on `push.default`.

As a safety measure, `git push` may fail if you haven't set an upstream
for the current branch, depending on what `push.default` is set to.
See the UPSTREAM BRANCHES section below for more on how to set and
use upstreams.

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

When the command line does not specify where to push with the
`<repository>` argument, `branch.*.remote` configuration for the
current branch is consulted to determine where to push. If the
configuration is missing, it defaults to 'origin'.

When the command line does not specify what to push with `<refspec>...`
arguments or `--all`, `--mirror`, `--tags` options, the command finds
the default `<refspec>` by consulting `remote.*.push` configuration,
and if it is not found, honors `push.default` configuration to decide
what to push (See linkgit:git-config[1] for the meaning of `push.default`).

When neither the command-line nor the configuration specifies what to
push, the default behavior is used, which corresponds to the `simple`
value for `push.default`: the current branch is pushed to the
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.


OPTIONS[[OPTIONS]]
------------------
Expand Down
44 changes: 41 additions & 3 deletions Documentation/urls-remotes.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,44 @@ git push uses:
HEAD:refs/heads/<head>
------------




UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
--------------------------------------

Branches in Git can optionally have an upstream remote branch.
Git defaults to using the upstream branch for remote operations, for example:

* It's the default for `git pull` or `git fetch` with no arguments
* It's the default for `git push` with no arguments, with some exceptions.
For example, you can use the `branch.<name>.pushRemote` option to push
to a different remote than you pull from, and by default with
`push.default=simple` the upstream branch you configure must have
the same name.
* Various commands, including `git checkout` and `git status`, will
show you how many commits have been added to your current branch and
the upstream since you forked from it, for example "Your branch and
'origin/main' have diverged, and have 2 and 3 different commits each
respectively"

The upstream is stored in `.git/config`, in the "remote" and "merge"
fields. For example, if `main`'s upstream is `origin/main`:

[branch "main"]
remote = origin
merge = refs/heads/main

You can set an upstream branch explicitly with
`git push --set-upstream <remote> <branch>` or `git branch --track`,
but Git will often automatically set the upstream for you, for example:

* When you clone a repository, Git will automatically set the upstream
for the default branch.
* If you have the `push.autoSetupRemote` configuration option set,
`git push` will automatically set the upstream the first time you push
a branch.
* Checking out a remote-tracking branch with `git checkout <branch>`
will automatically create a local branch with that name and set
the upstream to the remote branch.

[NOTE]
Upstream branches are sometimes referred to as "tracking information",
as in "set the branch's tracking information".
Loading