commit 482b0b83833675d8c750a996c3a9db1fb99e1e8d from: Stefan Sperling via: Thomas Adam date: Wed Jul 19 20:02:02 2023 UTC reorder some paragraphs in got.1 to make default behaviour easier to spot commit - fb8851205d3a6b7f0c457b2091c3b335d0f7e4e3 commit + 482b0b83833675d8c750a996c3a9db1fb99e1e8d blob - 6850047d13f8afebd1c2166d9b5f9d3e689eab3b blob + d52a563d452f3ee2fe440e9ab63d1a2b3ddb551f --- got/got.1 +++ got/got.1 @@ -566,7 +566,12 @@ reference will be used. Check out files from the specified .Ar commit on the selected branch. -The expected argument is a commit ID SHA1 hash or an existing reference +If this option is not specified, the most recent commit on the selected +branch will be used. +.Pp +The expected +.Ar commit +argument is a commit ID SHA1 hash or an existing reference or tag name which will be resolved to a commit ID. An abbreviated hash argument will be expanded to a full SHA1 hash automatically, provided the abbreviation is unique. @@ -607,8 +612,6 @@ is implicitly appended is equivalent to .Sy :head:-1 .Pc . -If this option is not specified, the most recent commit on the selected -branch will be used. .Pp If the specified .Ar commit @@ -732,49 +735,52 @@ or could be discarded with .It Fl c Ar commit Update the work tree to the specified .Ar commit . -The expected argument is a commit ID SHA1 hash or an existing reference -or tag name which will be resolved to a commit ID. -An abbreviated hash argument will be expanded to a full SHA1 hash -automatically, provided the abbreviation is unique. -.Pp -The special -.Ar commit -keywords -.Qq :base -and -.Qq :head -can also be used to represent the work tree's base commit -and branch head, respectively. -Keywords and reference names may be appended with -.Qq :+ -or -.Qq :- -modifiers and an optional integer N to denote the -Nth descendant or antecedent, respectively, by first parent traversal; -for example, -.Sy :head:-2 -denotes the work tree branch head's 2nd generation ancestor, and -.Sy :base:+4 -denotes the 4th generation descendant of the work tree's base commit. -Similarly, -.Sy foo:-3 -will denote the 3rd generation ancestor of the commit resolved by the -.Qq foo -reference. -If an integer does not follow the -.Qq :+ -or -.Qq :- -modifier, a -.Qq 1 -is implicitly appended -.Po e.g., -.Sy :head:- -is equivalent to -.Sy :head:-1 -.Pc . If this option is not specified, the most recent commit on the work tree's branch will be used. +.Pp +The expected +.Ar commit +argument is a commit ID SHA1 hash or an existing reference +or tag name which will be resolved to a commit ID. +An abbreviated hash argument will be expanded to a full SHA1 hash +automatically, provided the abbreviation is unique. +.Pp +The special +.Ar commit +keywords +.Qq :base +and +.Qq :head +can also be used to represent the work tree's base commit +and branch head, respectively. +Keywords and reference names may be appended with +.Qq :+ +or +.Qq :- +modifiers and an optional integer N to denote the +Nth descendant or antecedent, respectively, by first parent traversal; +for example, +.Sy :head:-2 +denotes the work tree branch head's 2nd generation ancestor, and +.Sy :base:+4 +denotes the 4th generation descendant of the work tree's base commit. +Similarly, +.Sy foo:-3 +will denote the 3rd generation ancestor of the commit resolved by the +.Qq foo +reference. +If an integer does not follow the +.Qq :+ +or +.Qq :- +modifier, a +.Qq 1 +is implicitly appended +.Po e.g., +.Sy :head:- +is equivalent to +.Sy :head:-1 +.Pc . .It Fl q Silence progress output. .El @@ -928,7 +934,12 @@ By default, 3 lines of context are shown. .It Fl c Ar commit Start traversing history at the specified .Ar commit . -The expected argument is a commit ID SHA1 hash or an existing reference +If this option is not specified, default to the work tree's current branch +if invoked in a work tree, or to the repository's HEAD reference. +.Pp +The expected +.Ar commit +argument is a commit ID SHA1 hash or an existing reference or tag name which will be resolved to a commit ID. An abbreviated hash argument will be expanded to a full SHA1 hash automatically, provided the abbreviation is unique. @@ -972,8 +983,6 @@ appended is equivalent to .Sy :base:+1 .Pc . -If this option is not specified, default to the work tree's current branch -if invoked in a work tree, or to the repository's HEAD reference. .It Fl d Display diffstat of changes introduced in each commit. Cannot be used with the @@ -1092,51 +1101,6 @@ When used only once, show differences between the spec and its first parent commit. When used twice, show differences between the two specified commits. .Pp -The expected argument is a commit ID SHA1 hash or an existing reference -or tag name which will be resolved to a commit ID. -An abbreviated hash argument will be expanded to a full SHA1 hash -automatically, provided the abbreviation is unique. -.Pp -The special -.Ar commit -keywords -.Qq :base -and -.Qq :head -can also be used to represent the work tree's base commit -and branch head, respectively. -The former is only valid if invoked in a work tree, while the latter will -resolve to the tip of the work tree's current branch if invoked in a -work tree, otherwise it will resolve to the repository's HEAD reference. -Keywords and references may be appended with -.Qq :+ -or -.Qq :- -modifiers and an optional integer N to denote the -Nth descendant or antecedent, respectively, by first parent traversal; -for example, -.Sy :head:-2 -denotes the HEAD reference's 2nd generation ancestor, and -.Sy :base:+4 -denotes the 4th generation descendant of the work tree's base commit. -Similarly, -.Sy baz:+8 -will denote the 8th generation descendant of the commit resolved by the -.Qq baz -reference. -If an integer does not follow the -.Qq :+ -or -.Qq :- -modifier, a -.Qq 1 -is implicitly appended -.Po e.g., -.Sy :head:- -is equivalent to -.Sy :head:-1 -.Pc . -.Pp If the .Fl c option is used, all non-option arguments will be interpreted as paths. @@ -1144,6 +1108,53 @@ If one or more such .Ar path arguments are provided, only show differences for the specified paths. .Pp +The expected +.Ar commit +argument is a commit ID SHA1 hash or an existing reference +or tag name which will be resolved to a commit ID. +An abbreviated hash argument will be expanded to a full SHA1 hash +automatically, provided the abbreviation is unique. +.Pp +The special +.Ar commit +keywords +.Qq :base +and +.Qq :head +can also be used to represent the work tree's base commit +and branch head, respectively. +The former is only valid if invoked in a work tree, while the latter will +resolve to the tip of the work tree's current branch if invoked in a +work tree, otherwise it will resolve to the repository's HEAD reference. +Keywords and references may be appended with +.Qq :+ +or +.Qq :- +modifiers and an optional integer N to denote the +Nth descendant or antecedent, respectively, by first parent traversal; +for example, +.Sy :head:-2 +denotes the HEAD reference's 2nd generation ancestor, and +.Sy :base:+4 +denotes the 4th generation descendant of the work tree's base commit. +Similarly, +.Sy baz:+8 +will denote the 8th generation descendant of the commit resolved by the +.Qq baz +reference. +If an integer does not follow the +.Qq :+ +or +.Qq :- +modifier, a +.Qq 1 +is implicitly appended +.Po e.g., +.Sy :head:- +is equivalent to +.Sy :head:-1 +.Pc . +.Pp Cannot be used together with the .Fl P option. @@ -1397,9 +1408,7 @@ are as follows: .It Fl c Ar commit Make a newly created branch reference point at the specified .Ar commit . -The expected -.Ar commit -argument is a commit ID SHA1 hash or an existing reference +The expected argument is a commit ID SHA1 hash or an existing reference or tag name which will be resolved to a commit ID. .Pp The special @@ -1764,49 +1773,21 @@ are as follows: Attempt to locate files within the specified .Ar commit for use as a merge-base for 3-way merges. -The expected -.Ar commit -argument is a commit ID SHA1 hash or an existing reference -or tag name which will be resolved to a commit ID. -An abbreviated hash argument will be expanded to a full SHA1 hash -automatically, provided the abbreviation is unique. .Pp -The special -.Ar commit -keywords -.Qq :base -and -.Qq :head -can also be used to represent the work tree's base commit -and branch head, respectively. -Keywords and references may be appended with -.Qq :+ +If the +.Fl c +option is not used then +.Cm got patch +will attempt to locate merge-bases via object IDs found in +.Ar patchfile +meta-data, such as produced by +.Cm got diff or -.Qq :- -modifiers and an optional integer N to denote the -Nth descendant or antecedent by first parent traversal, respectively; -for example, -.Sy :head:-2 -denotes the work tree branch head's 2nd generation ancestor, and -.Sy :base:+4 -denotes the 4th generation descendant of the work tree's base commit. -Similarly, -.Sy flan:+3 -will denote the 3rd generation descendant of the commit resolved by the -.Qq flan -reference. -A -.Qq :+ -or -.Qq :- -modifier without a trailing integer has an implicit -.Qq 1 -appended -.Po e.g., -.Sy :base:+ -is equivalent to -.Sy :base:+1 -.Pc . +.Xr git-diff 1 . +Use of the +.Fl c +option is only recommended in the absence of such meta-data. +.Pp Ideally, the specified .Ar commit should contain versions of files which the changes contained in the @@ -1818,24 +1799,54 @@ If the option is used then leading path components will be stripped before paths are looked up in the repository. .Pp -If the -.Fl c -option is not used then -.Cm got patch -will attempt to locate merge-bases via object IDs found in -.Ar patchfile -meta-data, such as produced by -.Cm got diff -or -.Xr git-diff 1 . -Use of the -.Fl c -option is only recommended in the absence of such meta-data. -.Pp In case no merge-base is available for a file, changes will be applied without doing a 3-way merge. Changes which do not apply cleanly may then be rejected entirely, rather than producing merge conflicts in the patched target file. +.Pp +The expected +.Ar commit +argument is a commit ID SHA1 hash or an existing reference +or tag name which will be resolved to a commit ID. +An abbreviated hash argument will be expanded to a full SHA1 hash +automatically, provided the abbreviation is unique. +.Pp +The special +.Ar commit +keywords +.Qq :base +and +.Qq :head +can also be used to represent the work tree's base commit +and branch head, respectively. +Keywords and references may be appended with +.Qq :+ +or +.Qq :- +modifiers and an optional integer N to denote the +Nth descendant or antecedent by first parent traversal, respectively; +for example, +.Sy :head:-2 +denotes the work tree branch head's 2nd generation ancestor, and +.Sy :base:+4 +denotes the 4th generation descendant of the work tree's base commit. +Similarly, +.Sy flan:+3 +will denote the 3rd generation descendant of the commit resolved by the +.Qq flan +reference. +A +.Qq :+ +or +.Qq :- +modifier without a trailing integer has an implicit +.Qq 1 +appended +.Po e.g., +.Sy :base:+ +is equivalent to +.Sy :base:+1 +.Pc . .It Fl n Do not make any modifications to the work tree. This can be used to check whether a patch would apply without issues.