| Message ID | pull.1265.git.1655697671724.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | rev-parse: documentation adjustment - mention remote tracking with @{u} | expand |
"Tao Klerks via GitGitGadget" <gitgitgadget@gmail.com> writes: > '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: > The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') > - refers to the branch that the branch specified by branchname is set to build on > - top of (configured with `branch.<name>.remote` and > - `branch.<name>.merge`). A missing branchname defaults to the > - current one. These suffixes are also accepted when spelled in uppercase, and > - they mean the same thing no matter the case. > + refers to the remote branch that the branch specified by branchname > + is set to build on top of (configured with `branch.<name>.remote` and > + `branch.<name>.merge`). Let's refrain from inventing confusing new phrases that are not defined in "git help glossary". What is a "remote branch"? I think this is better left as "the branch", to avoid confusion with remote-tracking branch we keep locally. I think a version with a slight tweak, e.g. ... refers to the name of the branch (configured with `branch.<name>.merge`) at the remote (configured with `branch.<name>.remote`) that the branch is set to build on top of. would be OK, though. > ... As `branch.<name>.merge` is the branch path on the > + remote, it is first converted to a local tracking branch (i.e., something in > + `refs/remotes/`). Let's correct it to "remote-tracking branch". But more importantly, the order of explanation feels a bit backwards. Something like... A branch B may be set up to build on top of a branch X (configured with `branch.<name>.merge`) at a remote R (configured with `branch.<name>.remote`). B@{u} refers to the remote-tracking branch for the branch X taken from remote R, typically found at `refs/remotes/R/X`. ... to cover both of the above, perhaps, may flow more naturally? > ... A missing branchname defaults to the current one. These > + suffixes are also accepted when spelled in uppercase, and they mean the same > + thing no matter the case. > '[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: > The suffix '@\{push}' reports the branch "where we would push to" if > `git push` were run while `branchname` was checked out (or the current > - `HEAD` if no branchname is specified). Since our push destination is > - in a remote repository, of course, we report the local tracking branch > - that corresponds to that branch (i.e., something in `refs/remotes/`). > + `HEAD` if no branchname is specified). Like for '@\{upstream\}', we report > + the local tracking branch that corresponds to that remote branch. > + > Here's an example to make it more clear: > + > > base-commit: 5b71c59bc3b9365075e2a175aa7b6f2b0c84ce44
On Tue, Jun 21, 2022 at 6:19 PM Junio C Hamano <gitster@pobox.com> wrote: > > "Tao Klerks via GitGitGadget" <gitgitgadget@gmail.com> writes: > > > ... As `branch.<name>.merge` is the branch path on the > > + remote, it is first converted to a local tracking branch (i.e., something in > > + `refs/remotes/`). > > Let's correct it to "remote-tracking branch". > > But more importantly, the order of explanation feels a bit > backwards. Something like... > > A branch B may be set up to build on top of a branch X > (configured with `branch.<name>.merge`) at a remote R > (configured with `branch.<name>.remote`). B@{u} refers to the > remote-tracking branch for the branch X taken from remote R, > typically found at `refs/remotes/R/X`. > > ... to cover both of the above, perhaps, may flow more naturally? > Looks great, thanks! I feel like a bit of a fraud signing my name to it now, but the important thing is that's a much better improvement than I proposed. Patch v2 coming.
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index f5f17b65a12..33809036f04 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -97,18 +97,19 @@ some output processing may assume ref names in UTF-8. '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') - refers to the branch that the branch specified by branchname is set to build on - top of (configured with `branch.<name>.remote` and - `branch.<name>.merge`). A missing branchname defaults to the - current one. These suffixes are also accepted when spelled in uppercase, and - they mean the same thing no matter the case. + refers to the remote branch that the branch specified by branchname + is set to build on top of (configured with `branch.<name>.remote` and + `branch.<name>.merge`). As `branch.<name>.merge` is the branch path on the + remote, it is first converted to a local tracking branch (i.e., something in + `refs/remotes/`). A missing branchname defaults to the current one. These + suffixes are also accepted when spelled in uppercase, and they mean the same + thing no matter the case. '[<branchname>]@\{push\}', e.g. 'master@\{push\}', '@\{push\}':: The suffix '@\{push}' reports the branch "where we would push to" if `git push` were run while `branchname` was checked out (or the current - `HEAD` if no branchname is specified). Since our push destination is - in a remote repository, of course, we report the local tracking branch - that corresponds to that branch (i.e., something in `refs/remotes/`). + `HEAD` if no branchname is specified). Like for '@\{upstream\}', we report + the local tracking branch that corresponds to that remote branch. + Here's an example to make it more clear: +