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
52 provides global and command-specific options.
53 Global options must precede the command name, and are as follows:
54 .Bl -tag -width tenletters
56 Display usage information and exit immediately.
58 Display program version and exit immediately.
64 .Bl -tag -width checkout
71 .Op Fl r Ar repository-path
75 Create an initial commit in a repository from the file hierarchy
78 The created commit will not have any parent commits, i.e. it will be a
80 Also create a new reference which provides a branch name for the newly
82 Show the path of each imported file to indicate progress.
88 environment variable to be set,
89 unless an author has been configured in
95 configuration settings can be obtained from the repository's
97 file or from Git's global
108 If this option is not specified, a branch corresponding to the repository's
109 HEAD reference will be used.
110 Use of this option is required if the branch resolved via the repository's
111 HEAD reference already exists.
113 Ignore files or directories with a name which matches the specified
115 This option may be specified multiple times to build a list of ignore patterns.
118 follows the globbing rules documented in
120 Ignore patterns which end with a slash,
122 will only match directories.
124 Use the specified log message when creating the new commit.
129 opens a temporary file in an editor where a log message can be written.
130 .It Fl r Ar repository-path
131 Use the repository at the specified path.
132 If not specified, assume the repository is located at or above the current
140 .Op Fl R Ar reference
145 Clone a Git repository at the specified
151 is specified, the directory name will be derived from the name of the
154 will refuse to run if the
160 specifies a protocol scheme, a server hostname, an optional port number
161 separated from the hostname by a colon, and a path to the repository on
163 .Lk scheme://hostname:port/path/to/repository
165 The following protocol schemes are supported:
166 .Bl -tag -width git+ssh
168 The Git protocol as implemented by the
171 Use of this protocol is discouraged since it supports neither authentication
174 The Git protocol wrapped in an authenticated and encrypted
177 With this protocol the hostname may contain an embedded username for
182 Short alias for git+ssh.
185 Objects in the cloned repository are stored in a pack file which is downloaded
187 This pack file will then be indexed to facilitate access to the objects stored
189 If any objects in the pack file are stored in deltified form, all deltas will
190 be fully resolved in order to compute the ID of such objects.
191 This can take some time.
192 More details about the pack file format are documented in
193 .Xr git-repository 5 .
196 creates a remote repository entry in the
200 files of the cloned repository to store the
206 arguments for future use by
216 Fetch all branches from the remote repository's
218 reference namespace and set
219 .Cm fetch_all_branches
220 in the cloned repository's
222 file for future use by
224 If this option is not specified, a branch resolved via the remote
225 repository's HEAD reference will be fetched.
226 Cannot be used together with the
232 from the remote repository's
235 This option may be specified multiple times to build a list of branches
237 If the branch corresponding to the remote repository's HEAD reference is not
238 in this list, the cloned repository's HEAD reference will be set to the first
239 branch which was fetched.
240 If this option is not specified, a branch resolved via the remote
241 repository's HEAD reference will be fetched.
242 Cannot be used together with the
246 List branches and tags available for fetching from the remote repository
247 and exit immediately.
248 Cannot be used together with any of the other options except
253 Create the cloned repository as a mirror of the original repository.
254 This is useful if the cloned repository will not be used to store
255 locally created commits.
261 files will be set up with the
263 option enabled, such that
267 will write incoming changes directly to branches in the
269 reference namespace, rather than to branches in the
272 This avoids the usual requirement of having to run
278 in order to make incoming changes appear on branches in the
281 But maintaining custom changes in the cloned repository becomes difficult
282 since such changes will be at risk of being discarded whenever incoming
285 Suppress progress reporting output.
286 The same option will be passed to
289 .It Fl R Ar reference
290 In addition to the branches and tags that will be fetched, fetch an arbitrary
292 from the remote repository's
295 This option may be specified multiple times to build a list of additional
299 may either be a path to a specific reference, or a reference namespace
300 which will cause all references in this namespace to be fetched.
302 Each reference will be mapped into the cloned repository's
304 namespace, unless the
306 option is used to mirror references directly into the cloned repository's
311 will refuse to fetch references from the remote repository's
320 to print debugging messages to standard error output.
321 This option will be passed to
324 Multiple -v options increase the verbosity.
332 .Op Fl R Ar reference
333 .Op Fl r Ar repository-path
334 .Op Ar remote-repository
337 Fetch new changes from a remote repository.
339 .Ar remote-repository
343 The remote repository's URL is obtained from the corresponding entry in
347 file of the local repository, as created by
350 By default, any branches configured in
353 .Ar remote-repository
357 is invoked in a work tree then this work tree's current branch will be
358 fetched, too, provided it is present on the server.
359 If no branches to fetch can be found in
361 or via a work tree, or said branches are not found on the server, a branch
362 resolved via the remote repository's HEAD reference will be fetched.
363 Likewise, if a HEAD reference for the
364 .Ar remote-repository
365 exists but its target no longer matches the remote HEAD, then
366 the new target branch will be fetched.
367 This default behaviour can be overridden with the
373 New changes will be stored in a separate pack file downloaded from the server.
374 Optionally, separate pack files stored in the repository can be combined with
377 By default, branch references in the
379 reference namespace will be updated to point at the newly fetched commits.
384 command can then be used to make new changes visible on branches in the
386 namespace, merging incoming changes with the changes on those branches
389 If the repository was created as a mirror with
391 then all branches in the
393 namespace will be updated directly to match the corresponding branches in
394 the remote repository.
395 If those branches contained local commits, these commits will no longer be
396 reachable via a reference and will therefore be at risk of being discarded
397 by Git's garbage collector or
398 .Cm gotadmin cleanup .
399 Maintaining custom changes in a mirror repository is therefore discouraged.
401 In any case, references in the
403 namespace will always be fetched and mapped directly to local references
404 in the same namespace.
411 Fetch all branches from the remote repository's
414 This option can be enabled by default for specific repositories in
416 Cannot be used together with the
422 from the remote repository's
425 This option may be specified multiple times to build a list of branches
427 Cannot be used together with the
431 Delete branches and tags from the local repository which are no longer
432 present in the remote repository.
433 Only references are deleted.
434 Any commit, tree, tag, and blob objects belonging to deleted branches or
435 tags remain in the repository and may be removed separately with
436 Git's garbage collector or
437 .Cm gotadmin cleanup .
439 List branches and tags available for fetching from the remote repository
440 and exit immediately.
441 Cannot be used together with any of the other options except
447 Suppress progress reporting output.
448 The same option will be passed to
451 .It Fl R Ar reference
452 In addition to the branches and tags that will be fetched, fetch an arbitrary
454 from the remote repository's
457 This option may be specified multiple times to build a list of additional
461 may either be a path to a specific reference, or a reference namespace
462 which will cause all references in this namespace to be fetched.
464 Each reference will be mapped into the local repository's
466 namespace, unless the local repository was created as a mirror with
468 in which case references will be mapped directly into the local repository's
472 Once a reference has been fetched, a branch based on it can be created with
477 will refuse to fetch references from the remote repository's
482 .It Fl r Ar repository-path
483 Use the repository at the specified path.
484 If not specified, assume the repository is located at or above the current
486 If this directory is a
488 work tree, use the repository path associated with this work tree.
490 Allow existing references in the
492 namespace to be updated if they have changed on the server.
493 If not specified, only new tag references will be created.
498 to print debugging messages to standard error output.
499 The same option will be passed to
502 Multiple -v options increase the verbosity.
505 Delete all references which correspond to a particular
506 .Ar remote-repository
507 instead of fetching new changes.
508 This can be useful when a remote repository is being removed from
514 .Ar remote-repository
515 argument is mandatory and no other options except
522 Only references are deleted.
523 Any commit, tree, tag, and blob objects fetched from a remote repository
524 will generally be stored in pack files and may be removed separately with
526 and Git's garbage collector.
534 .Op Fl p Ar path-prefix
536 .Op Ar work-tree-path
539 Copy files from a repository into a new work tree.
540 Show the status of each affected file, using the following status codes:
541 .Bl -column YXZ description
542 .It A Ta new file was added
543 .It E Ta file already exists in work tree's meta-data
548 is not specified, either use the last component of
549 .Ar repository path ,
552 was specified use the last component of
560 Check out files from a commit on the specified
562 If this option is not specified, a branch resolved via the repository's HEAD
563 reference will be used.
565 Check out files from the specified
567 on the selected branch.
568 The expected argument is a commit ID SHA1 hash or an existing reference
569 or tag name which will be resolved to a commit ID.
570 An abbreviated hash argument will be expanded to a full SHA1 hash
571 automatically, provided the abbreviation is unique.
572 If this option is not specified, the most recent commit on the selected
577 is not contained in the selected branch, a different branch which contains
578 this commit must be specified with the
581 If no such branch is known, a new branch must be created for this
587 Checking out work trees with an unknown branch is intentionally not supported.
589 Proceed with the checkout operation even if the directory at
592 Existing files will be left intact.
593 .It Fl p Ar path-prefix
594 Restrict the work tree to a subset of the repository's tree hierarchy.
595 Only files beneath the specified
599 Silence progress output.
610 Update an existing work tree to a different
612 Change existing files in the work tree as necessary to match file contents
614 Preserve any local changes in the work tree and merge them with the
617 Files which already contain merge conflicts will not be updated to avoid
618 further complications.
619 Such files will be updated when
621 is run again after merge conflicts have been resolved.
622 If the conflicting changes are no longer needed, affected files can be
629 Show the status of each affected file, using the following status codes:
630 .Bl -column YXZ description
631 .It U Ta file was updated and contained no local changes
632 .It G Ta file was updated and local changes were merged cleanly
633 .It C Ta file was updated and conflicts occurred during merge
634 .It D Ta file was deleted
635 .It d Ta file's deletion was prevented by local modifications
636 .It A Ta new file was added
637 .It \(a~ Ta versioned file is obstructed by a non-regular file
638 .It ! Ta a missing versioned file was restored
639 .It # Ta file was not updated because it contains merge conflicts
640 .It ? Ta changes destined for an unversioned file were not merged
645 is specified, update the entire work tree.
646 Otherwise, restrict the update operation to files at or within the
648 Each path is required to exist in the update operation's target commit.
649 Files in the work tree outside specified paths will remain unchanged and
650 will retain their previously recorded base commit.
653 commands may refuse to run while the work tree contains files from
654 multiple base commits.
655 The base commit of such a work tree can be made consistent by running
657 across the entire work tree.
660 is incompatible with the
665 cannot update paths with staged changes.
666 If changes have been staged with
668 these changes must first be committed with
678 Switch the work tree's branch reference to the specified
680 before updating the work tree.
681 This option requires that all paths in the work tree are updated.
683 As usual, any local changes in the work tree will be preserved.
684 This can be useful when switching to a newly created branch in order
685 to commit existing local changes to this branch.
687 Any local changes must be dealt with separately in order to obtain a
688 work tree with pristine file contents corresponding exactly to the specified
690 Such changes could first be committed to a different branch with
692 or could be discarded with
695 Update the work tree to the specified
697 The expected argument is a commit ID SHA1 hash or an existing reference
698 or tag name which will be resolved to a commit ID.
699 An abbreviated hash argument will be expanded to a full SHA1 hash
700 automatically, provided the abbreviation is unique.
701 If this option is not specified, the most recent commit on the work tree's
704 Silence progress output.
710 .Op Fl S Ar status-codes
711 .Op Fl s Ar status-codes
715 Show the current modification status of files in a work tree,
716 using the following status codes:
717 .Bl -column YXZ description
718 .It M Ta modified file
719 .It A Ta file scheduled for addition in next commit
720 .It D Ta file scheduled for deletion in next commit
721 .It C Ta modified or added file which contains merge conflicts
722 .It ! Ta versioned file was expected on disk but is missing
723 .It \(a~ Ta versioned file is obstructed by a non-regular file
724 .It ? Ta unversioned item not tracked by
726 .It m Ta modified file modes (executable bit only)
727 .It N Ta non-existent
729 specified on the command line
734 is specified, show modifications in the entire work tree.
735 Otherwise, show modifications at or within the specified paths.
737 If changes have been staged with
739 staged changes are shown in the second output column, using the following
741 .Bl -column YXZ description
742 .It M Ta file modification is staged
743 .It A Ta file addition is staged
744 .It D Ta file deletion is staged
747 Changes created on top of staged changes are indicated in the first column:
748 .Bl -column YXZ description
749 .It MM Ta file was modified after earlier changes have been staged
750 .It MA Ta file was modified after having been staged for addition
758 Show unversioned files even if they match an ignore pattern.
759 .It Fl S Ar status-codes
760 Suppress the output of files with a modification status matching any of the
761 single-character status codes contained in the
764 Any combination of codes from the above list of possible status codes
766 For staged files, status codes displayed in either column will be matched.
767 Cannot be used together with the
770 .It Fl s Ar status-codes
771 Only show files with a modification status matching any of the
772 single-character status codes contained in the
775 Any combination of codes from the above list of possible status codes
777 For staged files, status codes displayed in either column will be matched.
778 Cannot be used together with the
783 For compatibility with
794 files in each traversed directory and will not display unversioned files
795 which match these patterns.
796 Ignore patterns which end with a slash,
798 will only match directories.
803 supports consecutive asterisks,
805 which will match an arbitrary amount of directories.
809 only supports a single ignore pattern per line.
813 does not support negated ignore patterns prefixed with
815 and gives no special significance to the location of path component separators,
824 .Op Fl r Ar repository-path
825 .Op Fl S Ar search-pattern
829 Display history of a repository.
832 is specified, show only commits which modified this path.
833 If invoked in a work tree, the
835 is interpreted relative to the current working directory,
836 and the work tree's path prefix is implicitly prepended.
837 Otherwise, the path is interpreted relative to the repository root.
844 Display individual commits which were merged into the current branch
848 shows the linear history of the current branch only.
850 Set the number of context lines shown in diffs with
852 By default, 3 lines of context are shown.
854 Start traversing history at the specified
856 The expected argument is a commit ID SHA1 hash or an existing reference
857 or tag name which will be resolved to a commit ID.
858 An abbreviated hash argument will be expanded to a full SHA1 hash
859 automatically, provided the abbreviation is unique.
860 If this option is not specified, default to the work tree's current branch
861 if invoked in a work tree, or to the repository's HEAD reference.
863 Display diffstat of changes introduced in each commit.
864 Cannot be used with the
868 Limit history traversal to a given number of commits.
869 If this option is not specified, a default limit value of zero is used,
870 which is treated as an unbounded limit.
872 .Ev GOT_LOG_DEFAULT_LIMIT
873 environment variable may be set to change this default value.
875 Display the list of file paths changed in each commit, using the following
877 .Bl -column YXZ description
878 .It M Ta modified file
879 .It D Ta file was deleted
880 .It A Ta new file was added
881 .It m Ta modified file modes (executable bit only)
884 Cannot be used with the
888 Display the patch of modifications made in each commit.
891 is specified, only show the patch of modifications at or within this path.
892 Cannot be used with the
896 Determine a set of commits to display as usual, but display these commits
898 .It Fl r Ar repository-path
899 Use the repository at the specified path.
900 If not specified, assume the repository is located at or above the current
902 If this directory is a
904 work tree, use the repository path associated with this work tree.
905 .It Fl S Ar search-pattern
906 If specified, show only commits with a log message, author name,
907 committer name, or ID SHA1 hash matched by the extended regular
910 Lines in committed patches will be matched if
913 File paths changed by a commit will be matched if
916 Regular expression syntax is documented in
919 Display a short one-line summary of each commit, instead of the default
921 Cannot be used together with the
927 Stop traversing commit history immediately after the specified
930 This option has no effect if the specified
940 .Op Fl r Ar repository-path
941 .Op Ar object1 Ar object2 | Ar path ...
944 When invoked within a work tree without any arguments, display all
945 local changes in the work tree.
948 arguments are specified, only show changes within the specified paths.
950 If two arguments are provided, treat each argument as a reference, a tag
951 name, or an object ID SHA1 hash, and display differences between the
952 corresponding objects.
953 Both objects must be of the same type (blobs, trees, or commits).
954 An abbreviated hash argument will be expanded to a full SHA1 hash
955 automatically, provided the abbreviation is unique.
956 If none of these interpretations produce a valid result or if the
961 is running in a work tree, attempt to interpret the two arguments as paths.
968 Treat file contents as ASCII text even if binary data is detected.
970 Set the number of context lines shown in the diff.
971 By default, 3 lines of context are shown.
973 Show differences between commits in the repository.
974 This option may be used up to two times.
975 When used only once, show differences between the specified
977 and its first parent commit.
978 When used twice, show differences between the two specified commits.
980 The expected argument is a commit ID SHA1 hash or an existing reference
981 or tag name which will be resolved to a commit ID.
982 An abbreviated hash argument will be expanded to a full SHA1 hash
983 automatically, provided the abbreviation is unique.
987 option is used, all non-option arguments will be interpreted as paths.
990 arguments are provided, only show differences for the specified paths.
992 Cannot be used together with the
996 Display diffstat of changes before the actual diff by annotating each file path
997 or blob hash being diffed with the total number of lines added and removed.
998 A summary line will display the total number of changes across all files.
1000 Interpret all arguments as paths only.
1001 This option can be used to resolve ambiguity in cases where paths
1002 look like tag names, reference names, or object IDs.
1003 This option is only valid when
1005 is invoked in a work tree.
1006 .It Fl r Ar repository-path
1007 Use the repository at the specified path.
1008 If not specified, assume the repository is located at or above the current
1010 If this directory is a
1012 work tree, use the repository path associated with this work tree.
1014 Show changes staged with
1016 instead of showing local changes in the work tree.
1017 This option is only valid when
1019 is invoked in a work tree.
1021 Ignore whitespace-only changes.
1027 .Op Fl r Ar repository-path
1031 Display line-by-line history of a file at the specified path.
1038 Start traversing history at the specified
1040 The expected argument is a commit ID SHA1 hash or an existing reference
1041 or tag name which will be resolved to a commit ID.
1042 An abbreviated hash argument will be expanded to a full SHA1 hash
1043 automatically, provided the abbreviation is unique.
1044 .It Fl r Ar repository-path
1045 Use the repository at the specified path.
1046 If not specified, assume the repository is located at or above the current
1048 If this directory is a
1050 work tree, use the repository path associated with this work tree.
1057 .Op Fl r Ar repository-path
1061 Display a listing of files and directories at the specified
1062 directory path in the repository.
1063 Entries shown in this listing may carry one of the following trailing
1065 .Bl -column YXZ description
1066 .It @ Ta entry is a symbolic link
1067 .It / Ta entry is a directory
1068 .It * Ta entry is an executable file
1069 .It $ Ta entry is a Git submodule
1072 Symbolic link entries are also annotated with the target path of the link.
1076 is specified, list the repository path corresponding to the current
1077 directory of the work tree, or the root directory of the repository
1078 if there is no work tree.
1085 List files and directories as they appear in the specified
1087 The expected argument is a commit ID SHA1 hash or an existing reference
1088 or tag name which will be resolved to a commit ID.
1089 An abbreviated hash argument will be expanded to a full SHA1 hash
1090 automatically, provided the abbreviation is unique.
1092 Show object IDs of files (blob objects) and directories (tree objects).
1094 Recurse into sub-directories in the repository.
1095 .It Fl r Ar repository-path
1096 Use the repository at the specified path.
1097 If not specified, assume the repository is located at or above the current
1099 If this directory is a
1101 work tree, use the repository path associated with this work tree.
1107 .Op Fl r Ar repository-path
1108 .Op Fl s Ar reference
1111 Manage references in a repository.
1113 References may be listed, created, deleted, and changed.
1114 When creating, deleting, or changing a reference the specified
1116 must be an absolute reference name, i.e. it must begin with
1124 Create a reference or change an existing reference.
1125 The reference with the specified
1127 will point at the specified
1131 argument is a ID SHA1 hash or an existing reference or tag name which will
1132 be resolved to the ID of a corresponding commit, tree, tag, or blob object.
1133 Cannot be used together with any other options except
1136 Delete the reference with the specified
1138 from the repository.
1139 Any commit, tree, tag, and blob objects belonging to deleted references
1140 remain in the repository and may be removed separately with
1141 Git's garbage collector or
1142 .Cm gotadmin cleanup .
1143 Cannot be used together with any other options except
1146 List references in the repository.
1149 is specified, list all existing references in the repository.
1152 is a reference namespace, list all references in this namespace.
1153 Otherwise, show only the reference with the given
1155 Cannot be used together with any other options except
1159 .It Fl r Ar repository-path
1160 Use the repository at the specified path.
1161 If not specified, assume the repository is located at or above the current
1163 If this directory is a
1165 work tree, use the repository path associated with this work tree.
1166 .It Fl s Ar reference
1167 Create a symbolic reference, or change an existing symbolic reference.
1168 The symbolic reference with the specified
1170 will point at the specified
1172 which must already exist in the repository.
1173 Care should be taken not to create loops between references when
1174 this option is used.
1175 Cannot be used together with any other options except
1178 Sort listed references by modification time (most recently modified first)
1179 instead of sorting by lexicographical order.
1180 Use of this option requires the
1182 option to be used as well.
1190 .Op Fl r Ar repository-path
1194 Create, list, or delete branches.
1196 Local branches are managed via references which live in the
1198 reference namespace.
1201 command creates references in this namespace only.
1203 When deleting branches, the specified
1207 reference namespace first.
1208 If no corresponding branch is found, the
1210 namespace will be searched next.
1212 If invoked in a work tree without any arguments, print the name of the
1213 work tree's current branch.
1217 argument is passed, attempt to create a branch reference with the given name.
1218 By default the new branch reference will point at the latest commit on the
1219 work tree's current branch if invoked in a work tree, and otherwise to a commit
1220 resolved via the repository's HEAD reference.
1222 If invoked in a work tree, once the branch was created successfully
1223 switch the work tree's head reference to the newly created branch and
1224 update files across the entire work tree, just like
1225 .Cm got update -b Ar name
1227 Show the status of each affected file, using the following status codes:
1228 .Bl -column YXZ description
1229 .It U Ta file was updated and contained no local changes
1230 .It G Ta file was updated and local changes were merged cleanly
1231 .It C Ta file was updated and conflicts occurred during merge
1232 .It D Ta file was deleted
1233 .It A Ta new file was added
1234 .It \(a~ Ta versioned file is obstructed by a non-regular file
1235 .It ! Ta a missing versioned file was restored
1243 Make a newly created branch reference point at the specified
1247 argument is a commit ID SHA1 hash or an existing reference
1248 or tag name which will be resolved to a commit ID.
1250 Delete the branch with the specified
1256 reference namespace.
1258 Only the branch reference is deleted.
1259 Any commit, tree, and blob objects belonging to the branch
1260 remain in the repository and may be removed separately with
1261 Git's garbage collector or
1262 .Cm gotadmin cleanup .
1264 List all existing branches in the repository, including copies of remote
1265 repositories' branches in the
1267 reference namespace.
1269 If invoked in a work tree, the work tree's current branch is shown
1270 with one of the following annotations:
1271 .Bl -column YXZ description
1272 .It * Ta work tree's base commit matches the branch tip
1273 .It \(a~ Ta work tree's base commit is out-of-date
1276 Do not switch and update the work tree after creating a new branch.
1277 .It Fl r Ar repository-path
1278 Use the repository at the specified path.
1279 If not specified, assume the repository is located at or above the current
1281 If this directory is a
1283 work tree, use the repository path associated with this work tree.
1285 Sort listed branches by modification time (most recently modified first)
1286 instead of sorting by lexicographical order.
1289 reference namespace are listed before branches in
1292 Use of this option requires the
1294 option to be used as well.
1301 .Op Fl r Ar repository-path
1302 .Op Fl s Ar signer-id
1305 Manage tags in a repository.
1307 Tags are managed via references which live in the
1309 reference namespace.
1312 command operates on references in this namespace only.
1313 References in this namespace point at tag objects which contain a pointer
1314 to another object, a tag message, as well as author and timestamp information.
1316 Attempt to create a tag with the given
1318 and make this tag point at the given
1320 If no commit is specified, default to the latest commit on the work tree's
1321 current branch if invoked in a work tree, and to a commit resolved via
1322 the repository's HEAD reference otherwise.
1329 Make the newly created tag reference point at the specified
1333 argument is a commit ID SHA1 hash or an existing reference or tag name which
1334 will be resolved to a commit ID.
1335 An abbreviated hash argument will be expanded to a full SHA1 hash
1336 automatically, provided the abbreviation is unique.
1338 List all existing tags in the repository instead of creating a new tag.
1341 argument is passed, show only the tag with the given
1344 Use the specified tag message when creating the new tag.
1349 opens a temporary file in an editor where a tag message can be written.
1350 .It Fl r Ar repository-path
1351 Use the repository at the specified path.
1352 If not specified, assume the repository is located at or above the current
1354 If this directory is a
1356 work tree, use the repository path associated with this work tree.
1357 .It Fl s Ar signer-id
1358 While creating a new tag, sign this tag with the identity given in
1361 For SSH-based signatures,
1363 is the path to a file which may refer to either a private SSH key,
1364 or a public SSH key with the private half available via
1367 will sign the tag object by invoking
1371 command, using the signature namespace
1373 for compatibility with
1376 Verify tag object signatures.
1379 is specified, show and verify the tag object with the provided name.
1380 Otherwise, list all tag objects and verify signatures where present.
1383 verifies SSH-based signatures by invoking
1386 .Fl Y Cm verify Fl f Ar allowed_signers .
1391 otherwise verification is impossible.
1394 During SSH signature creation and verification this option will be passed to
1396 Multiple -v options increase the verbosity.
1402 command will not delete tags or change existing tags.
1403 If a tag must be deleted, the
1405 command may be used to delete a tag's reference.
1406 This should only be done if the tag has not already been copied to
1413 Schedule unversioned files in a work tree for addition to the
1414 repository in the next commit.
1415 By default, files which match a
1417 ignore pattern will not be added.
1421 mentioned in the command line is not an unversioned file then
1424 To avoid unnecessary errors from paths picked up by file globbing patterns
1425 in the shell, paths in the argument list will be silently ignored if they
1428 at all, or if they are reported with one of the following status codes
1429 and do not have changes staged via
1431 .Bl -column YXZ description
1432 .It M Ta modified file
1433 .It A Ta file scheduled for addition in next commit
1434 .It C Ta modified or added file which contains merge conflicts
1435 .It m Ta modified file modes (executable bit only)
1443 Add files even if they match a
1447 Permit recursion into directories.
1448 If this option is not specified,
1450 will refuse to run if a specified
1458 .Op Fl s Ar status-codes
1462 Remove versioned files from a work tree and schedule them for deletion
1463 from the repository in the next commit.
1470 Perform the operation even if a file contains local modifications,
1471 and do not raise an error if a specified
1473 does not exist on disk.
1475 Keep affected files on disk.
1477 Permit recursion into directories.
1478 If this option is not specified,
1480 will refuse to run if a specified
1483 .It Fl s Ar status-codes
1484 Only delete files with a modification status matching one of the
1485 single-character status codes contained in the
1488 The following status codes may be specified:
1489 .Bl -column YXZ description
1490 .It M Ta modified file (this implies the
1493 .It ! Ta versioned file expected on disk but missing
1501 .Op Fl p Ar strip-count
1507 to files in a work tree.
1508 Files added or removed by a patch will be scheduled for addition or removal in
1511 The patch must be in the unified diff format as produced by
1518 diff when invoked with their
1523 argument is provided, read unified diff data from standard input instead.
1527 contains multiple patches, then attempt to apply each of them in sequence.
1529 Show the status of each affected file, using the following status codes:
1530 .Bl -column XYZ description
1531 .It M Ta file was modified
1532 .It G Ta file was merged using a merge-base found in the repository
1533 .It C Ta file was merged and conflicts occurred during merge
1534 .It D Ta file was deleted
1535 .It A Ta file was added
1536 .It # Ta failed to patch the file
1539 If a change does not match at its exact line number, attempt to
1540 apply it somewhere else in the file if a good spot can be found.
1541 Otherwise, the patch will fail to apply.
1545 will refuse to apply a patch if certain preconditions are not met.
1546 Files to be deleted must already be under version control, and must
1547 not have been scheduled for deletion already.
1548 Files to be added must not yet be under version control and must not
1549 already be present on disk.
1550 Files to be modified must already be under version control and may not
1551 contain conflict markers.
1553 If an error occurs, the
1555 operation will be aborted.
1556 Any changes made to the work tree up to this point will be left behind.
1557 Such changes can be viewed with
1559 and can be reverted with
1568 Attempt to locate files within the specified
1570 for use as a merge-base for 3-way merges.
1571 Ideally, the specified
1573 should contain versions of files which the changes contained in the
1576 Files will be located by path, relative to the repository root.
1579 option is used then leading path components will be stripped
1580 before paths are looked up in the repository.
1584 option is not used then
1586 will attempt to locate merge-bases via object IDs found in
1588 meta-data, such as produced by
1594 option is only recommended in the absence of such meta-data.
1596 In case no merge-base is available for a file, changes will be applied
1597 without doing a 3-way merge.
1598 Changes which do not apply cleanly may then be rejected entirely, rather
1599 than producing merge conflicts in the patched target file.
1601 Do not make any modifications to the work tree.
1602 This can be used to check whether a patch would apply without issues.
1605 contains diffs that affect the same file multiple times, the results
1606 displayed may be incorrect.
1607 .It Fl p Ar strip-count
1608 Specify the number of leading path components to strip from paths
1617 path prefixes generated by
1619 will be recognized and stripped automatically.
1621 Reverse the patch before applying it.
1627 .Op Fl F Ar response-script
1631 Revert any local changes in files at the specified paths in a work tree.
1632 File contents will be overwritten with those contained in the
1633 work tree's base commit.
1634 There is no way to bring discarded changes back after
1637 If a file was added with
1639 it will become an unversioned file again.
1640 If a file was deleted with
1642 it will be restored.
1648 .It Fl F Ar response-script
1656 responses line-by-line from the specified
1658 file instead of prompting interactively.
1660 Instead of reverting all changes in files, interactively select or reject
1661 changes to revert based on
1667 (quit reverting this file) responses.
1668 If a file is in modified status, individual patches derived from the
1669 modified file content can be reverted.
1670 Files in added or deleted status may only be reverted in their entirety.
1672 Permit recursion into directories.
1673 If this option is not specified,
1675 will refuse to run if a specified
1689 Create a new commit in the repository from changes in a work tree
1690 and use this commit as the new base commit for the work tree.
1693 is specified, commit all changes in the work tree.
1694 Otherwise, commit changes at or within the specified paths.
1696 If changes have been explicitly staged for commit with
1698 only commit staged changes and reject any specified paths which
1699 have not been staged.
1702 opens a temporary file in an editor where a log message can be written
1710 options are used together.
1712 Show the status of each affected file, using the following status codes:
1713 .Bl -column YXZ description
1714 .It M Ta modified file
1715 .It D Ta file was deleted
1716 .It A Ta new file was added
1717 .It m Ta modified file modes (executable bit only)
1720 Files which are not part of the new commit will retain their previously
1721 recorded base commit.
1724 commands may refuse to run while the work tree contains files from
1725 multiple base commits.
1726 The base commit of such a work tree can be made consistent by running
1728 across the entire work tree.
1732 command requires the
1734 environment variable to be set,
1735 unless an author has been configured in
1741 configuration settings can be
1742 obtained from the repository's
1744 file or from Git's global
1753 Set author information in the newly created commit to
1755 This is useful when committing changes on behalf of someone else.
1758 argument must use the same format as the
1760 environment variable.
1762 In addition to storing author information, the newly created commit
1765 information which is obtained, as usual, from the
1767 environment variable, or
1769 or Git configuration settings.
1771 Allow committing files in conflicted status.
1773 Committing files with conflict markers should generally be avoided.
1774 Cases where conflict markers must be stored in the repository for
1775 some legitimate reason should be very rare.
1776 There are usually ways to avoid storing conflict markers verbatim by
1777 applying appropriate programming tricks.
1779 Use the prepared log message stored in the file found at
1781 when creating the new commit.
1783 opens a temporary file in an editor where the prepared log message can be
1784 reviewed and edited further if needed.
1785 Cannot be used together with the
1789 Use the specified log message when creating the new commit.
1790 Cannot be used together with the
1794 This option prevents
1796 from opening the commit message in an editor.
1797 It has no effect unless it is used together with the
1799 option and is intended for non-interactive use such as scripting.
1801 This option prevents
1803 from generating a diff of the to-be-committed changes in a temporary file
1804 which can be viewed while editing a commit message.
1806 Allow the addition of symbolic links which point outside of the path space
1807 that is under version control.
1810 will reject such symbolic links due to safety concerns.
1813 may decide to represent such a symbolic link as a regular file which contains
1814 the link's target path, rather than creating an actual symbolic link which
1815 points outside of the work tree.
1816 Use of this option is discouraged because external mechanisms such as
1818 are better suited for managing symbolic links to paths not under
1823 will refuse to run if certain preconditions are not met.
1824 If the work tree's current branch is not in the
1826 reference namespace, new commits may not be created on this branch.
1827 Local changes may only be committed if they are based on file content
1828 found in the most recent commit on the work tree's branch.
1829 If a path is found to be out of date,
1831 must be used first in order to merge local changes with changes made
1839 .Op Fl r Ar repository-path
1841 .Op Ar remote-repository
1844 Send new changes to a remote repository.
1846 .Ar remote-repository
1850 The remote repository's URL is obtained from the corresponding entry in
1854 file of the local repository, as created by
1857 All objects corresponding to new changes will be written to a temporary
1858 pack file which is then uploaded to the server.
1859 Upon success, references in the
1861 reference namespace of the local repository will be updated to point at
1862 the commits which have been sent.
1864 By default, changes will only be sent if they are based on up-to-date
1865 copies of relevant branches in the remote repository.
1866 If any changes to be sent are based on out-of-date copies or would
1867 otherwise break linear history of existing branches, new changes must
1868 be fetched from the server with
1870 and local branches must be rebased with
1877 option can be used to make exceptions to these requirements.
1884 Send all branches from the local repository's
1886 reference namespace.
1889 option is equivalent to listing all branches with multiple
1892 Cannot be used together with the
1898 from the local repository's
1900 reference namespace.
1901 This option may be specified multiple times to build a list of branches
1903 If this option is not specified, default to the work tree's current branch
1904 if invoked in a work tree, or to the repository's HEAD reference.
1905 Cannot be used together with the
1909 Delete the specified
1911 from the remote repository's
1913 reference namespace.
1914 This option may be specified multiple times to build a list of branches
1917 Only references are deleted.
1918 Any commit, tree, tag, and blob objects belonging to deleted branches
1919 may become subject to deletion by Git's garbage collector running on
1922 Requesting deletion of branches results in an error if the server
1923 does not support this feature or disallows the deletion of branches
1924 based on its configuration.
1926 Attempt to force the server to overwrite existing branches or tags
1927 in the remote repository, even when
1933 would usually be required before changes can be sent.
1934 The server may reject forced requests regardless, depending on its
1937 Any commit, tree, tag, and blob objects belonging to overwritten branches
1938 or tags may become subject to deletion by Git's garbage collector running
1943 reference namespace is globally shared between all repositories.
1946 option to overwrite tags is discouraged because it can lead to
1947 inconsistencies between the tags present in different repositories.
1948 In general, creating a new tag with a different name is recommended
1949 instead of overwriting an existing tag.
1953 option is particularly discouraged if changes being sent are based
1954 on an out-of-date copy of a branch in the remote repository.
1955 Instead of using the
1957 option, new changes should
1960 and local branches should be rebased with
1964 followed by another attempt to send the changes.
1968 option should only be needed in situations where the remote repository's
1969 copy of a branch or tag is known to be out-of-date and is considered
1971 The risks of creating inconsistencies between different repositories
1972 should also be taken into account.
1974 Suppress progress reporting output.
1975 The same option will be passed to
1978 .It Fl r Ar repository-path
1979 Use the repository at the specified path.
1980 If not specified, assume the repository is located at or above the current
1982 If this directory is a
1984 work tree, use the repository path associated with this work tree.
1986 Attempt to send all tags from the local repository's
1988 reference namespace.
1991 option is equivalent to listing all tags with multiple
1994 Cannot be used together with the
2000 from the local repository's
2002 reference namespace, in addition to any branches that are being sent.
2005 option may be specified multiple times to build a list of tags to send.
2006 No tags will be sent if the
2010 Raise an error if the specified
2012 already exists in the remote repository, unless the
2014 option is used to overwrite the server's copy of the tag.
2015 In general, creating a new tag with a different name is recommended
2016 instead of overwriting an existing tag.
2018 Cannot be used together with the
2025 to print debugging messages to standard error output.
2026 The same option will be passed to
2029 Multiple -v options increase the verbosity.
2039 Merge changes from a single
2044 should be on a different branch than the work tree's base commit.
2045 The expected argument is a reference or a commit ID SHA1 hash.
2046 An abbreviated hash argument will be expanded to a full SHA1 hash
2047 automatically, provided the abbreviation is unique.
2049 Show the status of each affected file, using the following status codes:
2050 .Bl -column YXZ description
2051 .It G Ta file was merged
2052 .It C Ta file was merged and conflicts occurred during merge
2053 .It ! Ta changes destined for a missing file were not merged
2054 .It D Ta file was deleted
2055 .It d Ta file's deletion was prevented by local modifications
2056 .It A Ta new file was added
2057 .It \(a~ Ta changes destined for a non-regular file were not merged
2058 .It ? Ta changes destined for an unversioned file were not merged
2061 The merged changes will appear as local changes in the work tree, which
2064 amended manually or with further
2070 If invoked in a work tree where no
2075 operation is taking place,
2077 creates a record of commits which have been merged into the work tree.
2078 When a file changed by
2082 the log messages of relevant merged commits will then appear in the editor,
2083 where the messages should be further adjusted to convey the reasons for
2084 cherrypicking the changes.
2085 Upon exiting the editor, if the time stamp of the log message file
2086 is unchanged or the log message is empty,
2088 will fail with an unmodified or empty log message error.
2090 If all the changes in all files touched by a given commit are discarded,
2093 this commit's log message record will also disappear.
2096 will refuse to run if certain preconditions are not met.
2097 If the work tree contains multiple base commits, it must first be updated
2098 to a single base commit with
2100 If any relevant files already contain merge conflicts, these
2101 conflicts must be resolved first.
2109 Display a list of commit log messages recorded by cherrypick operations,
2110 represented by references in the
2111 .Dq refs/got/worktree
2112 reference namespace.
2115 is specified, only show the log message of the specified commit.
2117 If invoked in a work tree, only log messages recorded by cherrypick operations
2118 in the current work tree will be displayed.
2119 Otherwise, all commit log messages will be displayed irrespective of the
2120 work tree in which they were created.
2121 This option cannot be used with
2124 Delete log messages created by previous cherrypick operations, represented by
2126 .Dq refs/got/worktree
2127 reference namespace.
2130 is specified, only delete the log message of the specified commit.
2132 If invoked in a work tree, only log messages recorded by cherrypick operations
2133 in the current work tree will be deleted.
2134 Otherwise, all commit log messages will be deleted irrespective of the
2135 work tree in which they were created.
2136 This option cannot be used with
2147 Reverse-merge changes from a single
2152 should be on the same branch as the work tree's base commit.
2153 The expected argument is a reference or a commit ID SHA1 hash.
2154 An abbreviated hash argument will be expanded to a full SHA1 hash
2155 automatically, provided the abbreviation is unique.
2157 Show the status of each affected file, using the following status codes:
2158 .Bl -column YXZ description
2159 .It G Ta file was merged
2160 .It C Ta file was merged and conflicts occurred during merge
2161 .It ! Ta changes destined for a missing file were not merged
2162 .It D Ta file was deleted
2163 .It d Ta file's deletion was prevented by local modifications
2164 .It A Ta new file was added
2165 .It \(a~ Ta changes destined for a non-regular file were not merged
2166 .It ? Ta changes destined for an unversioned file were not merged
2169 The reverse-merged changes will appear as local changes in the work tree,
2170 which may be viewed with
2172 amended manually or with further
2178 If invoked in a work tree where no
2183 operation is taking place,
2185 creates a record of commits which have been reverse-merged into the work tree.
2186 When a file changed by
2190 the log messages of relevant reverse-merged commits will then appear in
2191 the editor, where the messages should be further adjusted to convey the
2192 reasons for backing out the changes.
2193 Upon exiting the editor, if the time stamp of the log message file
2194 is unchanged or the log message is empty,
2196 will fail with an unmodified or empty log message error.
2198 If all the changes in all files touched by a given commit are discarded,
2201 this commit's log message record will also disappear.
2204 will refuse to run if certain preconditions are not met.
2205 If the work tree contains multiple base commits, it must first be updated
2206 to a single base commit with
2208 If any relevant files already contain merge conflicts, these
2209 conflicts must be resolved first.
2217 Display a list of commit log messages recorded by backout operations,
2218 represented by references in the
2219 .Dq refs/got/worktree
2220 reference namespace.
2223 is specified, only show the log message of the specified commit.
2225 If invoked in a work tree, only log messages recorded by backout operations
2226 in the current work tree will be displayed.
2227 Otherwise, all commit log messages will be displayed irrespective of the
2228 work tree in which they were created.
2229 This option cannot be used with
2232 Delete log messages created by previous backout operations, represented by
2234 .Dq refs/got/worktree
2235 reference namespace.
2238 is specified, only delete the log message of the specified commit.
2240 If invoked in a work tree, only log messages recorded by backout operations
2241 in the current work tree will be deleted.
2242 Otherwise, all commit log messages will be deleted irrespective of the
2243 work tree in which they were created.
2244 This option cannot be used with
2255 Rebase commits on the specified
2257 onto the tip of the current branch of the work tree.
2260 must share common ancestry with the work tree's current branch.
2261 Rebasing begins with the first descendant commit of the youngest
2262 common ancestor commit shared by the specified
2264 and the work tree's current branch, and stops once the tip commit
2271 is used as intended, the specified
2273 represents a local commit history and may already contain changes
2274 that are not yet visible in any other repositories.
2275 The work tree's current branch, which must be set with
2279 operation, represents a branch from a remote repository which shares
2280 a common history with the specified
2282 but has progressed, and perhaps diverged, due to commits added to the
2285 Rebased commits are accumulated on a temporary branch which the work tree
2286 will remain switched to throughout the entire rebase operation.
2287 Commits on this branch represent the same changes with the same log
2288 messages as their counterparts on the original
2290 but with different commit IDs.
2291 Once rebasing has completed successfully, the temporary branch becomes
2292 the new version of the specified
2294 and the work tree is automatically switched to it.
2295 If author information is available via the
2297 environment variable,
2303 configuration settings, this author information will be used to identify
2308 Old commits in their pre-rebase state are automatically backed up in the
2309 .Dq refs/got/backup/rebase
2310 reference namespace.
2311 As long as these references are not removed older versions of rebased
2312 commits will remain in the repository and can be viewed with the
2315 Removal of these references makes objects which become unreachable via
2316 any reference subject to removal by Git's garbage collector or
2317 .Cm gotadmin cleanup .
2319 While rebasing commits, show the status of each affected file,
2320 using the following status codes:
2321 .Bl -column YXZ description
2322 .It G Ta file was merged
2323 .It C Ta file was merged and conflicts occurred during merge
2324 .It ! Ta changes destined for a missing file were not merged
2325 .It D Ta file was deleted
2326 .It d Ta file's deletion was prevented by local modifications
2327 .It A Ta new file was added
2328 .It \(a~ Ta changes destined for a non-regular file were not merged
2329 .It ? Ta changes destined for an unversioned file were not merged
2332 If merge conflicts occur, the rebase operation is interrupted and may
2333 be continued once conflicts have been resolved.
2334 If any files with destined changes are found to be missing or unversioned,
2335 or if files could not be deleted due to differences in deleted content,
2336 the rebase operation will be interrupted to prevent potentially incomplete
2337 changes from being committed to the repository without user intervention.
2338 The work tree may be modified as desired and the rebase operation can be
2339 continued once the changes present in the work tree are considered complete.
2340 Alternatively, the rebase operation may be aborted which will leave
2342 unmodified and the work tree switched back to its original branch.
2344 If a merge conflict is resolved in a way which renders the merged
2345 change into a no-op change, the corresponding commit will be elided
2346 when the rebase operation continues.
2349 will refuse to run if certain preconditions are not met.
2354 reference namespace, the branch may not be rebased.
2355 If the work tree is not yet fully updated to the tip commit of its
2356 branch, then the work tree must first be updated with
2358 If changes have been staged with
2360 these changes must first be committed with
2364 If the work tree contains local changes, these changes must first be
2371 contains changes to files outside of the work tree's path prefix,
2372 the work tree cannot be used to rebase this branch.
2381 commands will refuse to run while a rebase operation is in progress.
2382 Other commands which manipulate the work tree may be used for
2383 conflict resolution purposes.
2387 is already based on the work tree's current branch, then no commits
2388 need to be rebased and
2390 will simply switch the work tree to the specified
2392 and update files in the work tree accordingly.
2399 Abort an interrupted rebase operation.
2400 If this option is used, no other command-line arguments are allowed.
2402 Allow a rebase operation to continue with files in conflicted status.
2403 This option should generally be avoided, and can only be used with the
2407 Continue an interrupted rebase operation.
2408 If this option is used, no other command-line arguments are allowed except
2411 Show a list of past rebase operations, represented by references in the
2412 .Dq refs/got/backup/rebase
2413 reference namespace.
2415 Display the author, date, and log message of each backed up commit,
2416 the object ID of the corresponding post-rebase commit, and
2417 the object ID of their common ancestor commit.
2418 Given these object IDs,
2425 options can be used to examine the history of either version of the branch,
2430 option can be used to create a new branch from a pre-rebase state if desired.
2434 is specified, only show commits which at some point in time represented this
2436 Otherwise, list all backed up commits for any branches.
2438 If this option is used,
2440 does not require a work tree.
2441 None of the other options can be used together with
2444 Delete backups created by past rebase operations, represented by references
2446 .Dq refs/got/backup/rebase
2447 reference namespace.
2451 is specified, only delete backups which at some point in time represented
2453 Otherwise, delete all references found within
2454 .Dq refs/got/backup/rebase .
2456 Any commit, tree, tag, and blob objects belonging to deleted backups
2457 remain in the repository and may be removed separately with
2458 Git's garbage collector or
2459 .Cm gotadmin cleanup .
2461 If this option is used,
2463 does not require a work tree.
2464 None of the other options can be used together with
2471 .Op Fl F Ar histedit-script
2475 Edit commit history between the work tree's current base commit and
2476 the tip commit of the work tree's current branch.
2480 command requires the
2482 environment variable to be set,
2483 unless an author has been configured in
2489 configuration settings can be obtained from the repository's
2491 file or from Git's global
2497 operation, the work tree's current branch must be set with
2499 to the branch which should be edited, unless this branch is already the
2500 current branch of the work tree.
2501 The tip of this branch represents the upper bound (inclusive) of commits
2506 Furthermore, the work tree's base commit
2509 to a point in this branch's commit history where editing should begin.
2510 This commit represents the lower bound (non-inclusive) of commits touched
2515 Editing of commit history is controlled via a
2517 which can be written in an editor based on a template, passed on the
2518 command line, or generated with the
2526 The format of the histedit script is line-based.
2527 Each line in the script begins with a command name, followed by
2528 whitespace and an argument.
2529 For most commands, the expected argument is a commit ID SHA1 hash.
2530 Any remaining text on the line is ignored.
2531 Lines which begin with the
2533 character are ignored entirely.
2535 The available histedit script commands are as follows:
2536 .Bl -column YXZ pick-commit
2537 .It Cm pick Ar commit Ta Use the specified commit as it is.
2538 .It Cm edit Ar commit Ta Apply the changes from the specified commit, but
2539 then interrupt the histedit operation for amending, without creating a commit.
2540 While the histedit operation is interrupted arbitrary files may be edited,
2541 and commands which manipulate the work tree can be used freely.
2546 commands can be used to add new files or remove existing ones.
2549 command can be used to eliminate arbitrary changes from files in the work tree.
2552 command may be used to prepare a subset of changes for inclusion in the
2556 command can be used to insert arbitrary commits into the edited history.
2557 Regular editing of history must eventually be resumed by running
2558 .Cm got histedit -c .
2559 .It Cm fold Ar commit Ta Combine the specified commit with the next commit
2560 listed further below that will be used.
2561 .It Cm drop Ar commit Ta Remove this commit from the edited history.
2562 .It Cm mesg Oo Ar log-message Oc Ta Create a new log message for the commit of
2567 command on the previous line of the histedit script.
2570 argument provides a new single-line log message to use.
2573 argument is omitted, open an editor where a new log message can be written.
2576 Every commit in the history being edited must be mentioned in the script.
2577 Lines may be re-ordered to change the order of commits in the edited history.
2578 No commit may be listed more than once.
2580 Edited commits are accumulated on a temporary branch which the work tree
2581 will remain switched to throughout the entire histedit operation.
2582 Once history editing has completed successfully, the temporary branch becomes
2583 the new version of the work tree's branch and the work tree is automatically
2586 Old commits in their pre-histedit state are automatically backed up in the
2587 .Dq refs/got/backup/histedit
2588 reference namespace.
2589 As long as these references are not removed older versions of edited
2590 commits will remain in the repository and can be viewed with the
2593 Removal of these references makes objects which become unreachable via
2594 any reference subject to removal by Git's garbage collector or
2595 .Cm gotadmin cleanup .
2597 While merging commits, show the status of each affected file,
2598 using the following status codes:
2599 .Bl -column YXZ description
2600 .It G Ta file was merged
2601 .It C Ta file was merged and conflicts occurred during merge
2602 .It ! Ta changes destined for a missing file were not merged
2603 .It D Ta file was deleted
2604 .It d Ta file's deletion was prevented by local modifications
2605 .It A Ta new file was added
2606 .It \(a~ Ta changes destined for a non-regular file were not merged
2607 .It ? Ta changes destined for an unversioned file were not merged
2610 If merge conflicts occur, the histedit operation is interrupted and may
2611 be continued once conflicts have been resolved.
2612 If any files with destined changes are found to be missing or unversioned,
2613 or if files could not be deleted due to differences in deleted content,
2614 the histedit operation will be interrupted to prevent potentially incomplete
2615 changes from being committed to the repository without user intervention.
2616 The work tree may be modified as desired and the histedit operation can be
2617 continued once the changes present in the work tree are considered complete.
2618 Alternatively, the histedit operation may be aborted which will leave
2619 the work tree switched back to its original branch.
2621 If a merge conflict is resolved in a way which renders the merged
2622 change into a no-op change, the corresponding commit will be elided
2623 when the histedit operation continues.
2626 will refuse to run if certain preconditions are not met.
2627 If the work tree's current branch is not in the
2629 reference namespace, the history of the branch may not be edited.
2630 If the work tree contains multiple base commits, it must first be updated
2631 to a single base commit with
2633 If changes have been staged with
2635 these changes must first be committed with
2639 If the work tree contains local changes, these changes must first be
2644 If the edited history contains changes to files outside of the work tree's
2645 path prefix, the work tree cannot be used to edit the history of this branch.
2653 commands will refuse to run while a histedit operation is in progress.
2654 Other commands which manipulate the work tree may be used, and the
2656 command may be used to commit arbitrary changes to the temporary branch
2657 while the histedit operation is interrupted.
2664 Abort an interrupted histedit operation.
2665 If this option is used, no other command-line arguments are allowed.
2667 Allow a histedit operation to continue with files in conflicted status.
2668 This option should generally be avoided, and can only be used with the
2672 Continue an interrupted histedit operation.
2673 If this option is used, no other command-line arguments are allowed except
2677 This option is a quick equivalent to a histedit script which drops all
2681 option can only be used when starting a new histedit operation.
2682 If this option is used, no other command-line arguments are allowed.
2684 Interrupt the histedit operation for editing after merging each commit.
2685 This option is a quick equivalent to a histedit script which uses the
2687 command for all commits.
2690 option can only be used when starting a new histedit operation.
2691 If this option is used, no other command-line arguments are allowed.
2692 .It Fl F Ar histedit-script
2695 instead of opening a temporary file in an editor where a histedit script
2698 Fold all commits into a single commit.
2699 This option is a quick equivalent to a histedit script which folds all
2700 commits, combining them all into one commit.
2703 option can only be used when starting a new histedit operation.
2704 If this option is used, no other command-line arguments are allowed.
2706 Show a list of past histedit operations, represented by references in the
2707 .Dq refs/got/backup/histedit
2708 reference namespace.
2710 Display the author, date, and log message of each backed up commit,
2711 the object ID of the corresponding post-histedit commit, and
2712 the object ID of their common ancestor commit.
2713 Given these object IDs,
2720 options can be used to examine the history of either version of the branch,
2725 option can be used to create a new branch from a pre-histedit state if desired.
2729 is specified, only show commits which at some point in time represented this
2731 Otherwise, list all backed up commits for any branches.
2733 If this option is used,
2735 does not require a work tree.
2736 None of the other options can be used together with
2739 Edit log messages only.
2740 This option is a quick equivalent to a histedit script which edits
2741 only log messages but otherwise leaves every picked commit as-is.
2744 option can only be used when starting a new histedit operation.
2745 If this option is used, no other command-line arguments are allowed.
2747 Delete backups created by past histedit operations, represented by references
2749 .Dq refs/got/backup/histedit
2750 reference namespace.
2754 is specified, only delete backups which at some point in time represented
2756 Otherwise, delete all references found within
2757 .Dq refs/got/backup/histedit .
2759 Any commit, tree, tag, and blob objects belonging to deleted backups
2760 remain in the repository and may be removed separately with
2761 Git's garbage collector or
2762 .Cm gotadmin cleanup .
2764 If this option is used,
2766 does not require a work tree.
2767 None of the other options can be used together with
2771 .It Cm integrate Ar branch
2773 Integrate the specified
2775 into the work tree's current branch.
2776 Files in the work tree are updated to match the contents on the integrated
2778 and the reference of the work tree's branch is changed to point at the
2779 head commit of the integrated
2782 Both branches can be considered equivalent after integration since they
2783 will be pointing at the same commit.
2784 Both branches remain available for future work, if desired.
2785 In case the integrated
2787 is no longer needed it may be deleted with
2790 Show the status of each affected file, using the following status codes:
2791 .Bl -column YXZ description
2792 .It U Ta file was updated
2793 .It D Ta file was deleted
2794 .It A Ta new file was added
2795 .It \(a~ Ta versioned file is obstructed by a non-regular file
2796 .It ! Ta a missing versioned file was restored
2800 will refuse to run if certain preconditions are not met.
2801 Most importantly, the
2803 must have been rebased onto the work tree's current branch with
2805 before it can be integrated, in order to linearize commit history and
2806 resolve merge conflicts.
2807 If the work tree contains multiple base commits, it must first be updated
2808 to a single base commit with
2810 If changes have been staged with
2812 these changes must first be committed with
2816 If the work tree contains local changes, these changes must first be
2830 into the current branch of the work tree.
2831 If the branches have diverged, creates a merge commit.
2834 already includes all commits from the work tree's branch, updates the work
2835 tree's branch to be the same as
2837 without creating a commit, and updates the work tree to the most recent commit
2840 If a linear project history is desired, then use of
2842 should be preferred over
2844 However, even strictly linear projects may require merge commits in order
2845 to merge in new versions of third-party code stored on vendor branches
2849 Merge commits are commits based on multiple parent commits.
2850 The tip commit of the work tree's current branch, which must be in the
2852 reference namespace and must be set with
2856 operation, will be used as the first parent.
2857 The tip commit of the specified
2859 will be used as the second parent.
2861 No ancestral relationship between the two branches is required.
2862 If the two branches have already been merged previously, only new changes
2865 It is not possible to create merge commits with more than two parents.
2866 If more than one branch needs to be merged, then multiple merge commits
2867 with two parents each can be created in sequence.
2869 While merging changes found on the
2871 into the work tree, show the status of each affected file,
2872 using the following status codes:
2873 .Bl -column YXZ description
2874 .It G Ta file was merged
2875 .It C Ta file was merged and conflicts occurred during merge
2876 .It ! Ta changes destined for a missing file were not merged
2877 .It D Ta file was deleted
2878 .It d Ta file's deletion was prevented by local modifications
2879 .It A Ta new file was added
2880 .It \(a~ Ta changes destined for a non-regular file were not merged
2881 .It ? Ta changes destined for an unversioned file were not merged
2884 If merge conflicts occur, the merge operation is interrupted and conflicts
2885 must be resolved before the merge operation can continue.
2886 If any files with destined changes are found to be missing or unversioned,
2887 or if files could not be deleted due to differences in deleted content,
2888 the merge operation will be interrupted to prevent potentially incomplete
2889 changes from being committed to the repository without user intervention.
2890 The work tree may be modified as desired and the merge can be continued
2891 once the changes present in the work tree are considered complete.
2892 Alternatively, the merge operation may be aborted which will leave
2893 the work tree's current branch unmodified.
2896 will refuse to run if certain preconditions are not met.
2897 If the work tree's current branch is not in the
2899 reference namespace then the work tree must first be switched to a
2904 If the work tree is not yet fully updated to the tip commit of its
2905 branch, then the work tree must first be updated with
2907 If the work tree contains multiple base commits, it must first be updated
2908 to a single base commit with
2910 If changes have been staged with
2912 these changes must first be committed with
2916 If the work tree contains local changes, these changes must first be
2923 contains changes to files outside of the work tree's path prefix,
2924 the work tree cannot be used to merge this branch.
2934 commands will refuse to run while a merge operation is in progress.
2935 Other commands which manipulate the work tree may be used for
2936 conflict resolution purposes.
2943 Abort an interrupted merge operation.
2944 If this option is used, no other command-line arguments are allowed.
2946 Allow a merge operation to continue with files in conflicted status.
2947 This option should generally be avoided, and can only be used with the
2951 Continue an interrupted merge operation.
2952 If this option is used, no other command-line arguments are allowed except
2955 Create a merge commit even if the branches have not diverged.
2957 Merge changes into the work tree as usual but do not create a merge
2959 The merge result can be adjusted as desired before a merge commit is
2962 Alternatively, the merge may be aborted with
2969 .Op Fl F Ar response-script
2973 Stage local changes for inclusion in the next commit.
2976 is specified, stage all changes in the work tree.
2977 Otherwise, stage changes at or within the specified paths.
2978 Paths may be staged if they are added, modified, or deleted according to
2981 Show the status of each affected file, using the following status codes:
2982 .Bl -column YXZ description
2983 .It A Ta file addition has been staged
2984 .It M Ta file modification has been staged
2985 .It D Ta file deletion has been staged
2988 Staged file contents are saved in newly created blob objects in the repository.
2989 These blobs will be referred to by tree objects once staged changes have been
2992 Staged changes affect the behaviour of
2997 While paths with staged changes exist, the
2999 command will refuse to commit any paths which do not have staged changes.
3000 Local changes created on top of staged changes can only be committed if
3001 the path is staged again, or if the staged changes are committed first.
3004 command will show both local changes and staged changes.
3007 command is able to display local changes relative to staged changes,
3008 and to display staged changes relative to the repository.
3011 command cannot revert staged changes but may be used to revert
3012 local changes created on top of staged changes.
3018 .It Fl F Ar response-script
3026 responses line-by-line from the specified
3028 file instead of prompting interactively.
3030 Instead of staging new changes, list paths which are already staged,
3031 along with the IDs of staged blob objects and stage status codes.
3032 If paths were provided on the command line, show the staged paths
3033 among the specified paths.
3034 Otherwise, show all staged paths.
3036 Instead of staging the entire content of a changed file, interactively
3037 select or reject changes for staging based on
3041 (reject change), and
3043 (quit staging this file) responses.
3044 If a file is in modified status, individual patches derived from the
3045 modified file content can be staged.
3046 Files in added or deleted status may only be staged or rejected in
3049 Allow staging of symbolic links which point outside of the path space
3050 that is under version control.
3053 will reject such symbolic links due to safety concerns.
3056 may decide to represent such a symbolic link as a regular file which contains
3057 the link's target path, rather than creating an actual symbolic link which
3058 points outside of the work tree.
3059 Use of this option is discouraged because external mechanisms such as
3061 are better suited for managing symbolic links to paths not under
3066 will refuse to run if certain preconditions are not met.
3067 If a file contains merge conflicts, these conflicts must be resolved first.
3068 If a file is found to be out of date relative to the head commit on the
3069 work tree's current branch, the file must be updated with
3071 before it can be staged (however, this does not prevent the file from
3072 becoming out-of-date at some point after having been staged).
3080 commands will refuse to run while staged changes exist.
3081 If staged changes cannot be committed because a staged path
3082 is out of date, the path must be unstaged with
3084 before it can be updated with
3086 and may then be staged again if necessary.
3091 .Op Fl F Ar response-script
3095 Merge staged changes back into the work tree and put affected paths
3096 back into non-staged status.
3099 is specified, unstage all staged changes across the entire work tree.
3100 Otherwise, unstage changes at or within the specified paths.
3102 Show the status of each affected file, using the following status codes:
3103 .Bl -column YXZ description
3104 .It G Ta file was unstaged
3105 .It C Ta file was unstaged and conflicts occurred during merge
3106 .It ! Ta changes destined for a missing file were not merged
3107 .It D Ta file was staged as deleted and still is deleted
3108 .It d Ta file's deletion was prevented by local modifications
3109 .It \(a~ Ta changes destined for a non-regular file were not merged
3116 .It Fl F Ar response-script
3124 responses line-by-line from the specified
3126 file instead of prompting interactively.
3128 Instead of unstaging the entire content of a changed file, interactively
3129 select or reject changes for unstaging based on
3133 (keep change staged), and
3135 (quit unstaging this file) responses.
3136 If a file is staged in modified status, individual patches derived from the
3137 staged file content can be unstaged.
3138 Files staged in added or deleted status may only be unstaged in their entirety.
3144 .Op Fl r Ar repository-path
3147 Parse and print contents of objects to standard output in a line-based
3149 Content of commit, tree, and tag objects is printed in a way similar
3150 to the actual content stored in such objects.
3151 Blob object contents are printed as they would appear in files on disk.
3153 Attempt to interpret each argument as a reference, a tag name, or
3154 an object ID SHA1 hash.
3155 References will be resolved to an object ID.
3156 Tag names will resolved to a tag object.
3157 An abbreviated hash argument will be expanded to a full SHA1 hash
3158 automatically, provided the abbreviation is unique.
3160 If none of the above interpretations produce a valid result, or if the
3162 option is used, attempt to interpret the argument as a path which will
3163 be resolved to the ID of an object found at this path in the repository.
3170 Look up paths in the specified
3172 If this option is not used, paths are looked up in the commit resolved
3173 via the repository's HEAD reference.
3174 The expected argument is a commit ID SHA1 hash or an existing reference
3175 or tag name which will be resolved to a commit ID.
3176 An abbreviated hash argument will be expanded to a full SHA1 hash
3177 automatically, provided the abbreviation is unique.
3179 Interpret all arguments as paths only.
3180 This option can be used to resolve ambiguity in cases where paths
3181 look like tag names, reference names, or object IDs.
3182 .It Fl r Ar repository-path
3183 Use the repository at the specified path.
3184 If not specified, assume the repository is located at or above the current
3186 If this directory is a
3188 work tree, use the repository path associated with this work tree.
3190 .It Cm info Op Ar path ...
3191 Display meta-data stored in a work tree.
3196 The work tree to use is resolved implicitly by walking upwards from the
3197 current working directory.
3201 arguments are specified, show additional per-file information for tracked
3202 files located at or within these paths.
3205 argument corresponds to the work tree's root directory, display information
3206 for all tracked files.
3209 .Bl -tag -width GOT_IGNORE_GITCONFIG
3211 The author's name and email address, such as
3212 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
3223 may fail to parse commits without an email address in author data,
3227 environment variables with a missing email address.
3229 .Ev GOT_AUTHOR will be overridden by configuration settings in
3235 configuration settings in the repository's
3242 configuration settings contained in Git's global
3244 configuration file will only be used if neither
3248 environment variable provide author information.
3249 .It Ev GOT_IGNORE_GITCONFIG
3250 If this variable is set then any remote repository definitions or author
3251 information found in Git configuration files will be ignored.
3252 .It Ev GOT_LOG_DEFAULT_LIMIT
3253 The default limit on the number of commits traversed by
3255 If set to zero, the limit is unbounded.
3256 This variable will be silently ignored if it is set to a non-numeric value.
3257 .It Ev VISUAL , EDITOR
3258 The editor spawned by
3266 text editor will be spawned.
3269 .Bl -tag -width packed-refs -compact
3271 Repository-wide configuration settings for
3275 configuration file located in the root directory of a Git repository
3276 supersedes any relevant settings in Git's
3280 .It Pa .got/got.conf
3281 Worktree-specific configuration settings for
3285 configuration file in the
3287 meta-data directory of a work tree supersedes any relevant settings in
3290 configuration file and Git's
3297 Enable tab-completion of
3302 .Dl $ set -A complete_got_1 -- $(got -h 2>&1 | sed -n s/commands://p)
3304 Clone an existing Git repository for use with
3308 .Dl $ got clone ssh://git@github.com/openbsd/src.git
3310 Unfortunately, many of the popular Git hosting sites do not offer anonymous
3312 Such sites will require an account to be created, and a public SSH key to be
3313 uploaded to this account, before repository access via ssh:// URLs will work.
3315 Use of HTTP URLs currently requires
3319 .Dl $ git clone --bare https://github.com/openbsd/src.git
3321 Alternatively, for quick and dirty local testing of
3323 a new Git repository could be created and populated with files,
3324 e.g. from a temporary CVS checkout located at
3327 .Dl $ gotadmin init /var/git/src.git
3328 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
3330 Check out a work tree from the Git repository to /usr/src:
3332 .Dl $ got checkout /var/git/src.git /usr/src
3334 View local changes in a work tree directory:
3336 .Dl $ got diff | less
3338 In a work tree, display files in a potentially problematic state:
3340 .Dl $ got status -s 'C!~?'
3342 Interactively revert selected local changes in a work tree directory:
3344 .Dl $ got revert -p -R\ .
3346 In a work tree or a git repository directory, list all branch references:
3350 As above, but list the most recently modified branches only:
3352 .Dl $ got branch -lt | head
3354 In a work tree or a git repository directory, create a new branch called
3355 .Dq unified-buffer-cache
3356 which is forked off the
3360 .Dl $ got branch -c master unified-buffer-cache
3362 Switch an existing work tree to the branch
3363 .Dq unified-buffer-cache .
3364 Local changes in the work tree will be preserved and merged if necessary:
3366 .Dl $ got update -b unified-buffer-cache
3368 Create a new commit from local changes in a work tree directory.
3369 This new commit will become the head commit of the work tree's current branch:
3373 In a work tree or a git repository directory, view changes committed in
3374 the 3 most recent commits to the work tree's branch, or the branch resolved
3375 via the repository's HEAD reference, respectively:
3377 .Dl $ got log -p -l 3
3379 As above, but display changes in the order in which
3381 could apply them in sequence:
3383 .Dl $ got log -p -l 3 -R
3385 In a work tree or a git repository directory, log the history of a subdirectory:
3387 .Dl $ got log sys/uvm
3389 While operating inside a work tree, paths are specified relative to the current
3390 working directory, so this command will log the subdirectory
3393 .Dl $ cd sys/uvm && got log\ .
3395 And this command has the same effect:
3397 .Dl $ cd sys/dev/usb && got log ../../uvm
3399 And this command displays work tree meta-data about all tracked files:
3402 .Dl $ got info\ . | less
3404 Add new files and remove obsolete files in a work tree directory:
3406 .Dl $ got add sys/uvm/uvm_ubc.c
3407 .Dl $ got remove sys/uvm/uvm_vnode.c
3409 Create a new commit from local changes in a work tree directory
3410 with a pre-defined log message.
3412 .Dl $ got commit -m 'unify the buffer cache'
3414 Alternatively, create a new commit from local changes in a work tree
3415 directory with a log message that has been prepared in the file
3418 .Dl $ got commit -F /tmp/msg
3420 Update any work tree checked out from the
3421 .Dq unified-buffer-cache
3422 branch to the latest commit on this branch:
3426 Roll file content on the unified-buffer-cache branch back by one commit,
3427 and then fetch the rolled-back change into the work tree as a local change
3428 to be amended and perhaps committed again:
3430 .Dl $ got backout unified-buffer-cache
3431 .Dl $ got commit -m 'roll back previous'
3432 .Dl $ # now back out the previous backout :-)
3433 .Dl $ got backout unified-buffer-cache
3435 Fetch new changes on the remote repository's
3437 branch, making them visible on the local repository's
3444 In a repository created with a HTTP URL and
3445 .Cm git clone --bare
3448 command must be used instead:
3450 .Dl $ cd /var/git/src.git
3451 .Dl $ git fetch origin master:refs/remotes/origin/master
3455 branch to merge the new changes that are now visible on the
3460 .Dl $ got update -b origin/master
3461 .Dl $ got rebase master
3464 .Dq unified-buffer-cache
3465 branch on top of the new head commit of the
3469 .Dl $ got update -b master
3470 .Dl $ got rebase unified-buffer-cache
3472 Create a patch from all changes on the unified-buffer-cache branch.
3473 The patch can be mailed out for review and applied to
3477 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
3479 Edit the entire commit history of the
3480 .Dq unified-buffer-cache
3483 .Dl $ got update -b unified-buffer-cache
3484 .Dl $ got update -c master
3487 Before working against existing branches in a repository cloned with
3488 .Cm git clone --bare
3493 must be configured to map all references in the remote repository
3496 namespace of the local repository.
3497 This can be achieved by setting Git's
3498 .Pa remote.origin.fetch
3499 configuration variable to the value
3500 .Dq +refs/heads/*:refs/remotes/origin/*
3505 .Dl $ cd /var/git/repo
3506 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
3510 option must be disabled:
3512 .Dl $ cd /var/git/repo
3513 .Dl $ git config remote.origin.mirror false
3515 Alternatively, the following
3517 configuration item can be added manually to the Git repository's
3521 .Dl [remote \&"origin\&"]
3523 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
3526 This configuration leaves the local repository's
3528 namespace free for use by local branches checked out with
3530 and, if needed, created with
3533 .Dq refs/remotes/origin
3534 namespace can now be updated with incoming changes from the remote
3539 without extra command line arguments.
3540 Newly fetched changes can be examined with
3543 Display changes on the remote repository's version of the
3545 branch, as of the last time
3549 .Dl $ got log -c origin/master | less
3551 As shown here, most commands accept abbreviated reference names such as
3554 .Dq refs/remotes/origin/master .
3555 The latter is only needed in case of ambiguity.
3558 can be used to merge changes which are visible on the
3563 This will also merge local changes, if any, with the incoming changes:
3565 .Dl $ got update -b origin/master
3566 .Dl $ got rebase master
3568 In order to make changes committed to the
3569 .Dq unified-buffer-cache
3573 .Dq unified-buffer-cache
3574 branch can be rebased onto the
3578 .Dl $ got update -b master
3579 .Dl $ got rebase unified-buffer-cache
3582 .Dq unified-buffer-cache
3583 branch can now be made visible on the
3587 Because the rebase operation switched the work tree to the
3588 .Dq unified-buffer-cache
3589 branch, the work tree must be switched back to the
3593 .Dl $ got update -b master
3594 .Dl $ got integrate unified-buffer-cache
3598 branch, log messages for local changes can now be amended with
3600 by other developers and any other important new information:
3602 .Dl $ got update -c origin/master
3603 .Dl $ got histedit -m
3605 If the remote repository offers write access, local changes on the
3607 branch can be sent to the remote repository with
3611 can be run without further arguments.
3612 The arguments shown here match defaults, provided the work tree's
3613 current branch is the
3617 .Dl $ got send -b master origin
3619 If the remote repository requires the HTTPS protocol, the
3621 command must be used instead:
3623 .Dl $ cd /var/git/src.git
3624 .Dl $ git push origin master
3626 When making contributions to projects which use the
3628 workflow, SSH protocol repository access needs to be set up first.
3629 Once an account has been created on a Git hosting site it should
3630 be possible to upload a public SSH key for repository access
3635 workflow will usually involve two remote repositories.
3636 In the real-life example below, the
3638 repository was forked from the
3640 repository by using the Git hosting site's web interface.
3643 file in the local repository describes both remote repositories:
3644 .Bd -literal -offset indent
3645 # Jelmers's repository, which accepts pull requests
3647 server git@github.com
3649 repository "/jelmer/dulwich"
3653 # Stefan's fork, used as the default remote repository
3655 server git@github.com
3657 repository "/stspdotname/dulwich"
3662 With this configuration, Stefan can create commits on
3663 .Dq refs/heads/master
3664 and send them to the
3666 repository by running:
3668 .Dl $ got send -b master origin
3670 The changes can now be proposed to Jelmer by opening a pull request
3671 via the Git hosting site's web interface.
3672 If Jelmer requests further changes to be made, additional commits
3673 can be created on the
3675 branch and be added to the pull request by running
3679 If Jelmer prefers additional commits to be
3681 then the following commands can be used to achieve this:
3683 .Dl $ got update -b master
3684 .Dl $ got update -c origin/master
3685 .Dl $ got histedit -f
3686 .Dl $ got send -f -b master origin
3688 In addition to reviewing the pull request in the web user interface,
3689 Jelmer can fetch the pull request's branch into his local repository
3690 and create a local branch which contains the proposed changes:
3692 .Dl $ got fetch -R refs/pull/1046/head origin
3693 .Dl $ got branch -c refs/remotes/origin/pull/1046/head pr1046
3695 Once Jelmer has accepted the pull request, Stefan can fetch the
3696 merged changes, and possibly several other new changes, by running:
3698 .Dl $ got fetch upstream
3700 The merged changes will now be visible under the reference
3701 .Dq refs/remotes/upstream/master .
3704 branch can now be rebased on top of the latest changes
3707 .Dl $ got update -b upstream/master
3708 .Dl $ got rebase master
3710 As an alternative to
3712 branches can be merged with
3715 .Dl $ got update -b master
3716 .Dl $ got merge upstream/master
3718 The question of whether to rebase or merge branches is philosophical.
3719 When in doubt, refer to the software project's policies set by project
3722 As a final step, the forked repository's copy of the master branch needs
3723 to be kept in sync by sending the new changes there:
3725 .Dl $ got send -f -b master origin
3727 If multiple pull requests need to be managed in parallel, a separate branch
3728 must be created for each pull request with
3730 Each such branch can then be used as above, in place of
3731 .Dq refs/heads/master .
3732 Changes for any accepted pull requests will still appear under
3733 .Dq refs/remotes/upstream/master,
3734 regardless of which branch was used in the forked repository to
3735 create a pull request.
3739 .Xr git-repository 5 ,
3740 .Xr got-worktree 5 ,
3744 .An Anthony J. Bentley Aq Mt bentley@openbsd.org
3745 .An Christian Weisgerber Aq Mt naddy@openbsd.org
3746 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
3747 .An Josh Rickmar Aq Mt jrick@zettaport.com
3748 .An Joshua Stein Aq Mt jcs@openbsd.org
3749 .An Klemens Nanni Aq Mt kn@openbsd.org
3750 .An Martin Pieuchot Aq Mt mpi@openbsd.org
3751 .An Neels Hofmeyr Aq Mt neels@hofmeyr.de
3752 .An Omar Polo Aq Mt op@openbsd.org
3753 .An Ori Bernstein Aq Mt ori@openbsd.org
3754 .An Sebastien Marie Aq Mt semarie@openbsd.org
3755 .An Stefan Sperling Aq Mt stsp@openbsd.org
3756 .An Steven McDonald Aq Mt steven@steven-mcdonald.id.au
3757 .An Theo Buehler Aq Mt tb@openbsd.org
3758 .An Thomas Adam Aq Mt thomas@xteddy.org
3759 .An Tracey Emery Aq Mt tracey@traceyemery.net
3760 .An Yang Zhong Aq Mt yzhong@freebsdfoundation.org
3767 were derived from code under copyright by:
3769 .An Caldera International
3770 .An Daniel Hartmeier
3775 .An Jean-Francois Brousseau
3781 .An Niklas Hallqvist
3786 .An Xavier Santolaria
3789 contains code contributed to the public domain by
3790 .An Austin Appleby .
3793 is a work-in-progress and some features remain to be implemented.
3795 At present, the user has to fall back on
3797 to perform some tasks.
3801 Reading from remote repositories over HTTP or HTTPS protocols requires
3806 Writing to remote repositories over HTTP or HTTPS protocols requires
3809 The creation of merge commits with more than two parent commits requires
3812 In situations where files or directories were moved around
3814 will not automatically merge changes to new locations and
3816 will usually produce better results.
