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 Quitting the editor without saving the file will abort the import operation.
128 .It Fl r Ar repository-path
129 Use the repository at the specified path.
130 If not specified, assume the repository is located at or above the current
138 .Op Fl R Ar reference
143 Clone a Git repository at the specified
149 is specified, the directory name will be derived from the name of the
152 will refuse to run if the
158 specifies a protocol scheme, a server hostname, an optional port number
159 separated from the hostname by a colon, and a path to the repository on
161 .Lk scheme://hostname:port/path/to/repository
163 The following protocol schemes are supported:
164 .Bl -tag -width git+ssh
166 The Git protocol as implemented by the
169 Use of this protocol is discouraged since it supports neither authentication
172 The Git protocol wrapped in an authenticated and encrypted
175 With this protocol the hostname may contain an embedded username for
180 Short alias for git+ssh.
183 Objects in the cloned repository are stored in a pack file which is downloaded
185 This pack file will then be indexed to facilitate access to the objects stored
187 If any objects in the pack file are stored in deltified form, all deltas will
188 be fully resolved in order to compute the ID of such objects.
189 This can take some time.
190 More details about the pack file format are documented in
191 .Xr git-repository 5 .
194 creates a remote repository entry in the
198 files of the cloned repository to store the
204 arguments for future use by
214 Fetch all branches from the remote repository's
216 reference namespace and set
217 .Cm fetch_all_branches
218 in the cloned repository's
220 file for future use by
222 If this option is not specified, a branch resolved via the remote
223 repository's HEAD reference will be fetched.
224 Cannot be used together with the
230 from the remote repository's
233 This option may be specified multiple times to build a list of branches
235 If the branch corresponding to the remote repository's HEAD reference is not
236 in this list, the cloned repository's HEAD reference will be set to the first
237 branch which was fetched.
238 If this option is not specified, a branch resolved via the remote
239 repository's HEAD reference will be fetched.
240 Cannot be used together with the
244 List branches and tags available for fetching from the remote repository
245 and exit immediately.
246 Cannot be used together with any of the other options except
251 Create the cloned repository as a mirror of the original repository.
252 This is useful if the cloned repository will not be used to store
253 locally created commits.
259 files will be set up with the
261 option enabled, such that
265 will write incoming changes directly to branches in the
267 reference namespace, rather than to branches in the
270 This avoids the usual requirement of having to run
276 in order to make incoming changes appear on branches in the
279 But maintaining custom changes in the cloned repository becomes difficult
280 since such changes will be at risk of being discarded whenever incoming
283 Suppress progress reporting output.
284 The same option will be passed to
287 .It Fl R Ar reference
288 In addition to the branches and tags that will be fetched, fetch an arbitrary
290 from the remote repository's
293 This option may be specified multiple times to build a list of additional
297 may either be a path to a specific reference, or a reference namespace
298 which will cause all references in this namespace to be fetched.
300 Each reference will be mapped into the cloned repository's
302 namespace, unless the
304 option is used to mirror references directly into the cloned repository's
309 will refuse to fetch references from the remote repository's
318 to print debugging messages to standard error output.
319 This option will be passed to
322 Multiple -v options increase the verbosity.
331 .Op Fl p Ar path-prefix
333 .Op Ar work-tree-path
336 Copy files from a repository into a new work tree.
337 Show the status of each affected file, using the following status codes:
338 .Bl -column YXZ description
339 .It A Ta new file was added
340 .It E Ta file already exists in work tree's meta-data
345 is not specified, either use the last component of
346 .Ar repository path ,
349 was specified use the last component of
357 Check out files from a commit on the specified
359 If this option is not specified, a branch resolved via the repository's HEAD
360 reference will be used.
362 Check out files from the specified
364 on the selected branch.
365 The expected argument is a commit ID SHA1 hash or an existing reference
366 or tag name which will be resolved to a commit ID.
367 An abbreviated hash argument will be expanded to a full SHA1 hash
368 automatically, provided the abbreviation is unique.
369 If this option is not specified, the most recent commit on the selected
374 is not contained in the selected branch, a different branch which contains
375 this commit must be specified with the
378 If no such branch is known, a new branch must be created for this
384 Checking out work trees with an unknown branch is intentionally not supported.
386 Proceed with the checkout operation even if the directory at
389 Existing files will be left intact.
390 .It Fl p Ar path-prefix
391 Restrict the work tree to a subset of the repository's tree hierarchy.
392 Only files beneath the specified
396 Silence progress output.
407 Update an existing work tree to a different
409 Change existing files in the work tree as necessary to match file contents
411 Preserve any local changes in the work tree and merge them with the
414 Files which already contain merge conflicts will not be updated to avoid
415 further complications.
416 Such files will be updated when
418 is run again after merge conflicts have been resolved.
419 If the conflicting changes are no longer needed, affected files can be
426 Show the status of each affected file, using the following status codes:
427 .Bl -column YXZ description
428 .It U Ta file was updated and contained no local changes
429 .It G Ta file was updated and local changes were merged cleanly
430 .It C Ta file was updated and conflicts occurred during merge
431 .It D Ta file was deleted
432 .It d Ta file's deletion was prevented by local modifications
433 .It A Ta new file was added
434 .It \(a~ Ta versioned file is obstructed by a non-regular file
435 .It ! Ta a missing versioned file was restored
436 .It # Ta file was not updated because it contains merge conflicts
437 .It ? Ta changes destined for an unversioned file were not merged
442 is specified, update the entire work tree.
443 Otherwise, restrict the update operation to files at or within the
445 Each path is required to exist in the update operation's target commit.
446 Files in the work tree outside specified paths will remain unchanged and
447 will retain their previously recorded base commit.
450 commands may refuse to run while the work tree contains files from
451 multiple base commits.
452 The base commit of such a work tree can be made consistent by running
454 across the entire work tree.
457 is incompatible with the
462 cannot update paths with staged changes.
463 If changes have been staged with
465 these changes must first be committed with
475 Switch the work tree's branch reference to the specified
477 before updating the work tree.
478 This option requires that all paths in the work tree are updated.
480 As usual, any local changes in the work tree will be preserved.
481 This can be useful when switching to a newly created branch in order
482 to commit existing local changes to this branch.
484 Any local changes must be dealt with separately in order to obtain a
485 work tree with pristine file contents corresponding exactly to the specified
487 Such changes could first be committed to a different branch with
489 or could be discarded with
492 Update the work tree to the specified
494 The expected argument is a commit ID SHA1 hash or an existing reference
495 or tag name which will be resolved to a commit ID.
496 An abbreviated hash argument will be expanded to a full SHA1 hash
497 automatically, provided the abbreviation is unique.
498 If this option is not specified, the most recent commit on the work tree's
501 Silence progress output.
507 .Op Fl S Ar status-codes
508 .Op Fl s Ar status-codes
512 Show the current modification status of files in a work tree,
513 using the following status codes:
514 .Bl -column YXZ description
515 .It M Ta modified file
516 .It A Ta file scheduled for addition in next commit
517 .It D Ta file scheduled for deletion in next commit
518 .It C Ta modified or added file which contains merge conflicts
519 .It ! Ta versioned file was expected on disk but is missing
520 .It \(a~ Ta versioned file is obstructed by a non-regular file
521 .It ? Ta unversioned item not tracked by
523 .It m Ta modified file modes (executable bit only)
524 .It N Ta non-existent
526 specified on the command line
531 is specified, show modifications in the entire work tree.
532 Otherwise, show modifications at or within the specified paths.
534 If changes have been staged with
536 staged changes are shown in the second output column, using the following
538 .Bl -column YXZ description
539 .It M Ta file modification is staged
540 .It A Ta file addition is staged
541 .It D Ta file deletion is staged
544 Changes created on top of staged changes are indicated in the first column:
545 .Bl -column YXZ description
546 .It MM Ta file was modified after earlier changes have been staged
547 .It MA Ta file was modified after having been staged for addition
555 Show unversioned files even if they match an ignore pattern.
556 .It Fl S Ar status-codes
557 Suppress the output of files with a modification status matching any of the
558 single-character status codes contained in the
561 Any combination of codes from the above list of possible status codes
563 For staged files, status codes displayed in either column will be matched.
564 Cannot be used together with the
567 .It Fl s Ar status-codes
568 Only show files with a modification status matching any of the
569 single-character status codes contained in the
572 Any combination of codes from the above list of possible status codes
574 For staged files, status codes displayed in either column will be matched.
575 Cannot be used together with the
580 For compatibility with
591 files in each traversed directory and will not display unversioned files
592 which match these patterns.
593 Ignore patterns which end with a slash,
595 will only match directories.
600 supports consecutive asterisks,
602 which will match an arbitrary amount of directories.
606 only supports a single ignore pattern per line.
610 does not support negated ignore patterns prefixed with
612 and gives no special significance to the location of path component separators,
621 .Op Fl r Ar repository-path
622 .Op Fl S Ar search-pattern
626 Display history of a repository.
629 is specified, show only commits which modified this path.
630 If invoked in a work tree, the
632 is interpreted relative to the current working directory,
633 and the work tree's path prefix is implicitly prepended.
634 Otherwise, the path is interpreted relative to the repository root.
641 Display individual commits which were merged into the current branch
645 shows the linear history of the current branch only.
647 Set the number of context lines shown in diffs with
649 By default, 3 lines of context are shown.
651 Start traversing history at the specified
653 The expected argument is a commit ID SHA1 hash or an existing reference
654 or tag name which will be resolved to a commit ID.
655 An abbreviated hash argument will be expanded to a full SHA1 hash
656 automatically, provided the abbreviation is unique.
657 If this option is not specified, default to the work tree's current branch
658 if invoked in a work tree, or to the repository's HEAD reference.
660 Display diffstat of changes introduced in each commit.
661 Cannot be used with the
665 Limit history traversal to a given number of commits.
666 If this option is not specified, a default limit value of zero is used,
667 which is treated as an unbounded limit.
669 .Ev GOT_LOG_DEFAULT_LIMIT
670 environment variable may be set to change this default value.
672 Display the list of file paths changed in each commit, using the following
674 .Bl -column YXZ description
675 .It M Ta modified file
676 .It D Ta file was deleted
677 .It A Ta new file was added
678 .It m Ta modified file modes (executable bit only)
681 Cannot be used with the
685 Display the patch of modifications made in each commit.
688 is specified, only show the patch of modifications at or within this path.
689 Cannot be used with the
693 Determine a set of commits to display as usual, but display these commits
695 .It Fl r Ar repository-path
696 Use the repository at the specified path.
697 If not specified, assume the repository is located at or above the current
699 If this directory is a
701 work tree, use the repository path associated with this work tree.
702 .It Fl S Ar search-pattern
703 If specified, show only commits with a log message, author name,
704 committer name, or ID SHA1 hash matched by the extended regular
707 Lines in committed patches will be matched if
710 File paths changed by a commit will be matched if
713 Regular expression syntax is documented in
716 Display a short one-line summary of each commit, instead of the default
718 Cannot be used together with the
724 Stop traversing commit history immediately after the specified
727 This option has no effect if the specified
737 .Op Fl r Ar repository-path
738 .Op Ar object1 Ar object2 | Ar path ...
741 When invoked within a work tree without any arguments, display all
742 local changes in the work tree.
745 arguments are specified, only show changes within the specified paths.
747 If two arguments are provided, treat each argument as a reference, a tag
748 name, or an object ID SHA1 hash, and display differences between the
749 corresponding objects.
750 Both objects must be of the same type (blobs, trees, or commits).
751 An abbreviated hash argument will be expanded to a full SHA1 hash
752 automatically, provided the abbreviation is unique.
753 If none of these interpretations produce a valid result or if the
758 is running in a work tree, attempt to interpret the two arguments as paths.
765 Treat file contents as ASCII text even if binary data is detected.
767 Set the number of context lines shown in the diff.
768 By default, 3 lines of context are shown.
770 Show differences between commits in the repository.
771 This option may be used up to two times.
772 When used only once, show differences between the specified
774 and its first parent commit.
775 When used twice, show differences between the two specified commits.
777 The expected argument is a commit ID SHA1 hash or an existing reference
778 or tag name which will be resolved to a commit ID.
779 An abbreviated hash argument will be expanded to a full SHA1 hash
780 automatically, provided the abbreviation is unique.
784 option is used, all non-option arguments will be interpreted as paths.
787 arguments are provided, only show differences for the specified paths.
789 Cannot be used together with the
793 Display diffstat of changes before the actual diff by annotating each file path
794 or blob hash being diffed with the total number of lines added and removed.
795 A summary line will display the total number of changes across all files.
797 Interpret all arguments as paths only.
798 This option can be used to resolve ambiguity in cases where paths
799 look like tag names, reference names, or object IDs.
800 This option is only valid when
802 is invoked in a work tree.
803 .It Fl r Ar repository-path
804 Use the repository at the specified path.
805 If not specified, assume the repository is located at or above the current
807 If this directory is a
809 work tree, use the repository path associated with this work tree.
811 Show changes staged with
813 instead of showing local changes in the work tree.
814 This option is only valid when
816 is invoked in a work tree.
818 Ignore whitespace-only changes.
824 .Op Fl r Ar repository-path
828 Display line-by-line history of a file at the specified path.
835 Start traversing history at the specified
837 The expected argument is a commit ID SHA1 hash or an existing reference
838 or tag name which will be resolved to a commit ID.
839 An abbreviated hash argument will be expanded to a full SHA1 hash
840 automatically, provided the abbreviation is unique.
841 .It Fl r Ar repository-path
842 Use the repository at the specified path.
843 If not specified, assume the repository is located at or above the current
845 If this directory is a
847 work tree, use the repository path associated with this work tree.
854 .Op Fl r Ar repository-path
858 Display a listing of files and directories at the specified
859 directory path in the repository.
860 Entries shown in this listing may carry one of the following trailing
862 .Bl -column YXZ description
863 .It @ Ta entry is a symbolic link
864 .It / Ta entry is a directory
865 .It * Ta entry is an executable file
866 .It $ Ta entry is a Git submodule
869 Symbolic link entries are also annotated with the target path of the link.
873 is specified, list the repository path corresponding to the current
874 directory of the work tree, or the root directory of the repository
875 if there is no work tree.
882 List files and directories as they appear in the specified
884 The expected argument is a commit ID SHA1 hash or an existing reference
885 or tag name which will be resolved to a commit ID.
886 An abbreviated hash argument will be expanded to a full SHA1 hash
887 automatically, provided the abbreviation is unique.
889 Show object IDs of files (blob objects) and directories (tree objects).
891 Recurse into sub-directories in the repository.
892 .It Fl r Ar repository-path
893 Use the repository at the specified path.
894 If not specified, assume the repository is located at or above the current
896 If this directory is a
898 work tree, use the repository path associated with this work tree.
904 .Op Fl s Ar status-codes
908 Remove versioned files from a work tree and schedule them for deletion
909 from the repository in the next commit.
916 Perform the operation even if a file contains local modifications,
917 and do not raise an error if a specified
919 does not exist on disk.
921 Keep affected files on disk.
923 Permit recursion into directories.
924 If this option is not specified,
926 will refuse to run if a specified
929 .It Fl s Ar status-codes
930 Only delete files with a modification status matching one of the
931 single-character status codes contained in the
934 The following status codes may be specified:
935 .Bl -column YXZ description
936 .It M Ta modified file (this implies the
939 .It ! Ta versioned file expected on disk but missing
947 .Op Fl p Ar strip-count
953 to files in a work tree.
954 Files added or removed by a patch will be scheduled for addition or removal in
957 The patch must be in the unified diff format as produced by
964 diff when invoked with their
969 argument is provided, read unified diff data from standard input instead.
973 contains multiple patches, then attempt to apply each of them in sequence.
975 Show the status of each affected file, using the following status codes:
976 .Bl -column XYZ description
977 .It M Ta file was modified
978 .It G Ta file was merged using a merge-base found in the repository
979 .It C Ta file was merged and conflicts occurred during merge
980 .It D Ta file was deleted
981 .It A Ta file was added
982 .It # Ta failed to patch the file
985 If a change does not match at its exact line number, attempt to
986 apply it somewhere else in the file if a good spot can be found.
987 Otherwise, the patch will fail to apply.
991 will refuse to apply a patch if certain preconditions are not met.
992 Files to be deleted must already be under version control, and must
993 not have been scheduled for deletion already.
994 Files to be added must not yet be under version control and must not
995 already be present on disk.
996 Files to be modified must already be under version control and may not
997 contain conflict markers.
999 If an error occurs, the
1001 operation will be aborted.
1002 Any changes made to the work tree up to this point will be left behind.
1003 Such changes can be viewed with
1005 and can be reverted with
1014 Attempt to locate files within the specified
1016 for use as a merge-base for 3-way merges.
1017 Ideally, the specified
1019 should contain versions of files which the changes contained in the
1022 Files will be located by path, relative to the repository root.
1025 option is used then leading path components will be stripped
1026 before paths are looked up in the repository.
1030 option is not used then
1032 will attempt to locate merge-bases via object IDs found in
1034 meta-data, such as produced by
1040 option is only recommended in the absence of such meta-data.
1042 In case no merge-base is available for a file, changes will be applied
1043 without doing a 3-way merge.
1044 Changes which do not apply cleanly may then be rejected entirely, rather
1045 than producing merge conflicts in the patched target file.
1047 Do not make any modifications to the work tree.
1048 This can be used to check whether a patch would apply without issues.
1051 contains diffs that affect the same file multiple times, the results
1052 displayed may be incorrect.
1053 .It Fl p Ar strip-count
1054 Specify the number of leading path components to strip from paths
1063 path prefixes generated by
1065 will be recognized and stripped automatically.
1067 Reverse the patch before applying it.
1073 .Op Fl F Ar response-script
1077 Revert any local changes in files at the specified paths in a work tree.
1078 File contents will be overwritten with those contained in the
1079 work tree's base commit.
1080 There is no way to bring discarded changes back after
1083 If a file was added with
1085 it will become an unversioned file again.
1086 If a file was deleted with
1088 it will be restored.
1094 .It Fl F Ar response-script
1102 responses line-by-line from the specified
1104 file instead of prompting interactively.
1106 Instead of reverting all changes in files, interactively select or reject
1107 changes to revert based on
1113 (quit reverting this file) responses.
1114 If a file is in modified status, individual patches derived from the
1115 modified file content can be reverted.
1116 Files in added or deleted status may only be reverted in their entirety.
1118 Permit recursion into directories.
1119 If this option is not specified,
1121 will refuse to run if a specified
1135 Create a new commit in the repository from changes in a work tree
1136 and use this commit as the new base commit for the work tree.
1139 is specified, commit all changes in the work tree.
1140 Otherwise, commit changes at or within the specified paths.
1142 If changes have been explicitly staged for commit with
1144 only commit staged changes and reject any specified paths which
1145 have not been staged.
1148 opens a temporary file in an editor where a log message can be written
1156 options are used together.
1157 Quitting the editor without saving the file will abort the commit operation.
1159 Show the status of each affected file, using the following status codes:
1160 .Bl -column YXZ description
1161 .It M Ta modified file
1162 .It D Ta file was deleted
1163 .It A Ta new file was added
1164 .It m Ta modified file modes (executable bit only)
1167 Files which are not part of the new commit will retain their previously
1168 recorded base commit.
1171 commands may refuse to run while the work tree contains files from
1172 multiple base commits.
1173 The base commit of such a work tree can be made consistent by running
1175 across the entire work tree.
1179 command requires the
1181 environment variable to be set,
1182 unless an author has been configured in
1188 configuration settings can be
1189 obtained from the repository's
1191 file or from Git's global
1200 Set author information in the newly created commit to
1202 This is useful when committing changes on behalf of someone else.
1205 argument must use the same format as the
1207 environment variable.
1209 In addition to storing author information, the newly created commit
1212 information which is obtained, as usual, from the
1214 environment variable, or
1216 or Git configuration settings.
1218 Allow committing files in conflicted status.
1220 Committing files with conflict markers should generally be avoided.
1221 Cases where conflict markers must be stored in the repository for
1222 some legitimate reason should be very rare.
1223 There are usually ways to avoid storing conflict markers verbatim by
1224 applying appropriate programming tricks.
1226 Use the prepared log message stored in the file found at
1228 when creating the new commit.
1230 opens a temporary file in an editor where the prepared log message can be
1231 reviewed and edited further if needed.
1232 Cannot be used together with the
1236 Use the specified log message when creating the new commit.
1237 Cannot be used together with the
1241 This option prevents
1243 from opening the commit message in an editor.
1244 It has no effect unless it is used together with the
1246 option and is intended for non-interactive use such as scripting.
1248 This option prevents
1250 from generating a diff of the to-be-committed changes in a temporary file
1251 which can be viewed while editing a commit message.
1253 Allow the addition of symbolic links which point outside of the path space
1254 that is under version control.
1257 will reject such symbolic links due to safety concerns.
1260 may decide to represent such a symbolic link as a regular file which contains
1261 the link's target path, rather than creating an actual symbolic link which
1262 points outside of the work tree.
1263 Use of this option is discouraged because external mechanisms such as
1265 are better suited for managing symbolic links to paths not under
1270 will refuse to run if certain preconditions are not met.
1271 If the work tree's current branch is not in the
1273 reference namespace, new commits may not be created on this branch.
1274 Local changes may only be committed if they are based on file content
1275 found in the most recent commit on the work tree's branch.
1276 If a path is found to be out of date,
1278 must be used first in order to merge local changes with changes made
1287 Merge changes from a single
1292 should be on a different branch than the work tree's base commit.
1293 The expected argument is a reference or a commit ID SHA1 hash.
1294 An abbreviated hash argument will be expanded to a full SHA1 hash
1295 automatically, provided the abbreviation is unique.
1297 Show the status of each affected file, using the following status codes:
1298 .Bl -column YXZ description
1299 .It G Ta file was merged
1300 .It C Ta file was merged and conflicts occurred during merge
1301 .It ! Ta changes destined for a missing file were not merged
1302 .It D Ta file was deleted
1303 .It d Ta file's deletion was prevented by local modifications
1304 .It A Ta new file was added
1305 .It \(a~ Ta changes destined for a non-regular file were not merged
1306 .It ? Ta changes destined for an unversioned file were not merged
1309 The merged changes will appear as local changes in the work tree, which
1312 amended manually or with further
1318 If invoked in a work tree where no
1323 operation is taking place,
1325 creates a record of commits which have been merged into the work tree.
1326 When a file changed by
1330 the log messages of relevant merged commits will then appear in the editor,
1331 where the messages should be further adjusted to convey the reasons for
1332 cherrypicking the changes.
1333 Upon exiting the editor, if the time stamp of the log message file
1334 is unchanged or the log message is empty,
1336 will fail with an unmodified or empty log message error.
1338 If all the changes in all files touched by a given commit are discarded,
1341 this commit's log message record will also disappear.
1344 will refuse to run if certain preconditions are not met.
1345 If the work tree contains multiple base commits, it must first be updated
1346 to a single base commit with
1348 If any relevant files already contain merge conflicts, these
1349 conflicts must be resolved first.
1357 Display a list of commit log messages recorded by cherrypick operations,
1358 represented by references in the
1359 .Dq refs/got/worktree
1360 reference namespace.
1363 is specified, only show the log message of the specified commit.
1365 If invoked in a work tree, only log messages recorded by cherrypick operations
1366 in the current work tree will be displayed.
1367 Otherwise, all commit log messages will be displayed irrespective of the
1368 work tree in which they were created.
1369 This option cannot be used with
1372 Delete log messages created by previous cherrypick operations, represented by
1374 .Dq refs/got/worktree
1375 reference namespace.
1378 is specified, only delete the log message of the specified commit.
1380 If invoked in a work tree, only log messages recorded by cherrypick operations
1381 in the current work tree will be deleted.
1382 Otherwise, all commit log messages will be deleted irrespective of the
1383 work tree in which they were created.
1384 This option cannot be used with
1395 Reverse-merge changes from a single
1400 should be on the same branch as the work tree's base commit.
1401 The expected argument is a reference or a commit ID SHA1 hash.
1402 An abbreviated hash argument will be expanded to a full SHA1 hash
1403 automatically, provided the abbreviation is unique.
1405 Show the status of each affected file, using the following status codes:
1406 .Bl -column YXZ description
1407 .It G Ta file was merged
1408 .It C Ta file was merged and conflicts occurred during merge
1409 .It ! Ta changes destined for a missing file were not merged
1410 .It D Ta file was deleted
1411 .It d Ta file's deletion was prevented by local modifications
1412 .It A Ta new file was added
1413 .It \(a~ Ta changes destined for a non-regular file were not merged
1414 .It ? Ta changes destined for an unversioned file were not merged
1417 The reverse-merged changes will appear as local changes in the work tree,
1418 which may be viewed with
1420 amended manually or with further
1426 If invoked in a work tree where no
1431 operation is taking place,
1433 creates a record of commits which have been reverse-merged into the work tree.
1434 When a file changed by
1438 the log messages of relevant reverse-merged commits will then appear in
1439 the editor, where the messages should be further adjusted to convey the
1440 reasons for backing out the changes.
1441 Upon exiting the editor, if the time stamp of the log message file
1442 is unchanged or the log message is empty,
1444 will fail with an unmodified or empty log message error.
1446 If all the changes in all files touched by a given commit are discarded,
1449 this commit's log message record will also disappear.
1452 will refuse to run if certain preconditions are not met.
1453 If the work tree contains multiple base commits, it must first be updated
1454 to a single base commit with
1456 If any relevant files already contain merge conflicts, these
1457 conflicts must be resolved first.
1465 Display a list of commit log messages recorded by backout operations,
1466 represented by references in the
1467 .Dq refs/got/worktree
1468 reference namespace.
1471 is specified, only show the log message of the specified commit.
1473 If invoked in a work tree, only log messages recorded by backout operations
1474 in the current work tree will be displayed.
1475 Otherwise, all commit log messages will be displayed irrespective of the
1476 work tree in which they were created.
1477 This option cannot be used with
1480 Delete log messages created by previous backout operations, represented by
1482 .Dq refs/got/worktree
1483 reference namespace.
1486 is specified, only delete the log message of the specified commit.
1488 If invoked in a work tree, only log messages recorded by backout operations
1489 in the current work tree will be deleted.
1490 Otherwise, all commit log messages will be deleted irrespective of the
1491 work tree in which they were created.
1492 This option cannot be used with
1500 .Op Fl r Ar repository-path
1503 Parse and print contents of objects to standard output in a line-based
1505 Content of commit, tree, and tag objects is printed in a way similar
1506 to the actual content stored in such objects.
1507 Blob object contents are printed as they would appear in files on disk.
1509 Attempt to interpret each argument as a reference, a tag name, or
1510 an object ID SHA1 hash.
1511 References will be resolved to an object ID.
1512 Tag names will resolved to a tag object.
1513 An abbreviated hash argument will be expanded to a full SHA1 hash
1514 automatically, provided the abbreviation is unique.
1516 If none of the above interpretations produce a valid result, or if the
1518 option is used, attempt to interpret the argument as a path which will
1519 be resolved to the ID of an object found at this path in the repository.
1526 Look up paths in the specified
1528 If this option is not used, paths are looked up in the commit resolved
1529 via the repository's HEAD reference.
1530 The expected argument is a commit ID SHA1 hash or an existing reference
1531 or tag name which will be resolved to a commit ID.
1532 An abbreviated hash argument will be expanded to a full SHA1 hash
1533 automatically, provided the abbreviation is unique.
1535 Interpret all arguments as paths only.
1536 This option can be used to resolve ambiguity in cases where paths
1537 look like tag names, reference names, or object IDs.
1538 .It Fl r Ar repository-path
1539 Use the repository at the specified path.
1540 If not specified, assume the repository is located at or above the current
1542 If this directory is a
1544 work tree, use the repository path associated with this work tree.
1546 .It Cm info Op Ar path ...
1547 Display meta-data stored in a work tree.
1552 The work tree to use is resolved implicitly by walking upwards from the
1553 current working directory.
1557 arguments are specified, show additional per-file information for tracked
1558 files located at or within these paths.
1561 argument corresponds to the work tree's root directory, display information
1562 for all tracked files.
1565 .Bl -tag -width GOT_IGNORE_GITCONFIG
1567 The author's name and email address, such as
1568 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1579 may fail to parse commits without an email address in author data,
1583 environment variables with a missing email address.
1585 .Ev GOT_AUTHOR will be overridden by configuration settings in
1591 configuration settings in the repository's
1598 configuration settings contained in Git's global
1600 configuration file will only be used if neither
1604 environment variable provide author information.
1605 .It Ev GOT_IGNORE_GITCONFIG
1606 If this variable is set then any remote repository definitions or author
1607 information found in Git configuration files will be ignored.
1608 .It Ev GOT_LOG_DEFAULT_LIMIT
1609 The default limit on the number of commits traversed by
1611 If set to zero, the limit is unbounded.
1612 This variable will be silently ignored if it is set to a non-numeric value.
1613 .It Ev VISUAL , EDITOR
1614 The editor spawned by
1622 text editor will be spawned.
1625 .Bl -tag -width packed-refs -compact
1627 Repository-wide configuration settings for
1631 configuration file located in the root directory of a Git repository
1632 supersedes any relevant settings in Git's
1636 .It Pa .got/got.conf
1637 Worktree-specific configuration settings for
1641 configuration file in the
1643 meta-data directory of a work tree supersedes any relevant settings in
1646 configuration file and Git's
1653 Enable tab-completion of
1658 .Dl $ set -A complete_got_1 -- $(got -h 2>&1 | sed -n s/commands://p)
1660 Clone an existing Git repository for use with
1664 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1666 Unfortunately, many of the popular Git hosting sites do not offer anonymous
1668 Such sites will require an account to be created, and a public SSH key to be
1669 uploaded to this account, before repository access via ssh:// URLs will work.
1671 Use of HTTP URLs currently requires
1675 .Dl $ git clone --bare https://github.com/openbsd/src.git
1677 Alternatively, for quick and dirty local testing of
1679 a new Git repository could be created and populated with files,
1680 e.g. from a temporary CVS checkout located at
1683 .Dl $ gotadmin init /var/git/src.git
1684 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1686 Check out a work tree from the Git repository to /usr/src:
1688 .Dl $ got checkout /var/git/src.git /usr/src
1690 View local changes in a work tree directory:
1692 .Dl $ got diff | less
1694 In a work tree, display files in a potentially problematic state:
1696 .Dl $ got status -s 'C!~?'
1698 Interactively revert selected local changes in a work tree directory:
1700 .Dl $ got revert -p -R\ .
1702 In a work tree or a git repository directory, list all branch references:
1706 As above, but list the most recently modified branches only:
1708 .Dl $ got branch -lt | head
1710 In a work tree or a git repository directory, create a new branch called
1711 .Dq unified-buffer-cache
1712 which is forked off the
1716 .Dl $ got branch -c master unified-buffer-cache
1718 Switch an existing work tree to the branch
1719 .Dq unified-buffer-cache .
1720 Local changes in the work tree will be preserved and merged if necessary:
1722 .Dl $ got update -b unified-buffer-cache
1724 Create a new commit from local changes in a work tree directory.
1725 This new commit will become the head commit of the work tree's current branch:
1729 In a work tree or a git repository directory, view changes committed in
1730 the 3 most recent commits to the work tree's branch, or the branch resolved
1731 via the repository's HEAD reference, respectively:
1733 .Dl $ got log -p -l 3
1735 As above, but display changes in the order in which
1737 could apply them in sequence:
1739 .Dl $ got log -p -l 3 -R
1741 In a work tree or a git repository directory, log the history of a subdirectory:
1743 .Dl $ got log sys/uvm
1745 While operating inside a work tree, paths are specified relative to the current
1746 working directory, so this command will log the subdirectory
1749 .Dl $ cd sys/uvm && got log\ .
1751 And this command has the same effect:
1753 .Dl $ cd sys/dev/usb && got log ../../uvm
1755 And this command displays work tree meta-data about all tracked files:
1758 .Dl $ got info\ . | less
1760 Add new files and remove obsolete files in a work tree directory:
1762 .Dl $ got add sys/uvm/uvm_ubc.c
1763 .Dl $ got remove sys/uvm/uvm_vnode.c
1765 Create a new commit from local changes in a work tree directory
1766 with a pre-defined log message.
1768 .Dl $ got commit -m 'unify the buffer cache'
1770 Alternatively, create a new commit from local changes in a work tree
1771 directory with a log message that has been prepared in the file
1774 .Dl $ got commit -F /tmp/msg
1776 Update any work tree checked out from the
1777 .Dq unified-buffer-cache
1778 branch to the latest commit on this branch:
1782 Roll file content on the unified-buffer-cache branch back by one commit,
1783 and then fetch the rolled-back change into the work tree as a local change
1784 to be amended and perhaps committed again:
1786 .Dl $ got backout unified-buffer-cache
1787 .Dl $ got commit -m 'roll back previous'
1788 .Dl $ # now back out the previous backout :-)
1789 .Dl $ got backout unified-buffer-cache
1791 Fetch new changes on the remote repository's
1793 branch, making them visible on the local repository's
1800 In a repository created with a HTTP URL and
1801 .Cm git clone --bare
1804 command must be used instead:
1806 .Dl $ cd /var/git/src.git
1807 .Dl $ git fetch origin master:refs/remotes/origin/master
1811 branch to merge the new changes that are now visible on the
1816 .Dl $ got update -b origin/master
1817 .Dl $ got rebase master
1820 .Dq unified-buffer-cache
1821 branch on top of the new head commit of the
1825 .Dl $ got update -b master
1826 .Dl $ got rebase unified-buffer-cache
1828 Create a patch from all changes on the unified-buffer-cache branch.
1829 The patch can be mailed out for review and applied to
1833 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1835 Edit the entire commit history of the
1836 .Dq unified-buffer-cache
1839 .Dl $ got update -b unified-buffer-cache
1840 .Dl $ got update -c master
1843 Before working against existing branches in a repository cloned with
1844 .Cm git clone --bare
1849 must be configured to map all references in the remote repository
1852 namespace of the local repository.
1853 This can be achieved by setting Git's
1854 .Pa remote.origin.fetch
1855 configuration variable to the value
1856 .Dq +refs/heads/*:refs/remotes/origin/*
1861 .Dl $ cd /var/git/repo
1862 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1866 option must be disabled:
1868 .Dl $ cd /var/git/repo
1869 .Dl $ git config remote.origin.mirror false
1871 Alternatively, the following
1873 configuration item can be added manually to the Git repository's
1877 .Dl [remote \&"origin\&"]
1879 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
1882 This configuration leaves the local repository's
1884 namespace free for use by local branches checked out with
1886 and, if needed, created with
1889 .Dq refs/remotes/origin
1890 namespace can now be updated with incoming changes from the remote
1895 without extra command line arguments.
1896 Newly fetched changes can be examined with
1899 Display changes on the remote repository's version of the
1901 branch, as of the last time
1905 .Dl $ got log -c origin/master | less
1907 As shown here, most commands accept abbreviated reference names such as
1910 .Dq refs/remotes/origin/master .
1911 The latter is only needed in case of ambiguity.
1914 can be used to merge changes which are visible on the
1919 This will also merge local changes, if any, with the incoming changes:
1921 .Dl $ got update -b origin/master
1922 .Dl $ got rebase master
1924 In order to make changes committed to the
1925 .Dq unified-buffer-cache
1929 .Dq unified-buffer-cache
1930 branch can be rebased onto the
1934 .Dl $ got update -b master
1935 .Dl $ got rebase unified-buffer-cache
1938 .Dq unified-buffer-cache
1939 branch can now be made visible on the
1943 Because the rebase operation switched the work tree to the
1944 .Dq unified-buffer-cache
1945 branch, the work tree must be switched back to the
1949 .Dl $ got update -b master
1950 .Dl $ got integrate unified-buffer-cache
1954 branch, log messages for local changes can now be amended with
1956 by other developers and any other important new information:
1958 .Dl $ got update -c origin/master
1959 .Dl $ got histedit -m
1961 If the remote repository offers write access, local changes on the
1963 branch can be sent to the remote repository with
1967 can be run without further arguments.
1968 The arguments shown here match defaults, provided the work tree's
1969 current branch is the
1973 .Dl $ got send -b master origin
1975 If the remote repository requires the HTTPS protocol, the
1977 command must be used instead:
1979 .Dl $ cd /var/git/src.git
1980 .Dl $ git push origin master
1982 When making contributions to projects which use the
1984 workflow, SSH protocol repository access needs to be set up first.
1985 Once an account has been created on a Git hosting site it should
1986 be possible to upload a public SSH key for repository access
1991 workflow will usually involve two remote repositories.
1992 In the real-life example below, the
1994 repository was forked from the
1996 repository by using the Git hosting site's web interface.
1999 file in the local repository describes both remote repositories:
2000 .Bd -literal -offset indent
2001 # Jelmers's repository, which accepts pull requests
2003 server git@github.com
2005 repository "/jelmer/dulwich"
2009 # Stefan's fork, used as the default remote repository
2011 server git@github.com
2013 repository "/stspdotname/dulwich"
2018 With this configuration, Stefan can create commits on
2019 .Dq refs/heads/master
2020 and send them to the
2022 repository by running:
2024 .Dl $ got send -b master origin
2026 The changes can now be proposed to Jelmer by opening a pull request
2027 via the Git hosting site's web interface.
2028 If Jelmer requests further changes to be made, additional commits
2029 can be created on the
2031 branch and be added to the pull request by running
2035 If Jelmer prefers additional commits to be
2037 then the following commands can be used to achieve this:
2039 .Dl $ got update -b master
2040 .Dl $ got update -c origin/master
2041 .Dl $ got histedit -f
2042 .Dl $ got send -f -b master origin
2044 In addition to reviewing the pull request in the web user interface,
2045 Jelmer can fetch the pull request's branch into his local repository
2046 and create a local branch which contains the proposed changes:
2048 .Dl $ got fetch -R refs/pull/1046/head origin
2049 .Dl $ got branch -c refs/remotes/origin/pull/1046/head pr1046
2051 Once Jelmer has accepted the pull request, Stefan can fetch the
2052 merged changes, and possibly several other new changes, by running:
2054 .Dl $ got fetch upstream
2056 The merged changes will now be visible under the reference
2057 .Dq refs/remotes/upstream/master .
2060 branch can now be rebased on top of the latest changes
2063 .Dl $ got update -b upstream/master
2064 .Dl $ got rebase master
2066 As an alternative to
2068 branches can be merged with
2071 .Dl $ got update -b master
2072 .Dl $ got merge upstream/master
2074 The question of whether to rebase or merge branches is philosophical.
2075 When in doubt, refer to the software project's policies set by project
2078 As a final step, the forked repository's copy of the master branch needs
2079 to be kept in sync by sending the new changes there:
2081 .Dl $ got send -f -b master origin
2083 If multiple pull requests need to be managed in parallel, a separate branch
2084 must be created for each pull request with
2086 Each such branch can then be used as above, in place of
2087 .Dq refs/heads/master .
2088 Changes for any accepted pull requests will still appear under
2089 .Dq refs/remotes/upstream/master,
2090 regardless of which branch was used in the forked repository to
2091 create a pull request.
2095 .Xr git-repository 5 ,
2096 .Xr got-worktree 5 ,
2100 .An Anthony J. Bentley Aq Mt bentley@openbsd.org
2101 .An Christian Weisgerber Aq Mt naddy@openbsd.org
2102 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
2103 .An Josh Rickmar Aq Mt jrick@zettaport.com
2104 .An Joshua Stein Aq Mt jcs@openbsd.org
2105 .An Klemens Nanni Aq Mt kn@openbsd.org
2106 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2107 .An Neels Hofmeyr Aq Mt neels@hofmeyr.de
2108 .An Omar Polo Aq Mt op@openbsd.org
2109 .An Ori Bernstein Aq Mt ori@openbsd.org
2110 .An Sebastien Marie Aq Mt semarie@openbsd.org
2111 .An Stefan Sperling Aq Mt stsp@openbsd.org
2112 .An Steven McDonald Aq Mt steven@steven-mcdonald.id.au
2113 .An Theo Buehler Aq Mt tb@openbsd.org
2114 .An Thomas Adam Aq Mt thomas@xteddy.org
2115 .An Tracey Emery Aq Mt tracey@traceyemery.net
2116 .An Yang Zhong Aq Mt yzhong@freebsdfoundation.org
2123 were derived from code under copyright by:
2125 .An Caldera International
2126 .An Daniel Hartmeier
2131 .An Jean-Francois Brousseau
2137 .An Niklas Hallqvist
2142 .An Xavier Santolaria
2145 contains code contributed to the public domain by
2146 .An Austin Appleby .
2149 is a work-in-progress and some features remain to be implemented.
2151 At present, the user has to fall back on
2153 to perform some tasks.
2157 Reading from remote repositories over HTTP or HTTPS protocols requires
2162 Writing to remote repositories over HTTP or HTTPS protocols requires
2165 The creation of merge commits with more than two parent commits requires
2168 In situations where files or directories were moved around
2170 will not automatically merge changes to new locations and
2172 will usually produce better results.
