path: root/Documentation
diff options
authorJ Wyman <>2017-11-07 16:31:08 (GMT)
committerJunio C Hamano <>2017-11-08 01:18:23 (GMT)
commit9700fae5ee93dd0928cb82afb7b2fd49295e28d2 (patch)
tree388bac3ca43e4393b9b0dc5c3413b15e79f96377 /Documentation
parentcc72385fe350d4d7bc64f84e8817dbdfe27b04fe (diff)
for-each-ref: let upstream/push report the remote ref name
There are times when scripts want to know not only the name of the push branch on the remote, but also the name of the branch as known by the remote repository. An example of this is when a tool wants to push to the very same branch from which it would pull automatically, i.e. the `<remote>` and the `<to>` in `git push <remote> <from>:<to>` would be provided by `%(upstream:remotename)` and `%(upstream:remoteref)`, respectively. This patch offers the new suffix :remoteref for the `upstream` and `push` atoms, allowing to show exactly that. Example: $ cat .git/config ... [remote "origin"] url = fetch = refs/heads/*:refs/remote/origin/* [branch "master"] remote = origin merge = refs/heads/master [branch "develop/with/topics"] remote = origin merge = refs/heads/develop/with/topics ... $ git for-each-ref \ --format='%(push) %(push:remoteref)' \ refs/heads refs/remotes/origin/master refs/heads/master refs/remotes/origin/develop/with/topics refs/heads/develop/with/topics Signed-off-by: J Wyman <> Signed-off-by: Johannes Schindelin <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation')
1 files changed, 9 insertions, 5 deletions
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 39f50bd..174af2c 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -142,8 +142,12 @@ upstream::
encountered. Append `:track,nobracket` to show tracking
information without brackets (i.e "ahead N, behind M").
-Also respects `:remotename` to state the name of the *remote* instead of
-the ref.
+For any remote-tracking branch `%(upstream)`, `%(upstream:remotename)`
+and `%(upstream:remoteref)` refer to the name of the remote and the
+name of the tracked remote ref, respectively. In other words, the
+remote-tracking branch can be updated explicitly and individually by
+using the refspec `%(upstream:remoteref):%(upstream)` to fetch from
Has no effect if the ref does not have tracking information associated
with it. All the options apart from `nobracket` are mutually exclusive,
@@ -152,9 +156,9 @@ but if used together the last option is selected.
The name of a local ref which represents the `@{push}`
location for the displayed ref. Respects `:short`, `:lstrip`,
- `:rstrip`, `:track`, `:trackshort` and `:remotename` options as
- `upstream` does. Produces an empty string if no `@{push}` ref is
- configured.
+ `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`
+ options as `upstream` does. Produces an empty string if no `@{push}`
+ ref is configured.
'*' if HEAD matches current ref (the checked out branch), ' '