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.
22 .Nd CVS-like Git client
30 is a Git-compatible version control system with a user interface
35 supports local and remote Git repositories.
36 The Git repository format is described in
37 .Xr git-repository 5 .
41 must be checked out from the repository for modification.
42 Checked out files are stored in a
44 which can be placed at an arbitrary directory in the filesystem hierarchy.
45 The on-disk format of this work tree is described in
49 provides global and command-specific options.
50 Global options must precede the command name, and are as follows:
51 .Bl -tag -width tenletters
53 Display usage information and exit immediately.
55 Display program version and exit immediately.
61 .Bl -tag -width checkout
68 .Op Fl r Ar repository-path
72 Create an initial commit in a repository from the file hierarchy
75 The created commit will not have any parent commits, i.e. it will be a
77 Also create a new reference which provides a branch name for the newly
79 Show the path of each imported file to indicate progress.
85 environment variable to be set,
86 unless an author has been configured in
92 configuration settings can be obtained from the repository's
94 file or from Git's global
105 If this option is not specified, a branch corresponding to the repository's
106 HEAD reference will be used.
107 Use of this option is required if the branch resolved via the repository's
108 HEAD reference already exists.
110 Ignore files or directories with a name which matches the specified
112 This option may be specified multiple times to build a list of ignore patterns.
115 follows the globbing rules documented in
117 Ignore patterns which end with a slash,
119 will only match directories.
121 Use the specified log message when creating the new commit.
126 opens a temporary file in an editor where a log message can be written.
127 .It Fl r Ar repository-path
128 Use the repository at the specified path.
129 If not specified, assume the repository is located at or above the current
137 .Op Fl R Ar reference
142 Clone a Git repository at the specified
148 is specified, the directory name will be derived from the name of the
151 will refuse to run if the
157 specifies a protocol scheme, a server hostname, an optional port number
158 separated from the hostname by a colon, and a path to the repository on
160 .Lk scheme://hostname:port/path/to/repository
162 The following protocol schemes are supported:
163 .Bl -tag -width git+ssh
165 The Git protocol as implemented by the
168 Use of this protocol is discouraged since it supports neither authentication
171 The Git protocol wrapped in an authenticated and encrypted
174 With this protocol the hostname may contain an embedded username for
179 Short alias for git+ssh.
182 Objects in the cloned repository are stored in a pack file which is downloaded
184 This pack file will then be indexed to facilitate access to the objects stored
186 If any objects in the pack file are stored in deltified form, all deltas will
187 be fully resolved in order to compute the ID of such objects.
188 This can take some time.
189 More details about the pack file format are documented in
190 .Xr git-repository 5 .
193 creates a remote repository entry in the
197 files of the cloned repository to store the
203 arguments for future use by
213 Fetch all branches from the remote repository's
215 reference namespace and set
216 .Cm fetch_all_branches
217 in the cloned repository's
219 file for future use by
221 If this option is not specified, a branch resolved via the remote
222 repository's HEAD reference will be fetched.
223 Cannot be used together with the
229 from the remote repository's
232 This option may be specified multiple times to build a list of branches
234 If the branch corresponding to the remote repository's HEAD reference is not
235 in this list, the cloned repository's HEAD reference will be set to the first
236 branch which was fetched.
237 If this option is not specified, a branch resolved via the remote
238 repository's HEAD reference will be fetched.
239 Cannot be used together with the
243 List branches and tags available for fetching from the remote repository
244 and exit immediately.
245 Cannot be used together with any of the other options except
250 Create the cloned repository as a mirror of the original repository.
251 This is useful if the cloned repository will not be used to store
252 locally created commits.
258 files will be set up with the
260 option enabled, such that
264 will write incoming changes directly to branches in the
266 reference namespace, rather than to branches in the
269 This avoids the usual requirement of having to run
275 in order to make incoming changes appear on branches in the
278 But maintaining custom changes in the cloned repository becomes difficult
279 since such changes will be at risk of being discarded whenever incoming
282 Suppress progress reporting output.
283 The same option will be passed to
286 .It Fl R Ar reference
287 In addition to the branches and tags that will be fetched, fetch an arbitrary
289 from the remote repository's
292 This option may be specified multiple times to build a list of additional
296 may either be a path to a specific reference, or a reference namespace
297 which will cause all references in this namespace to be fetched.
299 Each reference will be mapped into the cloned repository's
301 namespace, unless the
303 option is used to mirror references directly into the cloned repository's
308 will refuse to fetch references from the remote repository's
317 to print debugging messages to standard error output.
318 This option will be passed to
321 Multiple -v options increase the verbosity.
330 .Op Fl p Ar path-prefix
332 .Op Ar work-tree-path
335 Copy files from a repository into a new work tree.
336 Show the status of each affected file, using the following status codes:
337 .Bl -column YXZ description
338 .It A Ta new file was added
339 .It E Ta file already exists in work tree's meta-data
344 is not specified, either use the last component of
345 .Ar repository path ,
348 was specified use the last component of
356 Check out files from a commit on the specified
358 If this option is not specified, a branch resolved via the repository's HEAD
359 reference will be used.
361 Check out files from the specified
363 on the selected branch.
364 The expected argument is a commit ID SHA1 hash or an existing reference
365 or tag name which will be resolved to a commit ID.
366 An abbreviated hash argument will be expanded to a full SHA1 hash
367 automatically, provided the abbreviation is unique.
368 If this option is not specified, the most recent commit on the selected
373 is not contained in the selected branch, a different branch which contains
374 this commit must be specified with the
377 If no such branch is known, a new branch must be created for this
383 Checking out work trees with an unknown branch is intentionally not supported.
385 Proceed with the checkout operation even if the directory at
388 Existing files will be left intact.
389 .It Fl p Ar path-prefix
390 Restrict the work tree to a subset of the repository's tree hierarchy.
391 Only files beneath the specified
395 Silence progress output.
406 Update an existing work tree to a different
408 Change existing files in the work tree as necessary to match file contents
410 Preserve any local changes in the work tree and merge them with the
413 Files which already contain merge conflicts will not be updated to avoid
414 further complications.
415 Such files will be updated when
417 is run again after merge conflicts have been resolved.
418 If the conflicting changes are no longer needed, affected files can be
425 Show the status of each affected file, using the following status codes:
426 .Bl -column YXZ description
427 .It U Ta file was updated and contained no local changes
428 .It G Ta file was updated and local changes were merged cleanly
429 .It C Ta file was updated and conflicts occurred during merge
430 .It D Ta file was deleted
431 .It d Ta file's deletion was prevented by local modifications
432 .It A Ta new file was added
433 .It \(a~ Ta versioned file is obstructed by a non-regular file
434 .It ! Ta a missing versioned file was restored
435 .It # Ta file was not updated because it contains merge conflicts
436 .It ? Ta changes destined for an unversioned file were not merged
441 is specified, update the entire work tree.
442 Otherwise, restrict the update operation to files at or within the
444 Each path is required to exist in the update operation's target commit.
445 Files in the work tree outside specified paths will remain unchanged and
446 will retain their previously recorded base commit.
449 commands may refuse to run while the work tree contains files from
450 multiple base commits.
451 The base commit of such a work tree can be made consistent by running
453 across the entire work tree.
456 is incompatible with the
461 cannot update paths with staged changes.
462 If changes have been staged with
464 these changes must first be committed with
474 Switch the work tree's branch reference to the specified
476 before updating the work tree.
477 This option requires that all paths in the work tree are updated.
479 As usual, any local changes in the work tree will be preserved.
480 This can be useful when switching to a newly created branch in order
481 to commit existing local changes to this branch.
483 Any local changes must be dealt with separately in order to obtain a
484 work tree with pristine file contents corresponding exactly to the specified
486 Such changes could first be committed to a different branch with
488 or could be discarded with
491 Update the work tree to the specified
493 The expected argument is a commit ID SHA1 hash or an existing reference
494 or tag name which will be resolved to a commit ID.
495 An abbreviated hash argument will be expanded to a full SHA1 hash
496 automatically, provided the abbreviation is unique.
497 If this option is not specified, the most recent commit on the work tree's
500 Silence progress output.
506 .Op Fl S Ar status-codes
507 .Op Fl s Ar status-codes
511 Show the current modification status of files in a work tree,
512 using the following status codes:
513 .Bl -column YXZ description
514 .It M Ta modified file
515 .It A Ta file scheduled for addition in next commit
516 .It D Ta file scheduled for deletion in next commit
517 .It C Ta modified or added file which contains merge conflicts
518 .It ! Ta versioned file was expected on disk but is missing
519 .It \(a~ Ta versioned file is obstructed by a non-regular file
520 .It ? Ta unversioned item not tracked by
522 .It m Ta modified file modes (executable bit only)
523 .It N Ta non-existent
525 specified on the command line
530 is specified, show modifications in the entire work tree.
531 Otherwise, show modifications at or within the specified paths.
533 If changes have been staged with
535 staged changes are shown in the second output column, using the following
537 .Bl -column YXZ description
538 .It M Ta file modification is staged
539 .It A Ta file addition is staged
540 .It D Ta file deletion is staged
543 Changes created on top of staged changes are indicated in the first column:
544 .Bl -column YXZ description
545 .It MM Ta file was modified after earlier changes have been staged
546 .It MA Ta file was modified after having been staged for addition
554 Show unversioned files even if they match an ignore pattern.
555 .It Fl S Ar status-codes
556 Suppress the output of files with a modification status matching any of the
557 single-character status codes contained in the
560 Any combination of codes from the above list of possible status codes
562 For staged files, status codes displayed in either column will be matched.
563 Cannot be used together with the
566 .It Fl s Ar status-codes
567 Only show files with a modification status matching any of the
568 single-character status codes contained in the
571 Any combination of codes from the above list of possible status codes
573 For staged files, status codes displayed in either column will be matched.
574 Cannot be used together with the
579 For compatibility with
590 files in each traversed directory and will not display unversioned files
591 which match these patterns.
592 Ignore patterns which end with a slash,
594 will only match directories.
599 supports consecutive asterisks,
601 which will match an arbitrary amount of directories.
605 only supports a single ignore pattern per line.
609 does not support negated ignore patterns prefixed with
611 and gives no special significance to the location of path component separators,
620 .Op Fl r Ar repository-path
621 .Op Fl S Ar search-pattern
625 Display history of a repository.
628 is specified, show only commits which modified this path.
629 If invoked in a work tree, the
631 is interpreted relative to the current working directory,
632 and the work tree's path prefix is implicitly prepended.
633 Otherwise, the path is interpreted relative to the repository root.
640 Display individual commits which were merged into the current branch
644 shows the linear history of the current branch only.
646 Set the number of context lines shown in diffs with
648 By default, 3 lines of context are shown.
650 Start traversing history at the specified
652 The expected argument is a commit ID SHA1 hash or an existing reference
653 or tag name which will be resolved to a commit ID.
654 An abbreviated hash argument will be expanded to a full SHA1 hash
655 automatically, provided the abbreviation is unique.
656 If this option is not specified, default to the work tree's current branch
657 if invoked in a work tree, or to the repository's HEAD reference.
659 Display diffstat of changes introduced in each commit.
660 Cannot be used with the
664 Limit history traversal to a given number of commits.
665 If this option is not specified, a default limit value of zero is used,
666 which is treated as an unbounded limit.
668 .Ev GOT_LOG_DEFAULT_LIMIT
669 environment variable may be set to change this default value.
671 Display the list of file paths changed in each commit, using the following
673 .Bl -column YXZ description
674 .It M Ta modified file
675 .It D Ta file was deleted
676 .It A Ta new file was added
677 .It m Ta modified file modes (executable bit only)
680 Cannot be used with the
684 Display the patch of modifications made in each commit.
687 is specified, only show the patch of modifications at or within this path.
688 Cannot be used with the
692 Determine a set of commits to display as usual, but display these commits
694 .It Fl r Ar repository-path
695 Use the repository at the specified path.
696 If not specified, assume the repository is located at or above the current
698 If this directory is a
700 work tree, use the repository path associated with this work tree.
701 .It Fl S Ar search-pattern
702 If specified, show only commits with a log message, author name,
703 committer name, or ID SHA1 hash matched by the extended regular
706 Lines in committed patches will be matched if
709 File paths changed by a commit will be matched if
712 Regular expression syntax is documented in
715 Display a short one-line summary of each commit, instead of the default
717 Cannot be used together with the
723 Stop traversing commit history immediately after the specified
726 This option has no effect if the specified
736 .Op Fl r Ar repository-path
737 .Op Ar object1 Ar object2 | Ar path ...
740 When invoked within a work tree without any arguments, display all
741 local changes in the work tree.
744 arguments are specified, only show changes within the specified paths.
746 If two arguments are provided, treat each argument as a reference, a tag
747 name, or an object ID SHA1 hash, and display differences between the
748 corresponding objects.
749 Both objects must be of the same type (blobs, trees, or commits).
750 An abbreviated hash argument will be expanded to a full SHA1 hash
751 automatically, provided the abbreviation is unique.
752 If none of these interpretations produce a valid result or if the
757 is running in a work tree, attempt to interpret the two arguments as paths.
764 Treat file contents as ASCII text even if binary data is detected.
766 Set the number of context lines shown in the diff.
767 By default, 3 lines of context are shown.
769 Show differences between commits in the repository.
770 This option may be used up to two times.
771 When used only once, show differences between the specified
773 and its first parent commit.
774 When used twice, show differences between the two specified commits.
776 The expected argument is a commit ID SHA1 hash or an existing reference
777 or tag name which will be resolved to a commit ID.
778 An abbreviated hash argument will be expanded to a full SHA1 hash
779 automatically, provided the abbreviation is unique.
783 option is used, all non-option arguments will be interpreted as paths.
786 arguments are provided, only show differences for the specified paths.
788 Cannot be used together with the
792 Display diffstat of changes before the actual diff by annotating each file path
793 or blob hash being diffed with the total number of lines added and removed.
794 A summary line will display the total number of changes across all files.
796 Interpret all arguments as paths only.
797 This option can be used to resolve ambiguity in cases where paths
798 look like tag names, reference names, or object IDs.
799 This option is only valid when
801 is invoked in a work tree.
802 .It Fl r Ar repository-path
803 Use the repository at the specified path.
804 If not specified, assume the repository is located at or above the current
806 If this directory is a
808 work tree, use the repository path associated with this work tree.
810 Show changes staged with
812 instead of showing local changes in the work tree.
813 This option is only valid when
815 is invoked in a work tree.
817 Ignore whitespace-only changes.
823 .Op Fl r Ar repository-path
827 Display line-by-line history of a file at the specified path.
834 Start traversing history at the specified
836 The expected argument is a commit ID SHA1 hash or an existing reference
837 or tag name which will be resolved to a commit ID.
838 An abbreviated hash argument will be expanded to a full SHA1 hash
839 automatically, provided the abbreviation is unique.
840 .It Fl r Ar repository-path
841 Use the repository at the specified path.
842 If not specified, assume the repository is located at or above the current
844 If this directory is a
846 work tree, use the repository path associated with this work tree.
853 .Op Fl r Ar repository-path
857 Display a listing of files and directories at the specified
858 directory path in the repository.
859 Entries shown in this listing may carry one of the following trailing
861 .Bl -column YXZ description
862 .It @ Ta entry is a symbolic link
863 .It / Ta entry is a directory
864 .It * Ta entry is an executable file
865 .It $ Ta entry is a Git submodule
868 Symbolic link entries are also annotated with the target path of the link.
872 is specified, list the repository path corresponding to the current
873 directory of the work tree, or the root directory of the repository
874 if there is no work tree.
881 List files and directories as they appear in the specified
883 The expected argument is a commit ID SHA1 hash or an existing reference
884 or tag name which will be resolved to a commit ID.
885 An abbreviated hash argument will be expanded to a full SHA1 hash
886 automatically, provided the abbreviation is unique.
888 Show object IDs of files (blob objects) and directories (tree objects).
890 Recurse into sub-directories in the repository.
891 .It Fl r Ar repository-path
892 Use the repository at the specified path.
893 If not specified, assume the repository is located at or above the current
895 If this directory is a
897 work tree, use the repository path associated with this work tree.
903 .Op Fl s Ar status-codes
907 Remove versioned files from a work tree and schedule them for deletion
908 from the repository in the next commit.
915 Perform the operation even if a file contains local modifications,
916 and do not raise an error if a specified
918 does not exist on disk.
920 Keep affected files on disk.
922 Permit recursion into directories.
923 If this option is not specified,
925 will refuse to run if a specified
928 .It Fl s Ar status-codes
929 Only delete files with a modification status matching one of the
930 single-character status codes contained in the
933 The following status codes may be specified:
934 .Bl -column YXZ description
935 .It M Ta modified file (this implies the
938 .It ! Ta versioned file expected on disk but missing
946 .Op Fl p Ar strip-count
952 to files in a work tree.
953 Files added or removed by a patch will be scheduled for addition or removal in
956 The patch must be in the unified diff format as produced by
963 diff when invoked with their
968 argument is provided, read unified diff data from standard input instead.
972 contains multiple patches, then attempt to apply each of them in sequence.
974 Show the status of each affected file, using the following status codes:
975 .Bl -column XYZ description
976 .It M Ta file was modified
977 .It G Ta file was merged using a merge-base found in the repository
978 .It C Ta file was merged and conflicts occurred during merge
979 .It D Ta file was deleted
980 .It A Ta file was added
981 .It # Ta failed to patch the file
984 If a change does not match at its exact line number, attempt to
985 apply it somewhere else in the file if a good spot can be found.
986 Otherwise, the patch will fail to apply.
990 will refuse to apply a patch if certain preconditions are not met.
991 Files to be deleted must already be under version control, and must
992 not have been scheduled for deletion already.
993 Files to be added must not yet be under version control and must not
994 already be present on disk.
995 Files to be modified must already be under version control and may not
996 contain conflict markers.
998 If an error occurs, the
1000 operation will be aborted.
1001 Any changes made to the work tree up to this point will be left behind.
1002 Such changes can be viewed with
1004 and can be reverted with
1013 Attempt to locate files within the specified
1015 for use as a merge-base for 3-way merges.
1016 Ideally, the specified
1018 should contain versions of files which the changes contained in the
1021 Files will be located by path, relative to the repository root.
1024 option is used then leading path components will be stripped
1025 before paths are looked up in the repository.
1029 option is not used then
1031 will attempt to locate merge-bases via object IDs found in
1033 meta-data, such as produced by
1039 option is only recommended in the absence of such meta-data.
1041 In case no merge-base is available for a file, changes will be applied
1042 without doing a 3-way merge.
1043 Changes which do not apply cleanly may then be rejected entirely, rather
1044 than producing merge conflicts in the patched target file.
1046 Do not make any modifications to the work tree.
1047 This can be used to check whether a patch would apply without issues.
1050 contains diffs that affect the same file multiple times, the results
1051 displayed may be incorrect.
1052 .It Fl p Ar strip-count
1053 Specify the number of leading path components to strip from paths
1062 path prefixes generated by
1064 will be recognized and stripped automatically.
1066 Reverse the patch before applying it.
1072 .Op Fl F Ar response-script
1076 Revert any local changes in files at the specified paths in a work tree.
1077 File contents will be overwritten with those contained in the
1078 work tree's base commit.
1079 There is no way to bring discarded changes back after
1082 If a file was added with
1084 it will become an unversioned file again.
1085 If a file was deleted with
1087 it will be restored.
1093 .It Fl F Ar response-script
1101 responses line-by-line from the specified
1103 file instead of prompting interactively.
1105 Instead of reverting all changes in files, interactively select or reject
1106 changes to revert based on
1112 (quit reverting this file) responses.
1113 If a file is in modified status, individual patches derived from the
1114 modified file content can be reverted.
1115 Files in added or deleted status may only be reverted in their entirety.
1117 Permit recursion into directories.
1118 If this option is not specified,
1120 will refuse to run if a specified
1134 Create a new commit in the repository from changes in a work tree
1135 and use this commit as the new base commit for the work tree.
1138 is specified, commit all changes in the work tree.
1139 Otherwise, commit changes at or within the specified paths.
1141 If changes have been explicitly staged for commit with
1143 only commit staged changes and reject any specified paths which
1144 have not been staged.
1147 opens a temporary file in an editor where a log message can be written
1155 options are used together.
1157 Show the status of each affected file, using the following status codes:
1158 .Bl -column YXZ description
1159 .It M Ta modified file
1160 .It D Ta file was deleted
1161 .It A Ta new file was added
1162 .It m Ta modified file modes (executable bit only)
1165 Files which are not part of the new commit will retain their previously
1166 recorded base commit.
1169 commands may refuse to run while the work tree contains files from
1170 multiple base commits.
1171 The base commit of such a work tree can be made consistent by running
1173 across the entire work tree.
1177 command requires the
1179 environment variable to be set,
1180 unless an author has been configured in
1186 configuration settings can be
1187 obtained from the repository's
1189 file or from Git's global
1198 Set author information in the newly created commit to
1200 This is useful when committing changes on behalf of someone else.
1203 argument must use the same format as the
1205 environment variable.
1207 In addition to storing author information, the newly created commit
1210 information which is obtained, as usual, from the
1212 environment variable, or
1214 or Git configuration settings.
1216 Allow committing files in conflicted status.
1218 Committing files with conflict markers should generally be avoided.
1219 Cases where conflict markers must be stored in the repository for
1220 some legitimate reason should be very rare.
1221 There are usually ways to avoid storing conflict markers verbatim by
1222 applying appropriate programming tricks.
1224 Use the prepared log message stored in the file found at
1226 when creating the new commit.
1228 opens a temporary file in an editor where the prepared log message can be
1229 reviewed and edited further if needed.
1230 Cannot be used together with the
1234 Use the specified log message when creating the new commit.
1235 Cannot be used together with the
1239 This option prevents
1241 from opening the commit message in an editor.
1242 It has no effect unless it is used together with the
1244 option and is intended for non-interactive use such as scripting.
1246 This option prevents
1248 from generating a diff of the to-be-committed changes in a temporary file
1249 which can be viewed while editing a commit message.
1251 Allow the addition of symbolic links which point outside of the path space
1252 that is under version control.
1255 will reject such symbolic links due to safety concerns.
1258 may decide to represent such a symbolic link as a regular file which contains
1259 the link's target path, rather than creating an actual symbolic link which
1260 points outside of the work tree.
1261 Use of this option is discouraged because external mechanisms such as
1263 are better suited for managing symbolic links to paths not under
1268 will refuse to run if certain preconditions are not met.
1269 If the work tree's current branch is not in the
1271 reference namespace, new commits may not be created on this branch.
1272 Local changes may only be committed if they are based on file content
1273 found in the most recent commit on the work tree's branch.
1274 If a path is found to be out of date,
1276 must be used first in order to merge local changes with changes made
1285 Merge changes from a single
1290 should be on a different branch than the work tree's base commit.
1291 The expected argument is a reference or a commit ID SHA1 hash.
1292 An abbreviated hash argument will be expanded to a full SHA1 hash
1293 automatically, provided the abbreviation is unique.
1295 Show the status of each affected file, using the following status codes:
1296 .Bl -column YXZ description
1297 .It G Ta file was merged
1298 .It C Ta file was merged and conflicts occurred during merge
1299 .It ! Ta changes destined for a missing file were not merged
1300 .It D Ta file was deleted
1301 .It d Ta file's deletion was prevented by local modifications
1302 .It A Ta new file was added
1303 .It \(a~ Ta changes destined for a non-regular file were not merged
1304 .It ? Ta changes destined for an unversioned file were not merged
1307 The merged changes will appear as local changes in the work tree, which
1310 amended manually or with further
1316 If invoked in a work tree where no
1321 operation is taking place,
1323 creates a record of commits which have been merged into the work tree.
1324 When a file changed by
1328 the log messages of relevant merged commits will then appear in the editor,
1329 where the messages should be further adjusted to convey the reasons for
1330 cherrypicking the changes.
1331 Upon exiting the editor, if the time stamp of the log message file
1332 is unchanged or the log message is empty,
1334 will fail with an unmodified or empty log message error.
1336 If all the changes in all files touched by a given commit are discarded,
1339 this commit's log message record will also disappear.
1342 will refuse to run if certain preconditions are not met.
1343 If the work tree contains multiple base commits, it must first be updated
1344 to a single base commit with
1346 If any relevant files already contain merge conflicts, these
1347 conflicts must be resolved first.
1355 Display a list of commit log messages recorded by cherrypick operations,
1356 represented by references in the
1357 .Dq refs/got/worktree
1358 reference namespace.
1361 is specified, only show the log message of the specified commit.
1363 If invoked in a work tree, only log messages recorded by cherrypick operations
1364 in the current work tree will be displayed.
1365 Otherwise, all commit log messages will be displayed irrespective of the
1366 work tree in which they were created.
1367 This option cannot be used with
1370 Delete log messages created by previous cherrypick operations, represented by
1372 .Dq refs/got/worktree
1373 reference namespace.
1376 is specified, only delete the log message of the specified commit.
1378 If invoked in a work tree, only log messages recorded by cherrypick operations
1379 in the current work tree will be deleted.
1380 Otherwise, all commit log messages will be deleted irrespective of the
1381 work tree in which they were created.
1382 This option cannot be used with
1393 Reverse-merge changes from a single
1398 should be on the same branch as the work tree's base commit.
1399 The expected argument is a reference or a commit ID SHA1 hash.
1400 An abbreviated hash argument will be expanded to a full SHA1 hash
1401 automatically, provided the abbreviation is unique.
1403 Show the status of each affected file, using the following status codes:
1404 .Bl -column YXZ description
1405 .It G Ta file was merged
1406 .It C Ta file was merged and conflicts occurred during merge
1407 .It ! Ta changes destined for a missing file were not merged
1408 .It D Ta file was deleted
1409 .It d Ta file's deletion was prevented by local modifications
1410 .It A Ta new file was added
1411 .It \(a~ Ta changes destined for a non-regular file were not merged
1412 .It ? Ta changes destined for an unversioned file were not merged
1415 The reverse-merged changes will appear as local changes in the work tree,
1416 which may be viewed with
1418 amended manually or with further
1424 If invoked in a work tree where no
1429 operation is taking place,
1431 creates a record of commits which have been reverse-merged into the work tree.
1432 When a file changed by
1436 the log messages of relevant reverse-merged commits will then appear in
1437 the editor, where the messages should be further adjusted to convey the
1438 reasons for backing out the changes.
1439 Upon exiting the editor, if the time stamp of the log message file
1440 is unchanged or the log message is empty,
1442 will fail with an unmodified or empty log message error.
1444 If all the changes in all files touched by a given commit are discarded,
1447 this commit's log message record will also disappear.
1450 will refuse to run if certain preconditions are not met.
1451 If the work tree contains multiple base commits, it must first be updated
1452 to a single base commit with
1454 If any relevant files already contain merge conflicts, these
1455 conflicts must be resolved first.
1463 Display a list of commit log messages recorded by backout operations,
1464 represented by references in the
1465 .Dq refs/got/worktree
1466 reference namespace.
1469 is specified, only show the log message of the specified commit.
1471 If invoked in a work tree, only log messages recorded by backout operations
1472 in the current work tree will be displayed.
1473 Otherwise, all commit log messages will be displayed irrespective of the
1474 work tree in which they were created.
1475 This option cannot be used with
1478 Delete log messages created by previous backout operations, represented by
1480 .Dq refs/got/worktree
1481 reference namespace.
1484 is specified, only delete the log message of the specified commit.
1486 If invoked in a work tree, only log messages recorded by backout operations
1487 in the current work tree will be deleted.
1488 Otherwise, all commit log messages will be deleted irrespective of the
1489 work tree in which they were created.
1490 This option cannot be used with
1498 .Op Fl r Ar repository-path
1501 Parse and print contents of objects to standard output in a line-based
1503 Content of commit, tree, and tag objects is printed in a way similar
1504 to the actual content stored in such objects.
1505 Blob object contents are printed as they would appear in files on disk.
1507 Attempt to interpret each argument as a reference, a tag name, or
1508 an object ID SHA1 hash.
1509 References will be resolved to an object ID.
1510 Tag names will resolved to a tag object.
1511 An abbreviated hash argument will be expanded to a full SHA1 hash
1512 automatically, provided the abbreviation is unique.
1514 If none of the above interpretations produce a valid result, or if the
1516 option is used, attempt to interpret the argument as a path which will
1517 be resolved to the ID of an object found at this path in the repository.
1524 Look up paths in the specified
1526 If this option is not used, paths are looked up in the commit resolved
1527 via the repository's HEAD reference.
1528 The expected argument is a commit ID SHA1 hash or an existing reference
1529 or tag name which will be resolved to a commit ID.
1530 An abbreviated hash argument will be expanded to a full SHA1 hash
1531 automatically, provided the abbreviation is unique.
1533 Interpret all arguments as paths only.
1534 This option can be used to resolve ambiguity in cases where paths
1535 look like tag names, reference names, or object IDs.
1536 .It Fl r Ar repository-path
1537 Use the repository at the specified path.
1538 If not specified, assume the repository is located at or above the current
1540 If this directory is a
1542 work tree, use the repository path associated with this work tree.
1544 .It Cm info Op Ar path ...
1545 Display meta-data stored in a work tree.
1550 The work tree to use is resolved implicitly by walking upwards from the
1551 current working directory.
1555 arguments are specified, show additional per-file information for tracked
1556 files located at or within these paths.
1559 argument corresponds to the work tree's root directory, display information
1560 for all tracked files.
1563 .Bl -tag -width GOT_IGNORE_GITCONFIG
1565 The author's name and email address, such as
1566 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1577 may fail to parse commits without an email address in author data,
1581 environment variables with a missing email address.
1583 .Ev GOT_AUTHOR will be overridden by configuration settings in
1589 configuration settings in the repository's
1596 configuration settings contained in Git's global
1598 configuration file will only be used if neither
1602 environment variable provide author information.
1603 .It Ev GOT_IGNORE_GITCONFIG
1604 If this variable is set then any remote repository definitions or author
1605 information found in Git configuration files will be ignored.
1606 .It Ev GOT_LOG_DEFAULT_LIMIT
1607 The default limit on the number of commits traversed by
1609 If set to zero, the limit is unbounded.
1610 This variable will be silently ignored if it is set to a non-numeric value.
1611 .It Ev VISUAL , EDITOR
1612 The editor spawned by
1620 text editor will be spawned.
1623 .Bl -tag -width packed-refs -compact
1625 Repository-wide configuration settings for
1629 configuration file located in the root directory of a Git repository
1630 supersedes any relevant settings in Git's
1634 .It Pa .got/got.conf
1635 Worktree-specific configuration settings for
1639 configuration file in the
1641 meta-data directory of a work tree supersedes any relevant settings in
1644 configuration file and Git's
1651 Enable tab-completion of
1656 .Dl $ set -A complete_got_1 -- $(got -h 2>&1 | sed -n s/commands://p)
1658 Clone an existing Git repository for use with
1662 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1664 Unfortunately, many of the popular Git hosting sites do not offer anonymous
1666 Such sites will require an account to be created, and a public SSH key to be
1667 uploaded to this account, before repository access via ssh:// URLs will work.
1669 Use of HTTP URLs currently requires
1673 .Dl $ git clone --bare https://github.com/openbsd/src.git
1675 Alternatively, for quick and dirty local testing of
1677 a new Git repository could be created and populated with files,
1678 e.g. from a temporary CVS checkout located at
1681 .Dl $ gotadmin init /var/git/src.git
1682 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1684 Check out a work tree from the Git repository to /usr/src:
1686 .Dl $ got checkout /var/git/src.git /usr/src
1688 View local changes in a work tree directory:
1690 .Dl $ got diff | less
1692 In a work tree, display files in a potentially problematic state:
1694 .Dl $ got status -s 'C!~?'
1696 Interactively revert selected local changes in a work tree directory:
1698 .Dl $ got revert -p -R\ .
1700 In a work tree or a git repository directory, list all branch references:
1704 As above, but list the most recently modified branches only:
1706 .Dl $ got branch -lt | head
1708 In a work tree or a git repository directory, create a new branch called
1709 .Dq unified-buffer-cache
1710 which is forked off the
1714 .Dl $ got branch -c master unified-buffer-cache
1716 Switch an existing work tree to the branch
1717 .Dq unified-buffer-cache .
1718 Local changes in the work tree will be preserved and merged if necessary:
1720 .Dl $ got update -b unified-buffer-cache
1722 Create a new commit from local changes in a work tree directory.
1723 This new commit will become the head commit of the work tree's current branch:
1727 In a work tree or a git repository directory, view changes committed in
1728 the 3 most recent commits to the work tree's branch, or the branch resolved
1729 via the repository's HEAD reference, respectively:
1731 .Dl $ got log -p -l 3
1733 As above, but display changes in the order in which
1735 could apply them in sequence:
1737 .Dl $ got log -p -l 3 -R
1739 In a work tree or a git repository directory, log the history of a subdirectory:
1741 .Dl $ got log sys/uvm
1743 While operating inside a work tree, paths are specified relative to the current
1744 working directory, so this command will log the subdirectory
1747 .Dl $ cd sys/uvm && got log\ .
1749 And this command has the same effect:
1751 .Dl $ cd sys/dev/usb && got log ../../uvm
1753 And this command displays work tree meta-data about all tracked files:
1756 .Dl $ got info\ . | less
1758 Add new files and remove obsolete files in a work tree directory:
1760 .Dl $ got add sys/uvm/uvm_ubc.c
1761 .Dl $ got remove sys/uvm/uvm_vnode.c
1763 Create a new commit from local changes in a work tree directory
1764 with a pre-defined log message.
1766 .Dl $ got commit -m 'unify the buffer cache'
1768 Alternatively, create a new commit from local changes in a work tree
1769 directory with a log message that has been prepared in the file
1772 .Dl $ got commit -F /tmp/msg
1774 Update any work tree checked out from the
1775 .Dq unified-buffer-cache
1776 branch to the latest commit on this branch:
1780 Roll file content on the unified-buffer-cache branch back by one commit,
1781 and then fetch the rolled-back change into the work tree as a local change
1782 to be amended and perhaps committed again:
1784 .Dl $ got backout unified-buffer-cache
1785 .Dl $ got commit -m 'roll back previous'
1786 .Dl $ # now back out the previous backout :-)
1787 .Dl $ got backout unified-buffer-cache
1789 Fetch new changes on the remote repository's
1791 branch, making them visible on the local repository's
1798 In a repository created with a HTTP URL and
1799 .Cm git clone --bare
1802 command must be used instead:
1804 .Dl $ cd /var/git/src.git
1805 .Dl $ git fetch origin master:refs/remotes/origin/master
1809 branch to merge the new changes that are now visible on the
1814 .Dl $ got update -b origin/master
1815 .Dl $ got rebase master
1818 .Dq unified-buffer-cache
1819 branch on top of the new head commit of the
1823 .Dl $ got update -b master
1824 .Dl $ got rebase unified-buffer-cache
1826 Create a patch from all changes on the unified-buffer-cache branch.
1827 The patch can be mailed out for review and applied to
1831 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1833 Edit the entire commit history of the
1834 .Dq unified-buffer-cache
1837 .Dl $ got update -b unified-buffer-cache
1838 .Dl $ got update -c master
1841 Before working against existing branches in a repository cloned with
1842 .Cm git clone --bare
1847 must be configured to map all references in the remote repository
1850 namespace of the local repository.
1851 This can be achieved by setting Git's
1852 .Pa remote.origin.fetch
1853 configuration variable to the value
1854 .Dq +refs/heads/*:refs/remotes/origin/*
1859 .Dl $ cd /var/git/repo
1860 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1864 option must be disabled:
1866 .Dl $ cd /var/git/repo
1867 .Dl $ git config remote.origin.mirror false
1869 Alternatively, the following
1871 configuration item can be added manually to the Git repository's
1875 .Dl [remote \&"origin\&"]
1877 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
1880 This configuration leaves the local repository's
1882 namespace free for use by local branches checked out with
1884 and, if needed, created with
1887 .Dq refs/remotes/origin
1888 namespace can now be updated with incoming changes from the remote
1893 without extra command line arguments.
1894 Newly fetched changes can be examined with
1897 Display changes on the remote repository's version of the
1899 branch, as of the last time
1903 .Dl $ got log -c origin/master | less
1905 As shown here, most commands accept abbreviated reference names such as
1908 .Dq refs/remotes/origin/master .
1909 The latter is only needed in case of ambiguity.
1912 can be used to merge changes which are visible on the
1917 This will also merge local changes, if any, with the incoming changes:
1919 .Dl $ got update -b origin/master
1920 .Dl $ got rebase master
1922 In order to make changes committed to the
1923 .Dq unified-buffer-cache
1927 .Dq unified-buffer-cache
1928 branch can be rebased onto the
1932 .Dl $ got update -b master
1933 .Dl $ got rebase unified-buffer-cache
1936 .Dq unified-buffer-cache
1937 branch can now be made visible on the
1941 Because the rebase operation switched the work tree to the
1942 .Dq unified-buffer-cache
1943 branch, the work tree must be switched back to the
1947 .Dl $ got update -b master
1948 .Dl $ got integrate unified-buffer-cache
1952 branch, log messages for local changes can now be amended with
1954 by other developers and any other important new information:
1956 .Dl $ got update -c origin/master
1957 .Dl $ got histedit -m
1959 If the remote repository offers write access, local changes on the
1961 branch can be sent to the remote repository with
1965 can be run without further arguments.
1966 The arguments shown here match defaults, provided the work tree's
1967 current branch is the
1971 .Dl $ got send -b master origin
1973 If the remote repository requires the HTTPS protocol, the
1975 command must be used instead:
1977 .Dl $ cd /var/git/src.git
1978 .Dl $ git push origin master
1980 When making contributions to projects which use the
1982 workflow, SSH protocol repository access needs to be set up first.
1983 Once an account has been created on a Git hosting site it should
1984 be possible to upload a public SSH key for repository access
1989 workflow will usually involve two remote repositories.
1990 In the real-life example below, the
1992 repository was forked from the
1994 repository by using the Git hosting site's web interface.
1997 file in the local repository describes both remote repositories:
1998 .Bd -literal -offset indent
1999 # Jelmers's repository, which accepts pull requests
2001 server git@github.com
2003 repository "/jelmer/dulwich"
2007 # Stefan's fork, used as the default remote repository
2009 server git@github.com
2011 repository "/stspdotname/dulwich"
2016 With this configuration, Stefan can create commits on
2017 .Dq refs/heads/master
2018 and send them to the
2020 repository by running:
2022 .Dl $ got send -b master origin
2024 The changes can now be proposed to Jelmer by opening a pull request
2025 via the Git hosting site's web interface.
2026 If Jelmer requests further changes to be made, additional commits
2027 can be created on the
2029 branch and be added to the pull request by running
2033 If Jelmer prefers additional commits to be
2035 then the following commands can be used to achieve this:
2037 .Dl $ got update -b master
2038 .Dl $ got update -c origin/master
2039 .Dl $ got histedit -f
2040 .Dl $ got send -f -b master origin
2042 In addition to reviewing the pull request in the web user interface,
2043 Jelmer can fetch the pull request's branch into his local repository
2044 and create a local branch which contains the proposed changes:
2046 .Dl $ got fetch -R refs/pull/1046/head origin
2047 .Dl $ got branch -c refs/remotes/origin/pull/1046/head pr1046
2049 Once Jelmer has accepted the pull request, Stefan can fetch the
2050 merged changes, and possibly several other new changes, by running:
2052 .Dl $ got fetch upstream
2054 The merged changes will now be visible under the reference
2055 .Dq refs/remotes/upstream/master .
2058 branch can now be rebased on top of the latest changes
2061 .Dl $ got update -b upstream/master
2062 .Dl $ got rebase master
2064 As an alternative to
2066 branches can be merged with
2069 .Dl $ got update -b master
2070 .Dl $ got merge upstream/master
2072 The question of whether to rebase or merge branches is philosophical.
2073 When in doubt, refer to the software project's policies set by project
2076 As a final step, the forked repository's copy of the master branch needs
2077 to be kept in sync by sending the new changes there:
2079 .Dl $ got send -f -b master origin
2081 If multiple pull requests need to be managed in parallel, a separate branch
2082 must be created for each pull request with
2084 Each such branch can then be used as above, in place of
2085 .Dq refs/heads/master .
2086 Changes for any accepted pull requests will still appear under
2087 .Dq refs/remotes/upstream/master,
2088 regardless of which branch was used in the forked repository to
2089 create a pull request.
2093 .Xr git-repository 5 ,
2094 .Xr got-worktree 5 ,
2098 .An Anthony J. Bentley Aq Mt bentley@openbsd.org
2099 .An Christian Weisgerber Aq Mt naddy@openbsd.org
2100 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
2101 .An Josh Rickmar Aq Mt jrick@zettaport.com
2102 .An Joshua Stein Aq Mt jcs@openbsd.org
2103 .An Klemens Nanni Aq Mt kn@openbsd.org
2104 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2105 .An Neels Hofmeyr Aq Mt neels@hofmeyr.de
2106 .An Omar Polo Aq Mt op@openbsd.org
2107 .An Ori Bernstein Aq Mt ori@openbsd.org
2108 .An Sebastien Marie Aq Mt semarie@openbsd.org
2109 .An Stefan Sperling Aq Mt stsp@openbsd.org
2110 .An Steven McDonald Aq Mt steven@steven-mcdonald.id.au
2111 .An Theo Buehler Aq Mt tb@openbsd.org
2112 .An Thomas Adam Aq Mt thomas@xteddy.org
2113 .An Tracey Emery Aq Mt tracey@traceyemery.net
2114 .An Yang Zhong Aq Mt yzhong@freebsdfoundation.org
2121 were derived from code under copyright by:
2123 .An Caldera International
2124 .An Daniel Hartmeier
2129 .An Jean-Francois Brousseau
2135 .An Niklas Hallqvist
2140 .An Xavier Santolaria
2143 contains code contributed to the public domain by
2144 .An Austin Appleby .
2147 is a work-in-progress and some features remain to be implemented.
2149 At present, the user has to fall back on
2151 to perform some tasks.
2155 Reading from remote repositories over HTTP or HTTPS protocols requires
2160 Writing to remote repositories over HTTP or HTTPS protocols requires
2163 The creation of merge commits with more than two parent commits requires
2166 In situations where files or directories were moved around
2168 will not automatically merge changes to new locations and
2170 will usually produce better results.
