summaryrefslogtreecommitdiff
path: root/Documentation/revisions.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/revisions.txt')
-rw-r--r--Documentation/revisions.txt56
1 files changed, 41 insertions, 15 deletions
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 07961185fe..19314e3b7f 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -61,11 +61,11 @@ some output processing may assume ref names in UTF-8.
'@'::
'@' alone is a shortcut for 'HEAD'.
-'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}'::
+'<refname>@{<date>}', e.g. 'master@\{yesterday\}', 'HEAD@{5 minutes ago}'::
A ref followed by the suffix '@' with a date specification
enclosed in a brace
- pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
- second ago\}' or '\{1979-02-26 18:30:00\}') specifies the value
+ pair (e.g. '\{yesterday\}', '{1 month 2 weeks 3 days 1 hour 1
+ second ago}' or '{1979-02-26 18:30:00}') specifies the value
of the ref at a prior point in time. This suffix may only be
used immediately following a ref name and the ref must have an
existing log ('$GIT_DIR/logs/<ref>'). Note that this looks up the state
@@ -73,7 +73,7 @@ some output processing may assume ref names in UTF-8.
'master' branch last week. If you want to look at commits made during
certain times, see '--since' and '--until'.
-'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
+'<refname>@{<n>}', e.g. 'master@\{1\}'::
A ref followed by the suffix '@' with an ordinal specification
enclosed in a brace pair (e.g. '\{1\}', '\{15\}') specifies
the n-th prior value of that ref. For example 'master@\{1\}'
@@ -82,13 +82,13 @@ some output processing may assume ref names in UTF-8.
immediately following a ref name and the ref must have an existing
log ('$GIT_DIR/logs/<refname>').
-'@\{<n>\}', e.g. '@\{1\}'::
+'@{<n>}', e.g. '@\{1\}'::
You can use the '@' construct with an empty ref part to get at a
reflog entry of the current branch. For example, if you are on
branch 'blabla' then '@\{1\}' means the same as 'blabla@\{1\}'.
-'@\{-<n>\}', e.g. '@\{-1\}'::
- The construct '@\{-<n>\}' means the <n>th branch/commit checked out
+'@{-<n>}', e.g. '@{-1}'::
+ The construct '@{-<n>}' means the <n>th branch/commit checked out
before the current one.
'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
@@ -98,6 +98,31 @@ some output processing may assume ref names in UTF-8.
`branch.<name>.merge`). A missing branchname defaults to the
current one.
+'<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/').
++
+Here's an example to make it more clear:
++
+------------------------------
+$ git config push.default current
+$ git config remote.pushdefault myfork
+$ git checkout -b mybranch origin/master
+
+$ git rev-parse --symbolic-full-name @{upstream}
+refs/remotes/origin/master
+
+$ git rev-parse --symbolic-full-name @{push}
+refs/remotes/myfork/mybranch
+------------------------------
++
+Note in the example that we set up a triangular workflow, where we pull
+from one location and push to another. In a non-triangular workflow,
+'@\{push}' is the same as '@\{upstream}', and there is no need for it.
+
'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
A suffix '{caret}' to a revision parameter means the first parent of
that commit object. '{caret}<n>' means the <n>th parent (i.e.
@@ -114,7 +139,7 @@ some output processing may assume ref names in UTF-8.
'<rev>{caret}1{caret}1{caret}1'. See below for an illustration of
the usage of this form.
-'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}'::
+'<rev>{caret}{<type>}', e.g. 'v0.99.8{caret}\{commit\}'::
A suffix '{caret}' followed by an object type name enclosed in
brace pair means dereference the object at '<rev>' recursively until
an object of type '<type>' is found or the object cannot be
@@ -134,13 +159,13 @@ it does not have to be dereferenced even once to get to an object.
'rev{caret}\{tag\}' can be used to ensure that 'rev' identifies an
existing tag object.
-'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
+'<rev>{caret}{}', e.g. 'v0.99.8{caret}{}'::
A suffix '{caret}' followed by an empty brace pair
means the object could be a tag,
and dereference the tag recursively until a non-tag object is
found.
-'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}'::
+'<rev>{caret}{/<text>}', e.g. 'HEAD^{/fix nasty bug}'::
A suffix '{caret}' to a revision parameter, followed by a brace
pair that contains a text led by a slash,
is the same as the ':/fix nasty bug' syntax below except that
@@ -151,11 +176,12 @@ existing tag object.
A colon, followed by a slash, followed by a text, names
a commit whose commit message matches the specified regular expression.
This name returns the youngest matching commit which is
- reachable from any ref. If the commit message starts with a
- '!' you have to repeat that; the special sequence ':/!',
- followed by something else than '!', is reserved for now.
- The regular expression can match any part of the commit message. To
- match messages starting with a string, one can use e.g. ':/^foo'.
+ reachable from any ref. The regular expression can match any part of the
+ commit message. To match messages starting with a string, one can use
+ e.g. ':/^foo'. The special sequence ':/!' is reserved for modifiers to what
+ is matched. ':/!-foo' performs a negative match, while ':/!!foo' matches a
+ literal '!' character, followed by 'foo'. Any other sequence beginning with
+ ':/!' is reserved for now.
'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
A suffix ':' followed by a path names the blob or tree