2 .\" Copyright (c) 2017 Martin Pieuchot
3 .\" Copyright (c) 2018, 2019, 2020 Stefan Sperling
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
30 is a version control system which stores the history of tracked files
31 in a Git repository, as used by the Git version control system.
32 This repository format is described in
33 .Xr git-repository 5 .
38 version control system because every copy of a repository is writeable.
39 Modifications made to files can be synchronized between repositories
44 must be checked out from the repository for modification.
45 Checked out files are stored in a
47 which can be placed at an arbitrary directory in the filesystem hierarchy.
48 The on-disk format of this work tree is described in
53 utility provides global and command-specific options.
54 Global options must precede the command name, and are as follows:
55 .Bl -tag -width tenletters
57 Display usage information and exit immediately.
59 Display program version and exit immediately.
64 utility only provides commands needed to perform version control tasks.
65 Commands needed for repository maintenance tasks are provided by
67 Git repository server functionality is provided by
69 A repository interface for web browsers is provided by
71 An interactive repository interface for the terminal is provided by
77 .Bl -tag -width checkout
78 .It Cm init Oo Fl b Ar branch Oc Ar repository-path
79 Create a new empty repository at the specified
84 the new repository must be populated before
89 command can be used to populate the new repository with data from
91 Alternatively, on a server running
93 the new repository can be made available to
97 clients by adding the repository to
101 Clients may then clone the new repository from the server, populate the cloned
102 repository, and then populate the new repository on the server via
112 Make the repository's HEAD reference point to the specified
114 instead of the default branch
120 command is equivalent to
128 .Op Fl r Ar repository-path
132 Create an initial commit in a repository from the file hierarchy
135 The created commit will not have any parent commits, i.e. it will be a
137 Also create a new reference which provides a branch name for the newly
139 Show the path of each imported file to indicate progress.
145 environment variable to be set,
146 unless an author has been configured in
152 configuration settings can be obtained from the repository's
154 file or from Git's global
165 If this option is not specified, a branch corresponding to the repository's
166 HEAD reference will be used.
167 Use of this option is required if the branch resolved via the repository's
168 HEAD reference already exists.
170 Ignore files or directories with a name which matches the specified
172 This option may be specified multiple times to build a list of ignore patterns.
175 follows the globbing rules documented in
177 Ignore patterns which end with a slash,
179 will only match directories.
181 Use the specified log message when creating the new commit.
186 opens a temporary file in an editor where a log message can be written.
187 Quitting the editor without saving the file will abort the import operation.
188 .It Fl r Ar repository-path
189 Use the repository at the specified path.
190 If not specified, assume the repository is located at or above the current
198 .Op Fl R Ar reference
203 Clone a Git repository at the specified
209 is specified, the directory name will be derived from the name of the
212 will refuse to run if the
218 specifies a protocol scheme, a server hostname, an optional port number
219 separated from the hostname by a colon, and a path to the repository on
221 .Lk scheme://hostname:port/path/to/repository
223 The following protocol schemes are supported:
224 .Bl -tag -width https
226 The Git protocol as implemented by the
229 Use of this protocol is discouraged since it supports neither authentication
232 The Git protocol wrapped in an authenticated and encrypted
235 With this protocol the hostname may contain an embedded username for
243 Not compatible with servers using the
249 Git HTTP protocol is supported by
255 Sending from a repository cloned over HTTP will require use of a
261 protocol will be used by
264 Use of this protocol is discouraged since it supports neither authentication
269 Git HTTP protocol wrapped in SSL/TLS.
272 Objects in the cloned repository are stored in a pack file which is downloaded
274 This pack file will then be indexed to facilitate access to the objects stored
276 If any objects in the pack file are stored in deltified form, all deltas will
277 be fully resolved in order to compute the ID of such objects.
278 This can take some time.
279 More details about the pack file format are documented in
280 .Xr git-repository 5 .
283 creates a remote repository entry in the
287 files of the cloned repository to store the
293 arguments for future use by
303 Fetch all branches from the remote repository's
305 reference namespace and set
306 .Cm fetch_all_branches
307 in the cloned repository's
309 file for future use by
311 If this option is not specified, a branch resolved via the remote
312 repository's HEAD reference will be fetched.
313 Cannot be used together with the
319 from the remote repository's
322 This option may be specified multiple times to build a list of branches
324 If the branch corresponding to the remote repository's HEAD reference is not
325 in this list, the cloned repository's HEAD reference will be set to the first
326 branch which was fetched.
327 If this option is not specified, a branch resolved via the remote
328 repository's HEAD reference will be fetched.
329 Cannot be used together with the
333 List branches and tags available for fetching from the remote repository
334 and exit immediately.
335 Cannot be used together with any of the other options except
340 Create the cloned repository as a mirror of the original repository.
341 This is useful if the cloned repository will not be used to store
342 locally created commits.
348 files will be set up with the
350 option enabled, such that
354 will write incoming changes directly to branches in the
356 reference namespace, rather than to branches in the
359 This avoids the usual requirement of having to run
365 in order to make incoming changes appear on branches in the
368 But maintaining custom changes in the cloned repository becomes difficult
369 since such changes will be at risk of being discarded whenever incoming
372 Suppress progress reporting output.
373 The same option will be passed to
376 .It Fl R Ar reference
377 In addition to the branches and tags that will be fetched, fetch an arbitrary
379 from the remote repository's
382 This option may be specified multiple times to build a list of additional
386 may either be a path to a specific reference, or a reference namespace
387 which will cause all references in this namespace to be fetched.
389 Each reference will be mapped into the cloned repository's
391 namespace, unless the
393 option is used to mirror references directly into the cloned repository's
398 will refuse to fetch references from the remote repository's
407 to print debugging messages to standard error output.
408 This option will be passed to
411 Multiple -v options increase the verbosity.
419 .Op Fl R Ar reference
420 .Op Fl r Ar repository-path
421 .Op Ar remote-repository
424 Fetch new changes from a remote repository.
426 .Ar remote-repository
430 The remote repository's URL is obtained from the corresponding entry in
434 file of the local repository, as created by
437 By default, any branches configured in
440 .Ar remote-repository
444 is invoked in a work tree then this work tree's current branch will be
445 fetched, too, provided it is present on the server.
446 If no branches to fetch can be found in
448 or via a work tree, or said branches are not found on the server, a branch
449 resolved via the remote repository's HEAD reference will be fetched.
450 Likewise, if a HEAD reference for the
451 .Ar remote-repository
452 exists but its target no longer matches the remote HEAD, then
453 the new target branch will be fetched.
454 This default behaviour can be overridden with the
460 New changes will be stored in a separate pack file downloaded from the server.
461 Optionally, separate pack files stored in the repository can be combined with
464 By default, branch references in the
466 reference namespace will be updated to point at the newly fetched commits.
471 command can then be used to make new changes visible on branches in the
473 namespace, merging incoming changes with the changes on those branches
476 If the repository was created as a mirror with
478 then all branches in the
480 namespace will be updated directly to match the corresponding branches in
481 the remote repository.
482 If those branches contained local commits, these commits will no longer be
483 reachable via a reference and will therefore be at risk of being discarded
484 by Git's garbage collector or
485 .Cm gotadmin cleanup .
486 Maintaining custom changes in a mirror repository is therefore discouraged.
488 In any case, references in the
490 namespace will always be fetched and mapped directly to local references
491 in the same namespace.
498 Fetch all branches from the remote repository's
501 This option can be enabled by default for specific repositories in
503 Cannot be used together with the
509 from the remote repository's
512 This option may be specified multiple times to build a list of branches
514 Cannot be used together with the
518 Delete branches and tags from the local repository which are no longer
519 present in the remote repository.
520 Only references are deleted.
521 Any commit, tree, tag, and blob objects belonging to deleted branches or
522 tags remain in the repository and may be removed separately with
523 Git's garbage collector or
524 .Cm gotadmin cleanup .
526 List branches and tags available for fetching from the remote repository
527 and exit immediately.
528 Cannot be used together with any of the other options except
534 Suppress progress reporting output.
535 The same option will be passed to
538 .It Fl R Ar reference
539 In addition to the branches and tags that will be fetched, fetch an arbitrary
541 from the remote repository's
544 This option may be specified multiple times to build a list of additional
548 may either be a path to a specific reference, or a reference namespace
549 which will cause all references in this namespace to be fetched.
551 Each reference will be mapped into the local repository's
553 namespace, unless the local repository was created as a mirror with
555 in which case references will be mapped directly into the local repository's
559 Once a reference has been fetched, a branch based on it can be created with
564 will refuse to fetch references from the remote repository's
569 .It Fl r Ar repository-path
570 Use the repository at the specified path.
571 If not specified, assume the repository is located at or above the current
573 If this directory is a
575 work tree, use the repository path associated with this work tree.
577 Allow existing references in the
579 namespace to be updated if they have changed on the server.
580 If not specified, only new tag references will be created.
585 to print debugging messages to standard error output.
586 The same option will be passed to
589 Multiple -v options increase the verbosity.
592 Delete all references which correspond to a particular
593 .Ar remote-repository
594 instead of fetching new changes.
595 This can be useful when a remote repository is being removed from
601 .Ar remote-repository
602 argument is mandatory and no other options except
609 Only references are deleted.
610 Any commit, tree, tag, and blob objects fetched from a remote repository
611 will generally be stored in pack files and may be removed separately with
613 and Git's garbage collector.
621 .Op Fl p Ar path-prefix
623 .Op Ar work-tree-path
626 Copy files from a repository into a new work tree.
627 Show the status of each affected file, using the following status codes:
628 .Bl -column YXZ description
629 .It A Ta new file was added
630 .It E Ta file already exists in work tree's meta-data
635 is not specified, either use the last component of
636 .Ar repository path ,
639 was specified use the last component of
647 Check out files from a commit on the specified
649 If this option is not specified, a branch resolved via the repository's HEAD
650 reference will be used.
652 Check out files from the specified
654 on the selected branch.
655 If this option is not specified, the most recent commit on the selected
660 argument is a commit ID SHA1 hash, or a reference name or a keyword
661 which will be resolved to a commit ID.
662 An abbreviated hash argument will be expanded to a full SHA1 hash
663 automatically, provided the abbreviation is unique.
668 resolve to the repository's HEAD reference, or, if the
670 option is used, the head of the checked-out
672 Keywords and reference names may be appended with
676 modifiers and an optional integer N to denote the
677 Nth descendant or antecedent by first parent traversal, respectively;
680 denotes the work tree branch head's 2nd generation ancestor, and
682 will denote the 3rd generation ancestor of the commit resolved by the
685 If an integer does not follow the
691 is implicitly appended
700 is not contained in the selected branch, a different branch which contains
701 this commit must be specified with the
704 If no such branch is known, a new branch must be created for this
710 Checking out work trees with an unknown branch is intentionally not supported.
712 Proceed with the checkout operation even if the directory at
715 Existing files will be left intact.
716 .It Fl p Ar path-prefix
717 Restrict the work tree to a subset of the repository's tree hierarchy.
718 Only files beneath the specified
722 Silence progress output.
733 Update an existing work tree to a different
735 Change existing files in the work tree as necessary to match file contents
737 Preserve any local changes in the work tree and merge them with the
740 Files which already contain merge conflicts will not be updated to avoid
741 further complications.
742 Such files will be updated when
744 is run again after merge conflicts have been resolved.
745 If the conflicting changes are no longer needed, affected files can be
752 Show the status of each affected file, using the following status codes:
753 .Bl -column YXZ description
754 .It U Ta file was updated and contained no local changes
755 .It G Ta file was updated and local changes were merged cleanly
756 .It C Ta file was updated and conflicts occurred during merge
757 .It D Ta file was deleted
758 .It d Ta file's deletion was prevented by local modifications
759 .It A Ta new file was added
760 .It \(a~ Ta versioned file is obstructed by a non-regular file
761 .It ! Ta a missing versioned file was restored
762 .It # Ta file was not updated because it contains merge conflicts
763 .It ? Ta changes destined for an unversioned file were not merged
768 is specified, update the entire work tree.
769 Otherwise, restrict the update operation to files at or within the
771 Each path is required to exist in the update operation's target commit.
772 Files in the work tree outside specified paths will remain unchanged and
773 will retain their previously recorded base commit.
776 commands may refuse to run while the work tree contains files from
777 multiple base commits.
778 The base commit of such a work tree can be made consistent by running
780 across the entire work tree.
783 is incompatible with the
788 cannot update paths with staged changes.
789 If changes have been staged with
791 these changes must first be committed with
801 Switch the work tree's branch reference to the specified
803 before updating the work tree.
804 This option requires that all paths in the work tree are updated.
806 As usual, any local changes in the work tree will be preserved.
807 This can be useful when switching to a newly created branch in order
808 to commit existing local changes to this branch.
810 Any local changes must be dealt with separately in order to obtain a
811 work tree with pristine file contents corresponding exactly to the specified
813 Such changes could first be committed to a different branch with
815 or could be discarded with
818 Update the work tree to the specified
820 If this option is not specified, the most recent commit on the work tree's
825 argument is a commit ID SHA1 hash, or a reference name or a keyword
826 which will be resolved to a commit ID.
827 An abbreviated hash argument will be expanded to a full SHA1 hash
828 automatically, provided the abbreviation is unique.
833 resolve to the work tree's base commit and branch head, respectively.
834 Keywords and reference names may be appended with
838 modifiers and an optional integer N to denote the
839 Nth descendant or antecedent, respectively, by first parent traversal;
842 denotes the work tree branch head's 2nd generation ancestor, and
844 denotes the 4th generation descendant of the work tree's base commit.
847 will denote the 3rd generation ancestor of the commit resolved by the
850 If an integer does not follow the
856 is implicitly appended
863 Silence progress output.
869 .Op Fl S Ar status-codes
870 .Op Fl s Ar status-codes
874 Show the current modification status of files in a work tree,
875 using the following status codes:
876 .Bl -column YXZ description
877 .It M Ta modified file
878 .It A Ta file scheduled for addition in next commit
879 .It D Ta file scheduled for deletion in next commit
880 .It C Ta modified or added file which contains merge conflicts
881 .It ! Ta versioned file was expected on disk but is missing
882 .It \(a~ Ta versioned file is obstructed by a non-regular file
883 .It ? Ta unversioned item not tracked by
885 .It m Ta modified file modes (executable bit only)
886 .It N Ta non-existent
888 specified on the command line
893 is specified, show modifications in the entire work tree.
894 Otherwise, show modifications at or within the specified paths.
896 If changes have been staged with
898 staged changes are shown in the second output column, using the following
900 .Bl -column YXZ description
901 .It M Ta file modification is staged
902 .It A Ta file addition is staged
903 .It D Ta file deletion is staged
906 Changes created on top of staged changes are indicated in the first column:
907 .Bl -column YXZ description
908 .It MM Ta file was modified after earlier changes have been staged
909 .It MA Ta file was modified after having been staged for addition
912 If the work tree contains the results of an interrupted
917 operation then display a message which shows the branches involved.
924 Show unversioned files even if they match an ignore pattern.
925 .It Fl S Ar status-codes
926 Suppress the output of files with a modification status matching any of the
927 single-character status codes contained in the
930 Any combination of codes from the above list of possible status codes
932 For staged files, status codes displayed in either column will be matched.
933 Cannot be used together with the
936 .It Fl s Ar status-codes
937 Only show files with a modification status matching any of the
938 single-character status codes contained in the
941 Any combination of codes from the above list of possible status codes
943 For staged files, status codes displayed in either column will be matched.
944 Cannot be used together with the
949 For compatibility with
960 files in each traversed directory and will not display unversioned files
961 which match these patterns.
962 Ignore patterns which end with a slash,
964 will only match directories.
969 supports consecutive asterisks,
971 which will match an arbitrary amount of directories.
975 only supports a single ignore pattern per line.
979 does not support negated ignore patterns prefixed with
981 and gives no special significance to the location of path component separators,
990 .Op Fl r Ar repository-path
991 .Op Fl S Ar search-pattern
995 Display history of a repository.
998 is specified, show only commits which modified this path.
999 If invoked in a work tree, the
1001 is interpreted relative to the current working directory,
1002 and the work tree's path prefix is implicitly prepended.
1003 Otherwise, the path is interpreted relative to the repository root.
1010 Display individual commits which were merged into the current branch
1011 from other branches.
1014 shows the linear history of the current branch only.
1016 Set the number of context lines shown in diffs with
1018 By default, 3 lines of context are shown.
1020 Start traversing history at the specified
1022 If this option is not specified, default to the work tree's current branch
1023 if invoked in a work tree, or to the repository's HEAD reference.
1027 argument is a commit ID SHA1 hash, or a reference name or a keyword
1028 which will be resolved to a commit ID.
1029 An abbreviated hash argument will be expanded to a full SHA1 hash
1030 automatically, provided the abbreviation is unique.
1035 resolve to the work tree's base commit and branch head, respectively.
1036 The former is only valid if invoked in a work tree, while the latter will
1037 resolve to the tip of the work tree's current branch if invoked in a
1038 work tree, otherwise it will resolve to the repository's HEAD reference.
1039 Keywords and references may be appended with
1043 modifiers and an optional integer N to denote the
1044 Nth descendant or antecedent, respectively, by first parent traversal;
1047 denotes the HEAD reference's 2nd generation ancestor, and
1049 denotes the 4th generation descendant of the work tree's base commit.
1052 will denote the 3rd generation descendant of the commit resolved by the
1059 modifier without a trailing integer has an implicit
1068 Display diffstat of changes introduced in each commit.
1069 Cannot be used with the
1074 option (diffstat displays a list of changed paths).
1076 Limit history traversal to a given number of commits.
1077 If this option is not specified, a default limit value of zero is used,
1078 which is treated as an unbounded limit.
1080 .Ev GOT_LOG_DEFAULT_LIMIT
1081 environment variable may be set to change this default value.
1083 Display the list of file paths changed in each commit, using the following
1085 .Bl -column YXZ description
1086 .It M Ta modified file
1087 .It D Ta file was deleted
1088 .It A Ta new file was added
1089 .It m Ta modified file modes (executable bit only)
1092 Cannot be used with the
1096 Display the patch of modifications made in each commit.
1099 is specified, only show the patch of modifications at or within this path.
1100 Cannot be used with the
1104 Determine a set of commits to display as usual, but display these commits
1106 .It Fl r Ar repository-path
1107 Use the repository at the specified path.
1108 If not specified, assume the repository is located at or above the current
1110 If this directory is a
1112 work tree, use the repository path associated with this work tree.
1113 .It Fl S Ar search-pattern
1114 If specified, show only commits with a log message, author name,
1115 committer name, or ID SHA1 hash matched by the extended regular
1117 .Ar search-pattern .
1118 Lines in committed patches will be matched if
1121 File paths changed by a commit will be matched if
1124 Regular expression syntax is documented in
1127 Display a short one-line summary of each commit, instead of the default
1129 Cannot be used together with the
1135 Display commits in topological order.
1136 This option has no effect without the
1138 option because a linear history is sorted in topological order by definition.
1139 Topological sorting is disabled by default because the present implementation
1140 requires that commit history is fully traversed before any output can be shown.
1142 Stop traversing commit history immediately after the specified
1149 argument is a commit ID SHA1 hash, or a reference name or a keyword
1150 which will be resolved to a commit ID.
1151 This option has no effect if the specified
1161 .Op Fl r Ar repository-path
1162 .Op Ar object1 Ar object2 | Ar path ...
1165 When invoked within a work tree without any arguments, display all
1166 local changes in the work tree.
1169 arguments are specified, only show changes within the specified paths.
1171 If two arguments are provided, treat each argument as a reference, a tag
1172 name, or an object ID SHA1 hash, and display differences between the
1173 corresponding objects.
1174 Both objects must be of the same type (blobs, trees, or commits).
1175 An abbreviated hash argument will be expanded to a full SHA1 hash
1176 automatically, provided the abbreviation is unique.
1177 If none of these interpretations produce a valid result or if the
1182 is running in a work tree, attempt to interpret the two arguments as paths.
1189 Treat file contents as ASCII text even if binary data is detected.
1191 Set the number of context lines shown in the diff.
1192 By default, 3 lines of context are shown.
1194 Show differences between commits in the repository.
1195 This option may be used up to two times.
1196 When used only once, show differences between the specified
1198 and its first parent commit.
1199 When used twice, show differences between the two specified commits.
1203 option is used, all non-option arguments will be interpreted as paths.
1206 arguments are provided, only show differences for the specified paths.
1210 argument is a commit ID SHA1 hash, or a reference name or a keyword
1211 which will be resolved to a commit ID.
1212 An abbreviated hash argument will be expanded to a full SHA1 hash
1213 automatically, provided the abbreviation is unique.
1218 resolve to the work tree's base commit and branch head, respectively.
1219 The former is only valid if invoked in a work tree, while the latter will
1220 resolve to the tip of the work tree's current branch if invoked in a
1221 work tree, otherwise it will resolve to the repository's HEAD reference.
1222 Keywords and references may be appended with
1226 modifiers and an optional integer N to denote the
1227 Nth descendant or antecedent, respectively, by first parent traversal;
1230 denotes the HEAD reference's 2nd generation ancestor, and
1232 denotes the 4th generation descendant of the work tree's base commit.
1235 will denote the 8th generation descendant of the commit resolved by the
1238 If an integer does not follow the
1244 is implicitly appended
1251 Cannot be used together with the
1255 Display diffstat of changes before the actual diff by annotating each file path
1256 or blob hash being diffed with the total number of lines added and removed.
1257 A summary line will display the total number of changes across all files.
1259 Interpret all arguments as paths only.
1260 This option can be used to resolve ambiguity in cases where paths
1261 look like tag names, reference names, or object IDs.
1262 This option is only valid when
1264 is invoked in a work tree.
1265 .It Fl r Ar repository-path
1266 Use the repository at the specified path.
1267 If not specified, assume the repository is located at or above the current
1269 If this directory is a
1271 work tree, use the repository path associated with this work tree.
1273 Show changes staged with
1275 instead of showing local changes in the work tree.
1276 This option is only valid when
1278 is invoked in a work tree.
1280 Ignore whitespace-only changes.
1286 .Op Fl r Ar repository-path
1290 Display line-by-line history of a file at the specified path.
1297 Start traversing history at the specified
1299 The expected argument is a commit ID SHA1 hash, or a reference name
1300 or a keyword which will be resolved to a commit ID.
1301 An abbreviated hash argument will be expanded to a full SHA1 hash
1302 automatically, provided the abbreviation is unique.
1307 resolve to the work tree's base commit and branch head, respectively.
1308 The former is only valid if invoked in a work tree, while the latter will
1309 resolve to the tip of the work tree's current branch if invoked in a
1310 work tree, otherwise it will resolve to the repository's HEAD reference.
1311 Keywords and references may be appended with
1315 modifiers and an optional integer N to denote the
1316 Nth descendant or antecedent by first parent traversal, respectively;
1319 denotes the work tree branch head's 2nd generation ancestor, and
1321 denotes the 4th generation descendant of the work tree's base commit.
1324 will denote the 5th generation ancestor of the commit resolved by the
1331 modifier without a trailing integer has an implicit
1339 .It Fl r Ar repository-path
1340 Use the repository at the specified path.
1341 If not specified, assume the repository is located at or above the current
1343 If this directory is a
1345 work tree, use the repository path associated with this work tree.
1352 .Op Fl r Ar repository-path
1356 Display a listing of files and directories at the specified
1357 directory path in the repository.
1358 Entries shown in this listing may carry one of the following trailing
1360 .Bl -column YXZ description
1361 .It @ Ta entry is a symbolic link
1362 .It / Ta entry is a directory
1363 .It * Ta entry is an executable file
1364 .It $ Ta entry is a Git submodule
1367 Symbolic link entries are also annotated with the target path of the link.
1371 is specified, list the repository path corresponding to the current
1372 directory of the work tree, or the root directory of the repository
1373 if there is no work tree.
1380 List files and directories as they appear in the specified
1383 The expected argument is a commit ID SHA1 hash, or a reference name
1384 or a keyword which will be resolved to a commit ID.
1385 An abbreviated hash argument will be expanded to a full SHA1 hash
1386 automatically, provided the abbreviation is unique.
1391 resolve to the work tree's base commit and branch head, respectively.
1392 The former is only valid if invoked in a work tree, while the latter will
1393 resolve to the tip of the work tree's current branch if invoked in a
1394 work tree, otherwise it will resolve to the repository's HEAD reference.
1395 Keywords and references may be appended with
1399 modifiers and an optional integer N to denote the
1400 Nth descendant or antecedent by first parent traversal, respectively;
1403 denotes the work tree branch head's 2nd generation ancestor, and
1405 denotes the 4th generation descendant of the work tree's base commit.
1408 will denote the 3rd generation ancestor of the commit resolved by the
1415 modifier without a trailing integer has an implicit
1424 Show object IDs of files (blob objects) and directories (tree objects).
1426 Recurse into sub-directories in the repository.
1427 .It Fl r Ar repository-path
1428 Use the repository at the specified path.
1429 If not specified, assume the repository is located at or above the current
1431 If this directory is a
1433 work tree, use the repository path associated with this work tree.
1439 .Op Fl r Ar repository-path
1440 .Op Fl s Ar reference
1443 Manage references in a repository.
1445 References may be listed, created, deleted, and changed.
1446 When creating, deleting, or changing a reference the specified
1448 must be an absolute reference name, i.e. it must begin with
1456 Create a reference or change an existing reference.
1457 The reference with the specified
1459 will point at the specified
1464 argument is an ID SHA1 hash or an existing reference or tag name
1465 or a keyword which will be resolved to the ID of a corresponding commit,
1466 tree, tag, or blob object.
1467 An abbreviated hash argument will be expanded to a full SHA1 hash
1468 automatically, provided the abbreviation is unique.
1473 resolve to the work tree's base commit and branch head, respectively.
1474 The former is only valid if invoked in a work tree, while the latter will
1475 resolve to the tip of the work tree's current branch if invoked in a
1476 work tree, otherwise it will resolve to the repository's HEAD reference.
1477 Keywords and reference names may be appended with
1481 modifiers and an optional integer N to denote the
1482 Nth descendant or antecedent by first parent traversal, respectively;
1485 denotes the work tree branch head's 2nd generation ancestor, and
1487 will denote the 3rd generation ancestor of the commit resolved by the
1490 If an integer does not follow the
1496 is implicitly appended
1503 Cannot be used together with any other options except
1506 Delete the reference with the specified
1508 from the repository.
1509 Any commit, tree, tag, and blob objects belonging to deleted references
1510 remain in the repository and may be removed separately with
1511 Git's garbage collector or
1512 .Cm gotadmin cleanup .
1513 Cannot be used together with any other options except
1516 List references in the repository.
1519 is specified, list all existing references in the repository.
1522 is a reference namespace, list all references in this namespace.
1523 Otherwise, show only the reference with the given
1525 Cannot be used together with any other options except
1529 .It Fl r Ar repository-path
1530 Use the repository at the specified path.
1531 If not specified, assume the repository is located at or above the current
1533 If this directory is a
1535 work tree, use the repository path associated with this work tree.
1536 .It Fl s Ar reference
1537 Create a symbolic reference, or change an existing symbolic reference.
1538 The symbolic reference with the specified
1540 will point at the specified
1542 which must already exist in the repository.
1543 Care should be taken not to create loops between references when
1544 this option is used.
1545 Cannot be used together with any other options except
1548 Sort listed references by modification time (most recently modified first)
1549 instead of sorting by lexicographical order.
1550 Use of this option requires the
1552 option to be used as well.
1560 .Op Fl r Ar repository-path
1564 Create, list, or delete branches.
1566 Local branches are managed via references which live in the
1568 reference namespace.
1571 command creates references in this namespace only.
1573 When deleting branches, the specified
1577 reference namespace first.
1578 If no corresponding branch is found, the
1580 namespace will be searched next.
1582 If invoked in a work tree without any arguments, print the name of the
1583 work tree's current branch.
1587 argument is passed, attempt to create a branch reference with the given name.
1588 By default the new branch reference will point at the latest commit on the
1589 work tree's current branch if invoked in a work tree, and otherwise to a commit
1590 resolved via the repository's HEAD reference.
1592 If invoked in a work tree, once the branch was created successfully
1593 switch the work tree's head reference to the newly created branch and
1594 update files across the entire work tree, just like
1595 .Cm got update -b Ar name
1597 Show the status of each affected file, using the following status codes:
1598 .Bl -column YXZ description
1599 .It U Ta file was updated and contained no local changes
1600 .It G Ta file was updated and local changes were merged cleanly
1601 .It C Ta file was updated and conflicts occurred during merge
1602 .It D Ta file was deleted
1603 .It A Ta new file was added
1604 .It \(a~ Ta versioned file is obstructed by a non-regular file
1605 .It ! Ta a missing versioned file was restored
1613 Make a newly created branch reference point at the specified
1615 The expected argument is a commit ID SHA1 hash, or a reference name or keyword
1616 which will be resolved to a commit ID.
1617 An abbreviated hash argument will be expanded to a full SHA1 hash
1618 automatically, provided the abbreviation is unique.
1623 resolve to the work tree's base commit and branch head, respectively.
1624 The former is only valid if invoked in a work tree, while the latter will
1625 resolve to the tip of the work tree's current branch if invoked in a
1626 work tree, otherwise it will resolve to the repository's HEAD reference.
1627 Keywords and references may be appended with
1631 modifiers and an optional integer N to denote the
1632 Nth descendant or antecedent by first parent traversal, respectively;
1635 denotes the work tree branch head's 2nd generation ancestor, and
1637 denotes the 4th generation descendant of the work tree's base commit.
1640 will denote the 3rd generation descendant of the commit resolved by the
1647 modifier without a trailing integer has an implicit
1656 Delete the branch with the specified
1662 reference namespace.
1664 Only the branch reference is deleted.
1665 Any commit, tree, and blob objects belonging to the branch
1666 remain in the repository and may be removed separately with
1667 Git's garbage collector or
1668 .Cm gotadmin cleanup .
1670 List all existing branches in the repository, including copies of remote
1671 repositories' branches in the
1673 reference namespace.
1675 If invoked in a work tree, the work tree's current branch is shown
1676 with one of the following annotations:
1677 .Bl -column YXZ description
1678 .It * Ta work tree's base commit and the base commit of all tracked files
1679 matches the branch tip
1680 .It \(a~ Ta work tree comprises mixed commits or its base commit is out-of-date
1683 Do not switch and update the work tree after creating a new branch.
1684 .It Fl r Ar repository-path
1685 Use the repository at the specified path.
1686 If not specified, assume the repository is located at or above the current
1688 If this directory is a
1690 work tree, use the repository path associated with this work tree.
1692 Sort listed branches by modification time (most recently modified first)
1693 instead of sorting by lexicographical order.
1696 reference namespace are listed before branches in
1699 Use of this option requires the
1701 option to be used as well.
1708 .Op Fl r Ar repository-path
1709 .Op Fl s Ar signer-id
1712 Manage tags in a repository.
1714 Tags are managed via references which live in the
1716 reference namespace.
1719 command operates on references in this namespace only.
1720 References in this namespace point at tag objects which contain a pointer
1721 to another object, a tag message, as well as author and timestamp information.
1723 Attempt to create a tag with the given
1725 and make this tag point at the given
1727 If no commit is specified, default to the latest commit on the work tree's
1728 current branch if invoked in a work tree, and to a commit resolved via
1729 the repository's HEAD reference otherwise.
1736 Make the newly created tag reference point at the specified
1740 argument is a commit ID SHA1 hash, or a reference or keyword
1741 which will be resolved to a commit ID.
1742 An abbreviated hash argument will be expanded to a full SHA1 hash
1743 automatically, provided the abbreviation is unique.
1748 resolve to the work tree's base commit and branch head, respectively.
1749 The former is only valid if invoked in a work tree, while the latter will
1750 resolve to the tip of the work tree's current branch if invoked in a
1751 work tree, otherwise it will resolve to the repository's HEAD reference.
1752 Keywords and references may be appended with
1756 modifiers and an optional integer N to denote the
1757 Nth descendant or antecedent by first parent traversal, respectively;
1760 denotes the work tree branch head's 2nd generation ancestor, and
1762 denotes the 4th generation descendant of the work tree's base commit.
1765 will denote the 3rd generation ancestor of the commit resolved by the
1772 modifier without a trailing integer has an implicit
1781 List all existing tags in the repository instead of creating a new tag.
1784 argument is passed, show only the tag with the given
1787 Use the specified tag message when creating the new tag.
1792 opens a temporary file in an editor where a tag message can be written.
1793 Quitting the editor without saving the file will abort the tag operation.
1794 .It Fl r Ar repository-path
1795 Use the repository at the specified path.
1796 If not specified, assume the repository is located at or above the current
1798 If this directory is a
1800 work tree, use the repository path associated with this work tree.
1801 .It Fl s Ar signer-id
1802 While creating a new tag, sign this tag with the identity given in
1805 For SSH-based signatures,
1807 is the path to a file which may refer to either a private SSH key,
1808 or a public SSH key with the private half available via
1811 will sign the tag object by invoking
1815 command, using the signature namespace
1817 for compatibility with
1820 Verify tag object signatures.
1823 is specified, show and verify the tag object with the provided name.
1824 Otherwise, list all tag objects and verify signatures where present.
1827 verifies SSH-based signatures by invoking
1830 .Fl Y Cm verify Fl f Ar allowed_signers .
1835 otherwise verification is impossible.
1838 During SSH signature creation and verification this option will be passed to
1840 Multiple -v options increase the verbosity.
1846 command will not delete tags or change existing tags.
1847 If a tag must be deleted, the
1849 command may be used to delete a tag's reference.
1850 This should only be done if the tag has not already been copied to
1857 Schedule unversioned files in a work tree for addition to the
1858 repository in the next commit.
1859 By default, files which match a
1861 ignore pattern will not be added.
1865 mentioned in the command line is not an unversioned file then
1868 To avoid unnecessary errors from paths picked up by file globbing patterns
1869 in the shell, paths in the argument list will be silently ignored if they
1872 at all, or if they are reported with one of the following status codes
1873 and do not have changes staged via
1875 .Bl -column YXZ description
1876 .It M Ta modified file
1877 .It A Ta file scheduled for addition in next commit
1878 .It C Ta modified or added file which contains merge conflicts
1879 .It m Ta modified file modes (executable bit only)
1887 Add files even if they match a
1891 Permit recursion into directories.
1892 If this option is not specified,
1894 will refuse to run if a specified
1902 .Op Fl s Ar status-codes
1906 Remove versioned files from a work tree and schedule them for deletion
1907 from the repository in the next commit.
1914 Perform the operation even if a file contains local modifications,
1915 and do not raise an error if a specified
1917 does not exist on disk.
1919 Keep affected files on disk.
1921 Permit recursion into directories.
1922 If this option is not specified,
1924 will refuse to run if a specified
1927 .It Fl s Ar status-codes
1928 Only delete files with a modification status matching one of the
1929 single-character status codes contained in the
1932 The following status codes may be specified:
1933 .Bl -column YXZ description
1934 .It M Ta modified file (this implies the
1937 .It ! Ta versioned file expected on disk but missing
1945 .Op Fl p Ar strip-count
1951 to files in a work tree.
1952 Files added or removed by a patch will be scheduled for addition or removal in
1955 The patch must be in the unified diff format as produced by
1962 diff when invoked with their
1967 argument is provided, read unified diff data from standard input instead.
1971 contains multiple patches, then attempt to apply each of them in sequence.
1973 Show the status of each affected file, using the following status codes:
1974 .Bl -column XYZ description
1975 .It M Ta file was modified
1976 .It G Ta file was merged using a merge-base found in the repository
1977 .It C Ta file was merged and conflicts occurred during merge
1978 .It D Ta file was deleted
1979 .It A Ta file was added
1980 .It # Ta failed to patch the file
1983 If a change does not match at its exact line number, attempt to
1984 apply it somewhere else in the file if a good spot can be found.
1985 Otherwise, the patch will fail to apply.
1989 will refuse to apply a patch if certain preconditions are not met.
1990 Files to be deleted must already be under version control, and must
1991 not have been scheduled for deletion already.
1992 Files to be added must not yet be under version control and must not
1993 already be present on disk.
1994 Files to be modified must already be under version control and may not
1995 contain conflict markers.
1997 If an error occurs, the
1999 operation will be aborted.
2000 Any changes made to the work tree up to this point will be left behind.
2001 Such changes can be viewed with
2003 and can be reverted with
2012 Attempt to locate files within the specified
2014 for use as a merge-base for 3-way merges.
2018 option is not used then
2020 will attempt to locate merge-bases via object IDs found in
2022 meta-data, such as produced by
2028 option is only recommended in the absence of such meta-data.
2030 Ideally, the specified
2032 should contain versions of files which the changes contained in the
2035 Files will be located by path, relative to the repository root.
2038 option is used then leading path components will be stripped
2039 before paths are looked up in the repository.
2041 In case no merge-base is available for a file, changes will be applied
2042 without doing a 3-way merge.
2043 Changes which do not apply cleanly may then be rejected entirely, rather
2044 than producing merge conflicts in the patched target file.
2048 argument is a commit ID SHA1 hash, or a reference name or a keyword
2049 which will be resolved to a commit ID.
2050 An abbreviated hash argument will be expanded to a full SHA1 hash
2051 automatically, provided the abbreviation is unique.
2056 resolve to the work tree's base commit and branch head, respectively.
2057 Keywords and references may be appended with
2061 modifiers and an optional integer N to denote the
2062 Nth descendant or antecedent by first parent traversal, respectively;
2065 denotes the work tree branch head's 2nd generation ancestor, and
2067 denotes the 4th generation descendant of the work tree's base commit.
2070 will denote the 3rd generation descendant of the commit resolved by the
2077 modifier without a trailing integer has an implicit
2086 Do not make any modifications to the work tree.
2087 This can be used to check whether a patch would apply without issues.
2090 contains diffs that affect the same file multiple times, the results
2091 displayed may be incorrect.
2092 .It Fl p Ar strip-count
2093 Specify the number of leading path components to strip from paths
2102 path prefixes generated by
2104 will be recognized and stripped automatically.
2106 Reverse the patch before applying it.
2112 .Op Fl F Ar response-script
2116 Revert any local changes in files at the specified paths in a work tree.
2117 File contents will be overwritten with those contained in the
2118 work tree's base commit.
2119 There is no way to bring discarded changes back after
2122 If a file was added with
2124 it will become an unversioned file again.
2125 If a file was deleted with
2127 it will be restored.
2133 .It Fl F Ar response-script
2141 responses line-by-line from the specified
2143 file instead of prompting interactively.
2145 Instead of reverting all changes in files, interactively select or reject
2146 changes to revert based on
2152 (quit reverting this file) responses.
2153 If a file is in modified status, individual patches derived from the
2154 modified file content can be reverted.
2155 Files in added or deleted status may only be reverted in their entirety.
2157 Permit recursion into directories.
2158 If this option is not specified,
2160 will refuse to run if a specified
2174 Create a new commit in the repository from changes in a work tree
2175 and use this commit as the new base commit for the work tree.
2178 is specified, commit all changes in the work tree.
2179 Otherwise, commit changes at or within the specified paths.
2181 If changes have been explicitly staged for commit with
2183 only commit staged changes and reject any specified paths which
2184 have not been staged.
2187 opens a temporary file in an editor where a log message can be written
2195 options are used together.
2196 Quitting the editor without saving the file will abort the commit operation.
2198 Show the status of each affected file, using the following status codes:
2199 .Bl -column YXZ description
2200 .It M Ta modified file
2201 .It D Ta file was deleted
2202 .It A Ta new file was added
2203 .It m Ta modified file modes (executable bit only)
2206 Files which are not part of the new commit will retain their previously
2207 recorded base commit.
2210 commands may refuse to run while the work tree contains files from
2211 multiple base commits.
2212 The base commit of such a work tree can be made consistent by running
2214 across the entire work tree.
2218 command requires the
2220 environment variable to be set,
2221 unless an author has been configured in
2227 configuration settings can be
2228 obtained from the repository's
2230 file or from Git's global
2239 Set author information in the newly created commit to
2241 This is useful when committing changes on behalf of someone else.
2244 argument must use the same format as the
2246 environment variable.
2248 In addition to storing author information, the newly created commit
2251 information which is obtained, as usual, from the
2253 environment variable, or
2255 or Git configuration settings.
2257 Allow committing files in conflicted status.
2259 Committing files with conflict markers should generally be avoided.
2260 Cases where conflict markers must be stored in the repository for
2261 some legitimate reason should be very rare.
2262 There are usually ways to avoid storing conflict markers verbatim by
2263 applying appropriate programming tricks.
2265 Use the prepared log message stored in the file found at
2267 when creating the new commit.
2269 opens a temporary file in an editor where the prepared log message can be
2270 reviewed and edited further if needed.
2271 Cannot be used together with the
2275 Use the specified log message when creating the new commit.
2276 Cannot be used together with the
2280 This option prevents
2282 from opening the commit message in an editor.
2283 It has no effect unless it is used together with the
2285 option and is intended for non-interactive use such as scripting.
2287 This option prevents
2289 from generating a diff of the to-be-committed changes in a temporary file
2290 which can be viewed while editing a commit message.
2292 Allow the addition of symbolic links which point outside of the path space
2293 that is under version control.
2296 will reject such symbolic links due to safety concerns.
2299 may decide to represent such a symbolic link as a regular file which contains
2300 the link's target path, rather than creating an actual symbolic link which
2301 points outside of the work tree.
2302 Use of this option is discouraged because external mechanisms such as
2304 are better suited for managing symbolic links to paths not under
2309 will refuse to run if certain preconditions are not met.
2310 If the work tree's current branch is not in the
2312 reference namespace, new commits may not be created on this branch.
2313 Local changes may only be committed if they are based on file content
2314 found in the most recent commit on the work tree's branch.
2315 If a path is found to be out of date,
2317 must be used first in order to merge local changes with changes made
2325 .Op Fl r Ar repository-path
2327 .Op Ar remote-repository
2330 Send new changes to a remote repository.
2332 .Ar remote-repository
2336 The remote repository's URL is obtained from the corresponding entry in
2340 file of the local repository, as created by
2343 All objects corresponding to new changes will be written to a temporary
2344 pack file which is then uploaded to the server.
2345 Upon success, references in the
2347 reference namespace of the local repository will be updated to point at
2348 the commits which have been sent.
2350 By default, changes will only be sent if they are based on up-to-date
2351 copies of relevant branches in the remote repository.
2352 If any changes to be sent are based on out-of-date copies or would
2353 otherwise break linear history of existing branches, new changes must
2354 be fetched from the server with
2356 and local branches must be rebased with
2363 option can be used to make exceptions to these requirements.
2370 Send all branches from the local repository's
2372 reference namespace.
2375 option is equivalent to listing all branches with multiple
2378 Cannot be used together with the
2384 from the local repository's
2386 reference namespace.
2387 This option may be specified multiple times to build a list of branches
2389 If this option is not specified, default to the work tree's current branch
2390 if invoked in a work tree, or to the repository's HEAD reference.
2391 Cannot be used together with the
2395 Delete the specified
2397 from the remote repository's
2399 reference namespace.
2400 This option may be specified multiple times to build a list of branches
2403 Only references are deleted.
2404 Any commit, tree, tag, and blob objects belonging to deleted branches
2405 may become subject to deletion by Git's garbage collector running on
2408 Requesting deletion of branches results in an error if the server
2409 does not support this feature or disallows the deletion of branches
2410 based on its configuration.
2412 Attempt to force the server to overwrite existing branches or tags
2413 in the remote repository, even when
2419 would usually be required before changes can be sent.
2420 The server may reject forced requests regardless, depending on its
2423 Any commit, tree, tag, and blob objects belonging to overwritten branches
2424 or tags may become subject to deletion by Git's garbage collector running
2429 reference namespace is globally shared between all repositories.
2432 option to overwrite tags is discouraged because it can lead to
2433 inconsistencies between the tags present in different repositories.
2434 In general, creating a new tag with a different name is recommended
2435 instead of overwriting an existing tag.
2439 option is particularly discouraged if changes being sent are based
2440 on an out-of-date copy of a branch in the remote repository.
2441 Instead of using the
2443 option, new changes should
2446 and local branches should be rebased with
2450 followed by another attempt to send the changes.
2454 option should only be needed in situations where the remote repository's
2455 copy of a branch or tag is known to be out-of-date and is considered
2457 The risks of creating inconsistencies between different repositories
2458 should also be taken into account.
2460 Suppress progress reporting output.
2461 The same option will be passed to
2464 .It Fl r Ar repository-path
2465 Use the repository at the specified path.
2466 If not specified, assume the repository is located at or above the current
2468 If this directory is a
2470 work tree, use the repository path associated with this work tree.
2472 Attempt to send all tags from the local repository's
2474 reference namespace.
2477 option is equivalent to listing all tags with multiple
2480 Cannot be used together with the
2486 from the local repository's
2488 reference namespace, in addition to any branches that are being sent.
2491 option may be specified multiple times to build a list of tags to send.
2492 No tags will be sent if the
2496 Raise an error if the specified
2498 already exists in the remote repository, unless the
2500 option is used to overwrite the server's copy of the tag.
2501 In general, creating a new tag with a different name is recommended
2502 instead of overwriting an existing tag.
2504 Cannot be used together with the
2511 to print debugging messages to standard error output.
2512 The same option will be passed to
2515 Multiple -v options increase the verbosity.
2525 Merge changes from a single
2530 should be on a different branch than the work tree's base commit.
2532 The expected argument is a commit ID SHA1 hash, or a reference name or
2533 keyword which will be resolved to a commit ID.
2534 An abbreviated hash argument will be expanded to a full SHA1 hash
2535 automatically, provided the abbreviation is unique.
2540 resolve to the work tree's base commit and branch head, respectively.
2541 Keywords and references may be appended with
2545 modifiers and an optional integer N to denote the
2546 Nth descendant or antecedent by first parent traversal, respectively;
2549 denotes the work tree branch head's 2nd generation ancestor, and
2551 denotes the 4th generation descendant of the work tree's base commit.
2554 will denote the 3rd generation descendant of the commit resolved by the
2561 modifier without a trailing integer has an implicit
2570 Show the status of each affected file, using the following status codes:
2571 .Bl -column YXZ description
2572 .It G Ta file was merged
2573 .It C Ta file was merged and conflicts occurred during merge
2574 .It ! Ta changes destined for a missing file were not merged
2575 .It D Ta file was deleted
2576 .It d Ta file's deletion was prevented by local modifications
2577 .It A Ta new file was added
2578 .It \(a~ Ta changes destined for a non-regular file were not merged
2579 .It ? Ta changes destined for an unversioned file were not merged
2582 The merged changes will appear as local changes in the work tree, which
2585 amended manually or with further
2591 If invoked in a work tree where no
2596 operation is taking place,
2598 creates a record of commits which have been merged into the work tree.
2599 When a file changed by
2603 the log messages of relevant merged commits will then appear in the editor,
2604 where the messages should be further adjusted to convey the reasons for
2605 cherrypicking the changes.
2606 Upon exiting the editor, if the time stamp of the log message file
2607 is unchanged or the log message is empty,
2609 will fail with an unmodified or empty log message error.
2611 If all the changes in all files touched by a given commit are discarded,
2614 this commit's log message record will also disappear.
2617 will refuse to run if certain preconditions are not met.
2618 If the work tree contains multiple base commits, it must first be updated
2619 to a single base commit with
2621 If any relevant files already contain merge conflicts, these
2622 conflicts must be resolved first.
2630 Display a list of commit log messages recorded by cherrypick operations,
2631 represented by references in the
2632 .Dq refs/got/worktree
2633 reference namespace.
2636 is specified, only show the log message of the specified commit.
2638 If invoked in a work tree, only log messages recorded by cherrypick operations
2639 in the current work tree will be displayed.
2640 Otherwise, all commit log messages will be displayed irrespective of the
2641 work tree in which they were created.
2642 This option cannot be used with
2645 Delete log messages created by previous cherrypick operations, represented by
2647 .Dq refs/got/worktree
2648 reference namespace.
2651 is specified, only delete the log message of the specified commit.
2653 If invoked in a work tree, only log messages recorded by cherrypick operations
2654 in the current work tree will be deleted.
2655 Otherwise, all commit log messages will be deleted irrespective of the
2656 work tree in which they were created.
2657 This option cannot be used with
2668 Reverse-merge changes from a single
2673 should be on the same branch as the work tree's base commit.
2675 The expected argument is a commit ID SHA1 hash, or a reference name
2676 or keyword which will be resolved to a commit ID.
2677 An abbreviated hash argument will be expanded to a full SHA1 hash
2678 automatically, provided the abbreviation is unique.
2683 resolve to the work tree's base commit and branch head, respectively.
2684 Keywords and references may be appended with
2688 modifiers and an optional integer N to denote the
2689 Nth descendant or antecedent by first parent traversal, respectively;
2692 denotes the work tree branch head's 2nd generation ancestor, and
2694 denotes the 4th generation descendant of the work tree's base commit.
2697 will denote the 5th generation descendant of the commit resolved by the
2704 modifier without a trailing integer has an implicit
2713 Show the status of each affected file, using the following status codes:
2714 .Bl -column YXZ description
2715 .It G Ta file was merged
2716 .It C Ta file was merged and conflicts occurred during merge
2717 .It ! Ta changes destined for a missing file were not merged
2718 .It D Ta file was deleted
2719 .It d Ta file's deletion was prevented by local modifications
2720 .It A Ta new file was added
2721 .It \(a~ Ta changes destined for a non-regular file were not merged
2722 .It ? Ta changes destined for an unversioned file were not merged
2725 The reverse-merged changes will appear as local changes in the work tree,
2726 which may be viewed with
2728 amended manually or with further
2734 If invoked in a work tree where no
2739 operation is taking place,
2741 creates a record of commits which have been reverse-merged into the work tree.
2742 When a file changed by
2746 the log messages of relevant reverse-merged commits will then appear in
2747 the editor, where the messages should be further adjusted to convey the
2748 reasons for backing out the changes.
2749 Upon exiting the editor, if the time stamp of the log message file
2750 is unchanged or the log message is empty,
2752 will fail with an unmodified or empty log message error.
2754 If all the changes in all files touched by a given commit are discarded,
2757 this commit's log message record will also disappear.
2760 will refuse to run if certain preconditions are not met.
2761 If the work tree contains multiple base commits, it must first be updated
2762 to a single base commit with
2764 If any relevant files already contain merge conflicts, these
2765 conflicts must be resolved first.
2773 Display a list of commit log messages recorded by backout operations,
2774 represented by references in the
2775 .Dq refs/got/worktree
2776 reference namespace.
2779 is specified, only show the log message of the specified commit.
2781 If invoked in a work tree, only log messages recorded by backout operations
2782 in the current work tree will be displayed.
2783 Otherwise, all commit log messages will be displayed irrespective of the
2784 work tree in which they were created.
2785 This option cannot be used with
2788 Delete log messages created by previous backout operations, represented by
2790 .Dq refs/got/worktree
2791 reference namespace.
2794 is specified, only delete the log message of the specified commit.
2796 If invoked in a work tree, only log messages recorded by backout operations
2797 in the current work tree will be deleted.
2798 Otherwise, all commit log messages will be deleted irrespective of the
2799 work tree in which they were created.
2800 This option cannot be used with
2811 Rebase commits on the specified
2813 onto the tip of the current branch of the work tree.
2816 must share common ancestry with the work tree's current branch.
2817 Rebasing begins with the first descendant commit of the youngest
2818 common ancestor commit shared by the specified
2820 and the work tree's current branch, and stops once the tip commit
2827 is used as intended, the specified
2829 represents a local commit history and may already contain changes
2830 that are not yet visible in any other repositories.
2831 The work tree's current branch, which must be set with
2835 operation, represents a branch from a remote repository which shares
2836 a common history with the specified
2838 but has progressed, and perhaps diverged, due to commits added to the
2841 Rebased commits are accumulated on a temporary branch which the work tree
2842 will remain switched to throughout the entire rebase operation.
2843 Commits on this branch represent the same changes with the same log
2844 messages as their counterparts on the original
2846 but with different commit IDs.
2847 Once rebasing has completed successfully, the temporary branch becomes
2848 the new version of the specified
2850 and the work tree is automatically switched to it.
2851 If author information is available via the
2853 environment variable,
2859 configuration settings, this author information will be used to identify
2864 Old commits in their pre-rebase state are automatically backed up in the
2865 .Dq refs/got/backup/rebase
2866 reference namespace.
2867 As long as these references are not removed older versions of rebased
2868 commits will remain in the repository and can be viewed with the
2871 Removal of these references makes objects which become unreachable via
2872 any reference subject to removal by Git's garbage collector or
2873 .Cm gotadmin cleanup .
2875 While rebasing commits, show the status of each affected file,
2876 using the following status codes:
2877 .Bl -column YXZ description
2878 .It G Ta file was merged
2879 .It C Ta file was merged and conflicts occurred during merge
2880 .It ! Ta changes destined for a missing file were not merged
2881 .It D Ta file was deleted
2882 .It d Ta file's deletion was prevented by local modifications
2883 .It A Ta new file was added
2884 .It \(a~ Ta changes destined for a non-regular file were not merged
2885 .It ? Ta changes destined for an unversioned file were not merged
2888 If merge conflicts occur, the rebase operation is interrupted and may
2889 be continued once conflicts have been resolved.
2890 If any files with destined changes are found to be missing or unversioned,
2891 or if files could not be deleted due to differences in deleted content,
2892 the rebase operation will be interrupted to prevent potentially incomplete
2893 changes from being committed to the repository without user intervention.
2894 The work tree may be modified as desired and the rebase operation can be
2895 continued once the changes present in the work tree are considered complete.
2896 Alternatively, the rebase operation may be aborted which will leave
2898 unmodified and the work tree switched back to its original branch.
2900 If a merge conflict is resolved in a way which renders the merged
2901 change into a no-op change, the corresponding commit will be elided
2902 when the rebase operation continues.
2905 will refuse to run if certain preconditions are not met.
2910 reference namespace, the branch may not be rebased.
2911 If the work tree is not yet fully updated to the tip commit of its
2912 branch, then the work tree must first be updated with
2914 If changes have been staged with
2916 these changes must first be committed with
2920 If the work tree contains local changes, these changes must first be
2927 contains changes to files outside of the work tree's path prefix,
2928 the work tree cannot be used to rebase this branch.
2937 commands will refuse to run while a rebase operation is in progress.
2938 Other commands which manipulate the work tree may be used for
2939 conflict resolution purposes.
2943 is already based on the work tree's current branch, then no commits
2944 need to be rebased and
2946 will simply switch the work tree to the specified
2948 and update files in the work tree accordingly.
2955 Abort an interrupted rebase operation.
2956 If this option is used, no other command-line arguments are allowed.
2958 Allow a rebase operation to continue with files in conflicted status.
2959 This option should generally be avoided, and can only be used with the
2963 Continue an interrupted rebase operation.
2964 If this option is used, no other command-line arguments are allowed except
2967 Show a list of past rebase operations, represented by references in the
2968 .Dq refs/got/backup/rebase
2969 reference namespace.
2971 Display the author, date, and log message of each backed up commit,
2972 the object ID of the corresponding post-rebase commit, and
2973 the object ID of their common ancestor commit.
2974 Given these object IDs,
2981 options can be used to examine the history of either version of the branch,
2986 option can be used to create a new branch from a pre-rebase state if desired.
2990 is specified, only show commits which at some point in time represented this
2992 Otherwise, list all backed up commits for any branches.
2994 If this option is used,
2996 does not require a work tree.
2997 None of the other options can be used together with
3000 Delete backups created by past rebase operations, represented by references
3002 .Dq refs/got/backup/rebase
3003 reference namespace.
3007 is specified, only delete backups which at some point in time represented
3009 Otherwise, delete all references found within
3010 .Dq refs/got/backup/rebase .
3012 Any commit, tree, tag, and blob objects belonging to deleted backups
3013 remain in the repository and may be removed separately with
3014 Git's garbage collector or
3015 .Cm gotadmin cleanup .
3017 If this option is used,
3019 does not require a work tree.
3020 None of the other options can be used together with
3027 .Op Fl F Ar histedit-script
3031 Edit commit history between the work tree's current base commit and
3032 the tip commit of the work tree's current branch.
3036 command requires the
3038 environment variable to be set,
3039 unless an author has been configured in
3045 configuration settings can be obtained from the repository's
3047 file or from Git's global
3053 operation, the work tree's current branch must be set with
3055 to the branch which should be edited, unless this branch is already the
3056 current branch of the work tree.
3057 The tip of this branch represents the upper bound (inclusive) of commits
3062 Furthermore, the work tree's base commit
3065 to a point in this branch's commit history where editing should begin.
3066 This commit represents the lower bound (non-inclusive) of commits touched
3071 Editing of commit history is controlled via a
3073 which can be written in an editor based on a template, passed on the
3074 command line, or generated with the
3081 Quitting the editor without saving the file will abort the histedit operation.
3083 The format of the histedit script is line-based.
3084 Each line in the script begins with a command name, followed by
3085 whitespace and an argument.
3086 For most commands, the expected argument is a commit ID SHA1 hash.
3087 Any remaining text on the line is ignored.
3088 Lines which begin with the
3090 character are ignored entirely.
3092 The available histedit script commands are as follows:
3093 .Bl -column YXZ pick-commit
3094 .It Cm pick Ar commit Ta Use the specified commit as it is.
3095 .It Cm edit Ar commit Ta Apply the changes from the specified commit, but
3096 then interrupt the histedit operation for amending, without creating a commit.
3097 While the histedit operation is interrupted arbitrary files may be edited,
3098 and commands which manipulate the work tree can be used freely.
3103 commands can be used to add new files or remove existing ones.
3106 command can be used to eliminate arbitrary changes from files in the work tree.
3109 command may be used to prepare a subset of changes for inclusion in the
3113 command can be used to insert arbitrary commits into the edited history.
3114 Regular editing of history must eventually be resumed by running
3115 .Cm got histedit -c .
3116 .It Cm fold Ar commit Ta Combine the specified commit with the next commit
3117 listed further below that will be used.
3118 .It Cm drop Ar commit Ta Remove this commit from the edited history.
3119 .It Cm mesg Ar commit Ta Open an editor to create a new log message for this
3123 Every commit in the history being edited must be mentioned in the script.
3124 Lines may be re-ordered to change the order of commits in the edited history.
3125 No commit may be listed more than once.
3127 Edited commits are accumulated on a temporary branch which the work tree
3128 will remain switched to throughout the entire histedit operation.
3129 Once history editing has completed successfully, the temporary branch becomes
3130 the new version of the work tree's branch and the work tree is automatically
3133 Old commits in their pre-histedit state are automatically backed up in the
3134 .Dq refs/got/backup/histedit
3135 reference namespace.
3136 As long as these references are not removed older versions of edited
3137 commits will remain in the repository and can be viewed with the
3140 Removal of these references makes objects which become unreachable via
3141 any reference subject to removal by Git's garbage collector or
3142 .Cm gotadmin cleanup .
3144 While merging commits, show the status of each affected file,
3145 using the following status codes:
3146 .Bl -column YXZ description
3147 .It G Ta file was merged
3148 .It C Ta file was merged and conflicts occurred during merge
3149 .It ! Ta changes destined for a missing file were not merged
3150 .It D Ta file was deleted
3151 .It d Ta file's deletion was prevented by local modifications
3152 .It A Ta new file was added
3153 .It \(a~ Ta changes destined for a non-regular file were not merged
3154 .It ? Ta changes destined for an unversioned file were not merged
3157 If merge conflicts occur, the histedit operation is interrupted and may
3158 be continued once conflicts have been resolved.
3159 If any files with destined changes are found to be missing or unversioned,
3160 or if files could not be deleted due to differences in deleted content,
3161 the histedit operation will be interrupted to prevent potentially incomplete
3162 changes from being committed to the repository without user intervention.
3163 The work tree may be modified as desired and the histedit operation can be
3164 continued once the changes present in the work tree are considered complete.
3165 Alternatively, the histedit operation may be aborted which will leave
3166 the work tree switched back to its original branch.
3168 If a merge conflict is resolved in a way which renders the merged
3169 change into a no-op change, the corresponding commit will be elided
3170 when the histedit operation continues.
3173 will refuse to run if certain preconditions are not met.
3174 If the work tree's current branch is not in the
3176 reference namespace, the history of the branch may not be edited.
3177 If the work tree contains multiple base commits, it must first be updated
3178 to a single base commit with
3180 If changes have been staged with
3182 these changes must first be committed with
3186 If the work tree contains local changes, these changes must first be
3191 If the edited history contains changes to files outside of the work tree's
3192 path prefix, the work tree cannot be used to edit the history of this branch.
3200 commands will refuse to run while a histedit operation is in progress.
3201 Other commands which manipulate the work tree may be used, and the
3203 command may be used to commit arbitrary changes to the temporary branch
3204 while the histedit operation is interrupted.
3211 Abort an interrupted histedit operation.
3212 If this option is used, no other command-line arguments are allowed.
3214 Allow a histedit operation to continue with files in conflicted status.
3215 This option should generally be avoided, and can only be used with the
3219 Continue an interrupted histedit operation.
3220 If this option is used, no other command-line arguments are allowed except
3224 This option is a quick equivalent to a histedit script which drops all
3228 option can only be used when starting a new histedit operation.
3229 If this option is used, no other command-line arguments are allowed.
3231 Interrupt the histedit operation for editing after merging each commit.
3232 This option is a quick equivalent to a histedit script which uses the
3234 command for all commits.
3237 option can only be used when starting a new histedit operation.
3238 If this option is used, no other command-line arguments are allowed.
3239 .It Fl F Ar histedit-script
3242 instead of opening a temporary file in an editor where a histedit script
3245 Fold all commits into a single commit.
3246 This option is a quick equivalent to a histedit script which folds all
3247 commits, combining them all into one commit.
3250 option can only be used when starting a new histedit operation.
3251 If this option is used, no other command-line arguments are allowed.
3253 Show a list of past histedit operations, represented by references in the
3254 .Dq refs/got/backup/histedit
3255 reference namespace.
3257 Display the author, date, and log message of each backed up commit,
3258 the object ID of the corresponding post-histedit commit, and
3259 the object ID of their common ancestor commit.
3260 Given these object IDs,
3267 options can be used to examine the history of either version of the branch,
3272 option can be used to create a new branch from a pre-histedit state if desired.
3276 is specified, only show commits which at some point in time represented this
3278 Otherwise, list all backed up commits for any branches.
3280 If this option is used,
3282 does not require a work tree.
3283 None of the other options can be used together with
3286 Edit log messages only.
3287 This option is a quick equivalent to a histedit script which edits
3288 only log messages but otherwise leaves every picked commit as-is.
3291 option can only be used when starting a new histedit operation.
3292 If this option is used, no other command-line arguments are allowed.
3294 Delete backups created by past histedit operations, represented by references
3296 .Dq refs/got/backup/histedit
3297 reference namespace.
3301 is specified, only delete backups which at some point in time represented
3303 Otherwise, delete all references found within
3304 .Dq refs/got/backup/histedit .
3306 Any commit, tree, tag, and blob objects belonging to deleted backups
3307 remain in the repository and may be removed separately with
3308 Git's garbage collector or
3309 .Cm gotadmin cleanup .
3311 If this option is used,
3313 does not require a work tree.
3314 None of the other options can be used together with
3318 .It Cm integrate Ar branch
3320 Integrate the specified
3322 into the work tree's current branch.
3323 Files in the work tree are updated to match the contents on the integrated
3325 and the reference of the work tree's branch is changed to point at the
3326 head commit of the integrated
3329 Both branches can be considered equivalent after integration since they
3330 will be pointing at the same commit.
3331 Both branches remain available for future work, if desired.
3332 In case the integrated
3334 is no longer needed it may be deleted with
3337 Show the status of each affected file, using the following status codes:
3338 .Bl -column YXZ description
3339 .It U Ta file was updated
3340 .It D Ta file was deleted
3341 .It A Ta new file was added
3342 .It \(a~ Ta versioned file is obstructed by a non-regular file
3343 .It ! Ta a missing versioned file was restored
3347 will refuse to run if certain preconditions are not met.
3348 Most importantly, the
3350 must have been rebased onto the work tree's current branch with
3352 before it can be integrated, in order to linearize commit history and
3353 resolve merge conflicts.
3354 If the work tree contains multiple base commits, it must first be updated
3355 to a single base commit with
3357 If changes have been staged with
3359 these changes must first be committed with
3363 If the work tree contains local changes, these changes must first be
3377 into the current branch of the work tree.
3378 If the branches have diverged, merge changes into the work tree
3379 and create a merge commit.
3380 Otherwise, if the specified
3382 is already based on the work tree's current branch, make the work tree's
3383 current branch equivalent to the specified
3385 and update files in the work tree accordingly.
3387 Merge commits are commits based on multiple parent commits.
3388 The tip commit of the work tree's current branch will be used as the
3390 The tip commit of the specified
3392 will be used as the second parent.
3393 The work tree's current branch
3396 reference namespace and can be set with
3402 No ancestral relationship between the two branches is required.
3403 If the two branches have already been merged previously, only new changes
3406 It is not possible to create merge commits with more than two parents.
3407 If more than one branch needs to be merged, then multiple merge commits
3408 with two parents each can be created in sequence.
3410 If a linear project history is desired, then use of
3412 should generally be preferred over
3414 However, even strictly linear projects may require occasional merge commits,
3415 for example in order to merge in new versions of third-party code stored
3418 branches created with
3421 While merging changes found on the
3423 into the work tree, show the status of each affected file,
3424 using the following status codes:
3425 .Bl -column YXZ description
3426 .It G Ta file was merged
3427 .It C Ta file was merged and conflicts occurred during merge
3428 .It ! Ta changes destined for a missing file were not merged
3429 .It D Ta file was deleted
3430 .It d Ta file's deletion was prevented by local modifications
3431 .It A Ta new file was added
3432 .It \(a~ Ta changes destined for a non-regular file were not merged
3433 .It ? Ta changes destined for an unversioned file were not merged
3436 If merge conflicts occur, the merge operation is interrupted and conflicts
3437 must be resolved before the merge operation can continue.
3438 If any files with destined changes are found to be missing or unversioned,
3439 or if files could not be deleted due to differences in deleted content,
3440 the merge operation will be interrupted to prevent potentially incomplete
3441 changes from being committed to the repository without user intervention.
3442 The work tree may be modified as desired and the merge can be continued
3443 once the changes present in the work tree are considered complete.
3444 Alternatively, the merge operation may be aborted which will leave
3445 the work tree's current branch unmodified.
3448 will refuse to run if certain preconditions are not met.
3449 If the work tree's current branch is not in the
3451 reference namespace then the work tree must first be switched to a
3456 If the work tree is not yet fully updated to the tip commit of its
3457 branch, then the work tree must first be updated with
3459 If the work tree contains multiple base commits, it must first be updated
3460 to a single base commit with
3462 If changes have been staged with
3464 these changes must first be committed with
3468 If the work tree contains local changes, these changes must first be
3475 contains changes to files outside of the work tree's path prefix,
3476 the work tree cannot be used to merge this branch.
3486 commands will refuse to run while a merge operation is in progress.
3487 Other commands which manipulate the work tree may be used for
3488 conflict resolution purposes.
3495 Abort an interrupted merge operation.
3496 If this option is used, no other command-line arguments are allowed.
3498 Allow a merge operation to continue with files in conflicted status.
3499 This option should generally be avoided, and can only be used with the
3503 Continue an interrupted merge operation.
3504 If this option is used, no other command-line arguments are allowed except
3507 Create a merge commit even if the branches have not diverged.
3509 Merge changes into the work tree as usual but do not create a merge
3511 The merge result can be adjusted as desired before a merge commit is
3514 Alternatively, the merge may be aborted with
3521 .Op Fl F Ar response-script
3525 Stage local changes for inclusion in the next commit.
3528 is specified, stage all changes in the work tree.
3529 Otherwise, stage changes at or within the specified paths.
3530 Paths may be staged if they are added, modified, or deleted according to
3533 Show the status of each affected file, using the following status codes:
3534 .Bl -column YXZ description
3535 .It A Ta file addition has been staged
3536 .It M Ta file modification has been staged
3537 .It D Ta file deletion has been staged
3540 Staged file contents are saved in newly created blob objects in the repository.
3541 These blobs will be referred to by tree objects once staged changes have been
3544 Staged changes affect the behaviour of
3549 While paths with staged changes exist, the
3551 command will refuse to commit any paths which do not have staged changes.
3552 Local changes created on top of staged changes can only be committed if
3553 the path is staged again, or if the staged changes are committed first.
3556 command will show both local changes and staged changes.
3559 command is able to display local changes relative to staged changes,
3560 and to display staged changes relative to the repository.
3563 command cannot revert staged changes but may be used to revert
3564 local changes created on top of staged changes.
3570 .It Fl F Ar response-script
3578 responses line-by-line from the specified
3580 file instead of prompting interactively.
3582 Instead of staging new changes, list paths which are already staged,
3583 along with the IDs of staged blob objects and stage status codes.
3584 If paths were provided on the command line, show the staged paths
3585 among the specified paths.
3586 Otherwise, show all staged paths.
3588 Instead of staging the entire content of a changed file, interactively
3589 select or reject changes for staging based on
3593 (reject change), and
3595 (quit staging this file) responses.
3596 If a file is in modified status, individual patches derived from the
3597 modified file content can be staged.
3598 Files in added or deleted status may only be staged or rejected in
3601 Allow staging of symbolic links which point outside of the path space
3602 that is under version control.
3605 will reject such symbolic links due to safety concerns.
3608 may decide to represent such a symbolic link as a regular file which contains
3609 the link's target path, rather than creating an actual symbolic link which
3610 points outside of the work tree.
3611 Use of this option is discouraged because external mechanisms such as
3613 are better suited for managing symbolic links to paths not under
3618 will refuse to run if certain preconditions are not met.
3619 If a file contains merge conflicts, these conflicts must be resolved first.
3620 If a file is found to be out of date relative to the head commit on the
3621 work tree's current branch, the file must be updated with
3623 before it can be staged (however, this does not prevent the file from
3624 becoming out-of-date at some point after having been staged).
3632 commands will refuse to run while staged changes exist.
3633 If staged changes cannot be committed because a staged path
3634 is out of date, the path must be unstaged with
3636 before it can be updated with
3638 and may then be staged again if necessary.
3643 .Op Fl F Ar response-script
3647 Merge staged changes back into the work tree and put affected paths
3648 back into non-staged status.
3651 is specified, unstage all staged changes across the entire work tree.
3652 Otherwise, unstage changes at or within the specified paths.
3654 Show the status of each affected file, using the following status codes:
3655 .Bl -column YXZ description
3656 .It G Ta file was unstaged
3657 .It C Ta file was unstaged and conflicts occurred during merge
3658 .It ! Ta changes destined for a missing file were not merged
3659 .It D Ta file was staged as deleted and still is deleted
3660 .It d Ta file's deletion was prevented by local modifications
3661 .It \(a~ Ta changes destined for a non-regular file were not merged
3668 .It Fl F Ar response-script
3676 responses line-by-line from the specified
3678 file instead of prompting interactively.
3680 Instead of unstaging the entire content of a changed file, interactively
3681 select or reject changes for unstaging based on
3685 (keep change staged), and
3687 (quit unstaging this file) responses.
3688 If a file is staged in modified status, individual patches derived from the
3689 staged file content can be unstaged.
3690 Files staged in added or deleted status may only be unstaged in their entirety.
3696 .Op Fl r Ar repository-path
3699 Parse and print contents of objects to standard output in a line-based
3701 Content of commit, tree, and tag objects is printed in a way similar
3702 to the actual content stored in such objects.
3703 Blob object contents are printed as they would appear in files on disk.
3705 Attempt to interpret each argument as a reference, a tag name, or
3706 an object ID SHA1 hash.
3707 References will be resolved to an object ID.
3708 Tag names will resolved to a tag object.
3709 An abbreviated hash argument will be expanded to a full SHA1 hash
3710 automatically, provided the abbreviation is unique.
3712 If none of the above interpretations produce a valid result, or if the
3714 option is used, attempt to interpret the argument as a path which will
3715 be resolved to the ID of an object found at this path in the repository.
3722 Look up paths in the specified
3724 If this option is not used, paths are looked up in the commit resolved
3725 via the repository's HEAD reference.
3727 The expected argument is a commit ID SHA1 hash, or a reference name
3728 or keyword which will be resolved to a commit ID.
3729 An abbreviated hash argument will be expanded to a full SHA1 hash
3730 automatically, provided the abbreviation is unique.
3735 resolve to the work tree's base commit and branch head, respectively.
3736 The former is only valid if invoked in a work tree, while the latter will
3737 resolve to the tip of the work tree's current branch if invoked in a
3738 work tree, otherwise it will resolve to the repository's HEAD reference.
3739 Keywords and references may be appended with
3743 modifiers and an optional integer N to denote the
3744 Nth descendant or antecedent by first parent traversal, respectively;
3747 denotes the work tree branch head's 2nd generation ancestor, and
3749 denotes the 4th generation descendant of the work tree's base commit.
3752 will denote the 8th generation ancestor of the commit resolved by the
3759 modifier without a trailing integer has an implicit
3768 Interpret all arguments as paths only.
3769 This option can be used to resolve ambiguity in cases where paths
3770 look like tag names, reference names, or object IDs.
3771 .It Fl r Ar repository-path
3772 Use the repository at the specified path.
3773 If not specified, assume the repository is located at or above the current
3775 If this directory is a
3777 work tree, use the repository path associated with this work tree.
3779 .It Cm info Op Ar path ...
3780 Display meta-data stored in a work tree.
3785 The work tree to use is resolved implicitly by walking upwards from the
3786 current working directory.
3790 arguments are specified, show additional per-file information for tracked
3791 files located at or within these paths.
3794 argument corresponds to the work tree's root directory, display information
3795 for all tracked files.
3798 .Bl -tag -width GOT_IGNORE_GITCONFIG
3800 The author's name and email address, such as
3801 .Qq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
3812 may fail to parse commits without an email address in author data,
3816 environment variables with a missing email address.
3818 .Ev GOT_AUTHOR will be overridden by configuration settings in
3824 configuration settings in the repository's
3831 configuration settings contained in Git's global
3833 configuration file will only be used if neither
3837 environment variable provide author information.
3838 .It Ev GOT_IGNORE_GITCONFIG
3839 If this variable is set then any remote repository definitions or author
3840 information found in Git configuration files will be ignored.
3841 .It Ev GOT_LOG_DEFAULT_LIMIT
3842 The default limit on the number of commits traversed by
3844 If set to zero, the limit is unbounded.
3845 This variable will be silently ignored if it is set to a non-numeric value.
3846 .It Ev VISUAL , EDITOR
3847 The editor spawned by
3855 text editor will be spawned.
3858 .Bl -tag -width packed-refs -compact
3860 Repository-wide configuration settings for
3864 configuration file located in the root directory of a Git repository
3865 supersedes any relevant settings in Git's
3869 .It Pa .got/got.conf
3870 Worktree-specific configuration settings for
3874 configuration file in the
3876 meta-data directory of a work tree supersedes any relevant settings in
3879 configuration file and Git's
3886 Enable tab-completion of
3891 .Dl $ set -A complete_got_1 -- $(got -h 2>&1 | sed -n s/commands://p)
3893 Clone an existing Git repository for use with
3897 .Dl $ got clone ssh://git@github.com/openbsd/src.git
3899 Unfortunately, many of the popular Git hosting sites do not offer anonymous
3901 Such sites will require an account to be created, and a public SSH key to be
3902 uploaded to this account, before repository access via ssh:// URLs will work.
3904 Most sites offer anonymous repository access via HTTPS:
3907 .Dl $ got clone https://github.com/openbsd/src.git
3909 Alternatively, for quick and dirty local testing of
3911 a new Git repository could be created and populated with files,
3912 e.g. from a temporary CVS checkout located at
3915 .Dl $ got init /var/git/src.git
3916 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
3918 Check out a work tree from the Git repository to /usr/src:
3920 .Dl $ got checkout /var/git/src.git /usr/src
3922 View local changes in a work tree directory:
3924 .Dl $ got diff | less
3926 In a work tree, display files in a potentially problematic state:
3928 .Dl $ got status -s 'C!~?'
3930 Interactively revert selected local changes in a work tree directory:
3932 .Dl $ got revert -p -R\ .
3934 In a work tree or a git repository directory, list all branch references:
3938 As above, but list the most recently modified branches only:
3940 .Dl $ got branch -lt | head
3942 In a work tree or a git repository directory, create a new branch called
3943 .Dq unified-buffer-cache
3944 which is forked off the
3948 .Dl $ got branch -c master unified-buffer-cache
3950 Switch an existing work tree to the branch
3951 .Dq unified-buffer-cache .
3952 Local changes in the work tree will be preserved and merged if necessary:
3954 .Dl $ got update -b unified-buffer-cache
3956 Create a new commit from local changes in a work tree directory.
3957 This new commit will become the head commit of the work tree's current branch:
3961 In a work tree or a git repository directory, view changes committed in
3962 the 3 most recent commits to the work tree's branch, or the branch resolved
3963 via the repository's HEAD reference, respectively:
3965 .Dl $ got log -p -l 3
3967 As above, but display changes in the order in which
3969 could apply them in sequence:
3971 .Dl $ got log -p -l 3 -R
3973 In a work tree or a git repository directory, log the history of a subdirectory:
3975 .Dl $ got log sys/uvm
3977 While operating inside a work tree, paths are specified relative to the current
3978 working directory, so this command will log the subdirectory
3981 .Dl $ cd sys/uvm && got log\ .
3983 And this command has the same effect:
3985 .Dl $ cd sys/dev/usb && got log ../../uvm
3987 And this command displays work tree meta-data about all tracked files:
3990 .Dl $ got info\ . | less
3992 Add new files and remove obsolete files in a work tree directory:
3994 .Dl $ got add sys/uvm/uvm_ubc.c
3995 .Dl $ got remove sys/uvm/uvm_vnode.c
3997 A file can be renamed or moved by removing it from its old location
3998 and adding it at the new location:
4000 .Dl $ cp oldfile.c newfile.c
4001 .Dl $ got remove oldfile.c
4002 .Dl $ got add newfile.c
4005 does not yet follow file history across renames, but
4007 will be able to do so regardless.
4009 Create a new commit from local changes in a work tree directory
4010 with a pre-defined log message.
4012 .Dl $ got commit -m 'unify the buffer cache'
4014 Alternatively, create a new commit from local changes in a work tree
4015 directory with a log message that has been prepared in the file
4018 .Dl $ got commit -F /tmp/msg
4020 Update any work tree checked out from the
4021 .Dq unified-buffer-cache
4022 branch to the latest commit on this branch:
4026 Roll file content on the unified-buffer-cache branch back by one commit,
4027 and then fetch the rolled-back change into the work tree as a local change
4028 to be amended and perhaps committed again:
4030 .Dl $ got backout unified-buffer-cache
4031 .Dl $ got commit -m 'roll back previous'
4032 .Dl $ # now back out the previous backout :-)
4033 .Dl $ got backout unified-buffer-cache
4035 Fetch new changes on the remote repository's
4037 branch, making them visible on the local repository's
4046 branch to merge the new changes that are now visible on the
4051 .Dl $ got update -b origin/master
4052 .Dl $ got rebase master
4055 .Dq unified-buffer-cache
4056 branch on top of the new head commit of the
4060 .Dl $ got update -b master
4061 .Dl $ got rebase unified-buffer-cache
4063 Create a patch from all changes on the unified-buffer-cache branch.
4064 The patch can be mailed out for review and applied to
4068 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
4070 Edit the entire commit history of the
4071 .Dq unified-buffer-cache
4074 .Dl $ got update -b unified-buffer-cache
4075 .Dl $ got update -c master
4078 Before working against existing branches in a repository cloned with
4079 .Cm git clone --bare
4084 must be configured to map all references in the remote repository
4087 namespace of the local repository.
4088 This can be achieved by setting Git's
4089 .Pa remote.origin.fetch
4090 configuration variable to the value
4091 .Dq +refs/heads/*:refs/remotes/origin/*
4096 .Dl $ cd /var/git/repo
4097 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
4101 option must be disabled:
4103 .Dl $ cd /var/git/repo
4104 .Dl $ git config remote.origin.mirror false
4106 Alternatively, the following
4108 configuration item can be added manually to the Git repository's
4112 .Dl [remote \&"origin\&"]
4114 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
4117 This configuration leaves the local repository's
4119 namespace free for use by local branches checked out with
4121 and, if needed, created with
4124 .Dq refs/remotes/origin
4125 namespace can now be updated with incoming changes from the remote
4130 without extra command line arguments.
4131 Newly fetched changes can be examined with
4134 Display changes on the remote repository's version of the
4136 branch, as of the last time
4140 .Dl $ got log -c origin/master | less
4142 As shown here, most commands accept abbreviated reference names such as
4145 .Dq refs/remotes/origin/master .
4146 The latter is only needed in case of ambiguity.
4149 can be used to merge changes which are visible on the
4154 This will also merge local changes, if any, with the incoming changes:
4156 .Dl $ got update -b origin/master
4157 .Dl $ got rebase master
4159 In order to make changes committed to the
4160 .Dq unified-buffer-cache
4164 .Dq unified-buffer-cache
4165 branch can be rebased onto the
4169 .Dl $ got update -b master
4170 .Dl $ got rebase unified-buffer-cache
4173 .Dq unified-buffer-cache
4174 branch can now be made visible on the
4178 Because the rebase operation switched the work tree to the
4179 .Dq unified-buffer-cache
4180 branch, the work tree must be switched back to the
4184 .Dl $ got update -b master
4185 .Dl $ got integrate unified-buffer-cache
4189 branch, log messages for local changes can now be amended with
4191 by other developers and any other important new information:
4193 .Dl $ got update -c origin/master
4194 .Dl $ got histedit -m
4196 If the remote repository offers write access, local changes on the
4198 branch can be sent to the remote repository with
4202 can be run without further arguments.
4203 The arguments shown here match defaults, provided the work tree's
4204 current branch is the
4208 .Dl $ got send -b master origin
4210 If the remote repository requires the HTTPS protocol, the
4212 command must be used instead:
4214 .Dl $ cd /var/git/src.git
4215 .Dl $ git push origin master
4217 When making contributions to projects which use the
4219 workflow, SSH protocol repository access needs to be set up first.
4220 Once an account has been created on a Git hosting site it should
4221 be possible to upload a public SSH key for repository access
4226 workflow will usually involve two remote repositories.
4227 In the real-life example below, the
4229 repository was forked from the
4231 repository by using the Git hosting site's web interface.
4234 file in the local repository describes both remote repositories:
4235 .Bd -literal -offset indent
4236 # Jelmers's repository, which accepts pull requests
4238 server git@github.com
4240 repository "/jelmer/dulwich"
4244 # Stefan's fork, used as the default remote repository
4246 server git@github.com
4248 repository "/stspdotname/dulwich"
4253 With this configuration, Stefan can create commits on
4254 .Dq refs/heads/master
4255 and send them to the
4257 repository by running:
4259 .Dl $ got send -b master origin
4261 The changes can now be proposed to Jelmer by opening a pull request
4262 via the Git hosting site's web interface.
4263 If Jelmer requests further changes to be made, additional commits
4264 can be created on the
4266 branch and be added to the pull request by running
4270 If Jelmer prefers additional commits to be
4272 then the following commands can be used to achieve this:
4274 .Dl $ got update -b master
4275 .Dl $ got update -c origin/master
4276 .Dl $ got histedit -f
4277 .Dl $ got send -f -b master origin
4279 In addition to reviewing the pull request in the web user interface,
4280 Jelmer can fetch the pull request's branch into his local repository
4281 and create a local branch which contains the proposed changes:
4283 .Dl $ got fetch -R refs/pull/1046/head origin
4284 .Dl $ got branch -c refs/remotes/origin/pull/1046/head pr1046
4286 Once Jelmer has accepted the pull request, Stefan can fetch the
4287 merged changes, and possibly several other new changes, by running:
4289 .Dl $ got fetch upstream
4291 The merged changes will now be visible under the reference
4292 .Dq refs/remotes/upstream/master .
4295 branch can now be rebased on top of the latest changes
4298 .Dl $ got update -b upstream/master
4299 .Dl $ got rebase master
4301 As an alternative to
4303 branches can be merged with
4306 .Dl $ got update -b master
4307 .Dl $ got merge upstream/master
4309 The question of whether to rebase or merge branches is philosophical.
4310 When in doubt, refer to the software project's policies set by project
4313 As a final step, the forked repository's copy of the master branch needs
4314 to be kept in sync by sending the new changes there:
4316 .Dl $ got send -f -b master origin
4318 If multiple pull requests need to be managed in parallel, a separate branch
4319 must be created for each pull request with
4321 Each such branch can then be used as above, in place of
4322 .Dq refs/heads/master .
4323 Changes for any accepted pull requests will still appear under
4324 .Dq refs/remotes/upstream/master,
4325 regardless of which branch was used in the forked repository to
4326 create a pull request.
4330 .Xr git-repository 5 ,
4331 .Xr got-worktree 5 ,
4335 .An Anthony J. Bentley Aq Mt bentley@openbsd.org
4336 .An Christian Weisgerber Aq Mt naddy@openbsd.org
4337 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
4338 .An Josh Rickmar Aq Mt jrick@zettaport.com
4339 .An Joshua Stein Aq Mt jcs@openbsd.org
4340 .An Klemens Nanni Aq Mt kn@openbsd.org
4341 .An Martin Pieuchot Aq Mt mpi@openbsd.org
4342 .An Neels Hofmeyr Aq Mt neels@hofmeyr.de
4343 .An Omar Polo Aq Mt op@openbsd.org
4344 .An Ori Bernstein Aq Mt ori@openbsd.org
4345 .An Sebastien Marie Aq Mt semarie@openbsd.org
4346 .An Stefan Sperling Aq Mt stsp@openbsd.org
4347 .An Steven McDonald Aq Mt steven@steven-mcdonald.id.au
4348 .An Theo Buehler Aq Mt tb@openbsd.org
4349 .An Thomas Adam Aq Mt thomas@xteddy.org
4350 .An Tracey Emery Aq Mt tracey@traceyemery.net
4351 .An Yang Zhong Aq Mt yzhong@freebsdfoundation.org
4358 were derived from code under copyright by:
4360 .An Caldera International
4361 .An Daniel Hartmeier
4366 .An Jean-Francois Brousseau
4372 .An Niklas Hallqvist
4377 .An Xavier Santolaria
4380 contains code contributed to the public domain by
4381 .An Austin Appleby .
4384 is a work-in-progress and some features remain to be implemented.
4386 At present, the user has to fall back on
4388 to perform some tasks.
4392 Writing to remote repositories over HTTP or HTTPS protocols requires
4395 The creation of merge commits with more than two parent commits requires
4398 In situations where files or directories were moved around
4400 will not automatically merge changes to new locations and
4402 will usually produce better results.
