diff options
Diffstat (limited to 'Documentation/revisions.txt')
| -rw-r--r-- | Documentation/revisions.txt | 27 |
1 files changed, 17 insertions, 10 deletions
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 991fcd8f3f..d477b3f6bc 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -2,13 +2,13 @@ SPECIFYING REVISIONS -------------------- A revision parameter '<rev>' typically, but not necessarily, names a -commit object. It uses what is called an 'extended SHA1' +commit object. It uses what is called an 'extended SHA-1' syntax. Here are various ways to spell object names. The ones listed near the end of this list name trees and blobs contained in a commit. '<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e':: - The full SHA1 object name (40-byte hexadecimal string), or + The full SHA-1 object name (40-byte hexadecimal string), or a leading substring that is unique within the repository. E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both name the same commit object if there is no other object in @@ -23,7 +23,7 @@ blobs contained in a commit. A symbolic ref name. E.g. 'master' typically means the commit object referenced by 'refs/heads/master'. If you happen to have both 'heads/master' and 'tags/master', you can - explicitly say 'heads/master' to tell git which one you mean. + explicitly say 'heads/master' to tell Git which one you mean. When ambiguous, a '<refname>' is disambiguated by taking the first match in the following rules: @@ -55,7 +55,7 @@ when you run `git cherry-pick`. + Note that any of the 'refs/*' cases above may come either from the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. -While the ref name encoding is unspecified, UTF-8 is prefered as +While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: @@ -88,10 +88,10 @@ some output processing may assume ref names in UTF-8. The construct '@\{-<n>\}' means the <n>th branch checked out before the current one. -'<refname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: - The suffix '@\{upstream\}' to a ref (short form '<refname>@\{u\}') refers to - the branch the ref is set to build on top of. A missing ref defaults - to the current branch. +'<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. A missing branchname defaults to the current one. '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of @@ -116,6 +116,11 @@ some output processing may assume ref names in UTF-8. object of that type is found or the object cannot be dereferenced anymore (in which case, barf). '<rev>{caret}0' is a short-hand for '<rev>{caret}\{commit\}'. ++ +'rev{caret}\{object\}' can be used to make sure 'rev' names an +object that exists, without requiring 'rev' to be a tag, and +without dereferencing 'rev'; because a tag is already an object, +it does not have to be dereferenced even once to get to an object. '<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}':: A suffix '{caret}' followed by an empty brace pair @@ -239,11 +244,13 @@ To summarize: '<rev1>..<rev2>':: Include commits that are reachable from <rev2> but exclude - those that are reachable from <rev1>. + those that are reachable from <rev1>. When either <rev1> or + <rev2> is omitted, it defaults to 'HEAD'. '<rev1>\...<rev2>':: Include commits that are reachable from either <rev1> or - <rev2> but exclude those that are reachable from both. + <rev2> but exclude those that are reachable from both. When + either <rev1> or <rev2> is omitted, it defaults to 'HEAD'. '<rev>{caret}@', e.g. 'HEAD{caret}@':: A suffix '{caret}' followed by an at sign is the same as listing |