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.
905 .Op Fl r Ar repository-path
906 .Op Fl s Ar signer-id
909 Manage tags in a repository.
911 Tags are managed via references which live in the
916 command operates on references in this namespace only.
917 References in this namespace point at tag objects which contain a pointer
918 to another object, a tag message, as well as author and timestamp information.
920 Attempt to create a tag with the given
922 and make this tag point at the given
924 If no commit is specified, default to the latest commit on the work tree's
925 current branch if invoked in a work tree, and to a commit resolved via
926 the repository's HEAD reference otherwise.
933 Make the newly created tag reference point at the specified
937 argument is a commit ID SHA1 hash or an existing reference or tag name which
938 will be resolved to a commit ID.
939 An abbreviated hash argument will be expanded to a full SHA1 hash
940 automatically, provided the abbreviation is unique.
942 List all existing tags in the repository instead of creating a new tag.
945 argument is passed, show only the tag with the given
948 Use the specified tag message when creating the new tag.
953 opens a temporary file in an editor where a tag message can be written.
954 Quitting the editor without saving the file will abort the tag operation.
955 .It Fl r Ar repository-path
956 Use the repository at the specified path.
957 If not specified, assume the repository is located at or above the current
959 If this directory is a
961 work tree, use the repository path associated with this work tree.
962 .It Fl s Ar signer-id
963 While creating a new tag, sign this tag with the identity given in
966 For SSH-based signatures,
968 is the path to a file which may refer to either a private SSH key,
969 or a public SSH key with the private half available via
972 will sign the tag object by invoking
976 command, using the signature namespace
978 for compatibility with
981 Verify tag object signatures.
984 is specified, show and verify the tag object with the provided name.
985 Otherwise, list all tag objects and verify signatures where present.
988 verifies SSH-based signatures by invoking
991 .Fl Y Cm verify Fl f Ar allowed_signers .
996 otherwise verification is impossible.
999 During SSH signature creation and verification this option will be passed to
1001 Multiple -v options increase the verbosity.
1007 command will not delete tags or change existing tags.
1008 If a tag must be deleted, the
1010 command may be used to delete a tag's reference.
1011 This should only be done if the tag has not already been copied to
1018 Schedule unversioned files in a work tree for addition to the
1019 repository in the next commit.
1020 By default, files which match a
1022 ignore pattern will not be added.
1026 mentioned in the command line is not an unversioned file then
1029 To avoid unnecessary errors from paths picked up by file globbing patterns
1030 in the shell, paths in the argument list will be silently ignored if they
1033 at all, or if they are reported with one of the following status codes
1034 and do not have changes staged via
1036 .Bl -column YXZ description
1037 .It M Ta modified file
1038 .It A Ta file scheduled for addition in next commit
1039 .It C Ta modified or added file which contains merge conflicts
1040 .It m Ta modified file modes (executable bit only)
1048 Add files even if they match a
1052 Permit recursion into directories.
1053 If this option is not specified,
1055 will refuse to run if a specified
1063 .Op Fl s Ar status-codes
1067 Remove versioned files from a work tree and schedule them for deletion
1068 from the repository in the next commit.
1075 Perform the operation even if a file contains local modifications,
1076 and do not raise an error if a specified
1078 does not exist on disk.
1080 Keep affected files on disk.
1082 Permit recursion into directories.
1083 If this option is not specified,
1085 will refuse to run if a specified
1088 .It Fl s Ar status-codes
1089 Only delete files with a modification status matching one of the
1090 single-character status codes contained in the
1093 The following status codes may be specified:
1094 .Bl -column YXZ description
1095 .It M Ta modified file (this implies the
1098 .It ! Ta versioned file expected on disk but missing
1106 .Op Fl p Ar strip-count
1112 to files in a work tree.
1113 Files added or removed by a patch will be scheduled for addition or removal in
1116 The patch must be in the unified diff format as produced by
1123 diff when invoked with their
1128 argument is provided, read unified diff data from standard input instead.
1132 contains multiple patches, then attempt to apply each of them in sequence.
1134 Show the status of each affected file, using the following status codes:
1135 .Bl -column XYZ description
1136 .It M Ta file was modified
1137 .It G Ta file was merged using a merge-base found in the repository
1138 .It C Ta file was merged and conflicts occurred during merge
1139 .It D Ta file was deleted
1140 .It A Ta file was added
1141 .It # Ta failed to patch the file
1144 If a change does not match at its exact line number, attempt to
1145 apply it somewhere else in the file if a good spot can be found.
1146 Otherwise, the patch will fail to apply.
1150 will refuse to apply a patch if certain preconditions are not met.
1151 Files to be deleted must already be under version control, and must
1152 not have been scheduled for deletion already.
1153 Files to be added must not yet be under version control and must not
1154 already be present on disk.
1155 Files to be modified must already be under version control and may not
1156 contain conflict markers.
1158 If an error occurs, the
1160 operation will be aborted.
1161 Any changes made to the work tree up to this point will be left behind.
1162 Such changes can be viewed with
1164 and can be reverted with
1173 Attempt to locate files within the specified
1175 for use as a merge-base for 3-way merges.
1176 Ideally, the specified
1178 should contain versions of files which the changes contained in the
1181 Files will be located by path, relative to the repository root.
1184 option is used then leading path components will be stripped
1185 before paths are looked up in the repository.
1189 option is not used then
1191 will attempt to locate merge-bases via object IDs found in
1193 meta-data, such as produced by
1199 option is only recommended in the absence of such meta-data.
1201 In case no merge-base is available for a file, changes will be applied
1202 without doing a 3-way merge.
1203 Changes which do not apply cleanly may then be rejected entirely, rather
1204 than producing merge conflicts in the patched target file.
1206 Do not make any modifications to the work tree.
1207 This can be used to check whether a patch would apply without issues.
1210 contains diffs that affect the same file multiple times, the results
1211 displayed may be incorrect.
1212 .It Fl p Ar strip-count
1213 Specify the number of leading path components to strip from paths
1222 path prefixes generated by
1224 will be recognized and stripped automatically.
1226 Reverse the patch before applying it.
1232 .Op Fl F Ar response-script
1236 Revert any local changes in files at the specified paths in a work tree.
1237 File contents will be overwritten with those contained in the
1238 work tree's base commit.
1239 There is no way to bring discarded changes back after
1242 If a file was added with
1244 it will become an unversioned file again.
1245 If a file was deleted with
1247 it will be restored.
1253 .It Fl F Ar response-script
1261 responses line-by-line from the specified
1263 file instead of prompting interactively.
1265 Instead of reverting all changes in files, interactively select or reject
1266 changes to revert based on
1272 (quit reverting this file) responses.
1273 If a file is in modified status, individual patches derived from the
1274 modified file content can be reverted.
1275 Files in added or deleted status may only be reverted in their entirety.
1277 Permit recursion into directories.
1278 If this option is not specified,
1280 will refuse to run if a specified
1294 Create a new commit in the repository from changes in a work tree
1295 and use this commit as the new base commit for the work tree.
1298 is specified, commit all changes in the work tree.
1299 Otherwise, commit changes at or within the specified paths.
1301 If changes have been explicitly staged for commit with
1303 only commit staged changes and reject any specified paths which
1304 have not been staged.
1307 opens a temporary file in an editor where a log message can be written
1315 options are used together.
1316 Quitting the editor without saving the file will abort the commit operation.
1318 Show the status of each affected file, using the following status codes:
1319 .Bl -column YXZ description
1320 .It M Ta modified file
1321 .It D Ta file was deleted
1322 .It A Ta new file was added
1323 .It m Ta modified file modes (executable bit only)
1326 Files which are not part of the new commit will retain their previously
1327 recorded base commit.
1330 commands may refuse to run while the work tree contains files from
1331 multiple base commits.
1332 The base commit of such a work tree can be made consistent by running
1334 across the entire work tree.
1338 command requires the
1340 environment variable to be set,
1341 unless an author has been configured in
1347 configuration settings can be
1348 obtained from the repository's
1350 file or from Git's global
1359 Set author information in the newly created commit to
1361 This is useful when committing changes on behalf of someone else.
1364 argument must use the same format as the
1366 environment variable.
1368 In addition to storing author information, the newly created commit
1371 information which is obtained, as usual, from the
1373 environment variable, or
1375 or Git configuration settings.
1377 Allow committing files in conflicted status.
1379 Committing files with conflict markers should generally be avoided.
1380 Cases where conflict markers must be stored in the repository for
1381 some legitimate reason should be very rare.
1382 There are usually ways to avoid storing conflict markers verbatim by
1383 applying appropriate programming tricks.
1385 Use the prepared log message stored in the file found at
1387 when creating the new commit.
1389 opens a temporary file in an editor where the prepared log message can be
1390 reviewed and edited further if needed.
1391 Cannot be used together with the
1395 Use the specified log message when creating the new commit.
1396 Cannot be used together with the
1400 This option prevents
1402 from opening the commit message in an editor.
1403 It has no effect unless it is used together with the
1405 option and is intended for non-interactive use such as scripting.
1407 This option prevents
1409 from generating a diff of the to-be-committed changes in a temporary file
1410 which can be viewed while editing a commit message.
1412 Allow the addition of symbolic links which point outside of the path space
1413 that is under version control.
1416 will reject such symbolic links due to safety concerns.
1419 may decide to represent such a symbolic link as a regular file which contains
1420 the link's target path, rather than creating an actual symbolic link which
1421 points outside of the work tree.
1422 Use of this option is discouraged because external mechanisms such as
1424 are better suited for managing symbolic links to paths not under
1429 will refuse to run if certain preconditions are not met.
1430 If the work tree's current branch is not in the
1432 reference namespace, new commits may not be created on this branch.
1433 Local changes may only be committed if they are based on file content
1434 found in the most recent commit on the work tree's branch.
1435 If a path is found to be out of date,
1437 must be used first in order to merge local changes with changes made
1446 Merge changes from a single
1451 should be on a different branch than the work tree's base commit.
1452 The expected argument is a reference or a commit ID SHA1 hash.
1453 An abbreviated hash argument will be expanded to a full SHA1 hash
1454 automatically, provided the abbreviation is unique.
1456 Show the status of each affected file, using the following status codes:
1457 .Bl -column YXZ description
1458 .It G Ta file was merged
1459 .It C Ta file was merged and conflicts occurred during merge
1460 .It ! Ta changes destined for a missing file were not merged
1461 .It D Ta file was deleted
1462 .It d Ta file's deletion was prevented by local modifications
1463 .It A Ta new file was added
1464 .It \(a~ Ta changes destined for a non-regular file were not merged
1465 .It ? Ta changes destined for an unversioned file were not merged
1468 The merged changes will appear as local changes in the work tree, which
1471 amended manually or with further
1477 If invoked in a work tree where no
1482 operation is taking place,
1484 creates a record of commits which have been merged into the work tree.
1485 When a file changed by
1489 the log messages of relevant merged commits will then appear in the editor,
1490 where the messages should be further adjusted to convey the reasons for
1491 cherrypicking the changes.
1492 Upon exiting the editor, if the time stamp of the log message file
1493 is unchanged or the log message is empty,
1495 will fail with an unmodified or empty log message error.
1497 If all the changes in all files touched by a given commit are discarded,
1500 this commit's log message record will also disappear.
1503 will refuse to run if certain preconditions are not met.
1504 If the work tree contains multiple base commits, it must first be updated
1505 to a single base commit with
1507 If any relevant files already contain merge conflicts, these
1508 conflicts must be resolved first.
1516 Display a list of commit log messages recorded by cherrypick operations,
1517 represented by references in the
1518 .Dq refs/got/worktree
1519 reference namespace.
1522 is specified, only show the log message of the specified commit.
1524 If invoked in a work tree, only log messages recorded by cherrypick operations
1525 in the current work tree will be displayed.
1526 Otherwise, all commit log messages will be displayed irrespective of the
1527 work tree in which they were created.
1528 This option cannot be used with
1531 Delete log messages created by previous cherrypick operations, represented by
1533 .Dq refs/got/worktree
1534 reference namespace.
1537 is specified, only delete the log message of the specified commit.
1539 If invoked in a work tree, only log messages recorded by cherrypick operations
1540 in the current work tree will be deleted.
1541 Otherwise, all commit log messages will be deleted irrespective of the
1542 work tree in which they were created.
1543 This option cannot be used with
1554 Reverse-merge changes from a single
1559 should be on the same branch as the work tree's base commit.
1560 The expected argument is a reference or a commit ID SHA1 hash.
1561 An abbreviated hash argument will be expanded to a full SHA1 hash
1562 automatically, provided the abbreviation is unique.
1564 Show the status of each affected file, using the following status codes:
1565 .Bl -column YXZ description
1566 .It G Ta file was merged
1567 .It C Ta file was merged and conflicts occurred during merge
1568 .It ! Ta changes destined for a missing file were not merged
1569 .It D Ta file was deleted
1570 .It d Ta file's deletion was prevented by local modifications
1571 .It A Ta new file was added
1572 .It \(a~ Ta changes destined for a non-regular file were not merged
1573 .It ? Ta changes destined for an unversioned file were not merged
1576 The reverse-merged changes will appear as local changes in the work tree,
1577 which may be viewed with
1579 amended manually or with further
1585 If invoked in a work tree where no
1590 operation is taking place,
1592 creates a record of commits which have been reverse-merged into the work tree.
1593 When a file changed by
1597 the log messages of relevant reverse-merged commits will then appear in
1598 the editor, where the messages should be further adjusted to convey the
1599 reasons for backing out the changes.
1600 Upon exiting the editor, if the time stamp of the log message file
1601 is unchanged or the log message is empty,
1603 will fail with an unmodified or empty log message error.
1605 If all the changes in all files touched by a given commit are discarded,
1608 this commit's log message record will also disappear.
1611 will refuse to run if certain preconditions are not met.
1612 If the work tree contains multiple base commits, it must first be updated
1613 to a single base commit with
1615 If any relevant files already contain merge conflicts, these
1616 conflicts must be resolved first.
1624 Display a list of commit log messages recorded by backout operations,
1625 represented by references in the
1626 .Dq refs/got/worktree
1627 reference namespace.
1630 is specified, only show the log message of the specified commit.
1632 If invoked in a work tree, only log messages recorded by backout operations
1633 in the current work tree will be displayed.
1634 Otherwise, all commit log messages will be displayed irrespective of the
1635 work tree in which they were created.
1636 This option cannot be used with
1639 Delete log messages created by previous backout operations, represented by
1641 .Dq refs/got/worktree
1642 reference namespace.
1645 is specified, only delete the log message of the specified commit.
1647 If invoked in a work tree, only log messages recorded by backout operations
1648 in the current work tree will be deleted.
1649 Otherwise, all commit log messages will be deleted irrespective of the
1650 work tree in which they were created.
1651 This option cannot be used with
1658 .Op Fl r Ar repository-path
1661 Parse and print contents of objects to standard output in a line-based
1663 Content of commit, tree, and tag objects is printed in a way similar
1664 to the actual content stored in such objects.
1665 Blob object contents are printed as they would appear in files on disk.
1667 Attempt to interpret each argument as a reference, a tag name, or
1668 an object ID SHA1 hash.
1669 References will be resolved to an object ID.
1670 Tag names will resolved to a tag object.
1671 An abbreviated hash argument will be expanded to a full SHA1 hash
1672 automatically, provided the abbreviation is unique.
1674 If none of the above interpretations produce a valid result, or if the
1676 option is used, attempt to interpret the argument as a path which will
1677 be resolved to the ID of an object found at this path in the repository.
1684 Look up paths in the specified
1686 If this option is not used, paths are looked up in the commit resolved
1687 via the repository's HEAD reference.
1688 The expected argument is a commit ID SHA1 hash or an existing reference
1689 or tag name which will be resolved to a commit ID.
1690 An abbreviated hash argument will be expanded to a full SHA1 hash
1691 automatically, provided the abbreviation is unique.
1693 Interpret all arguments as paths only.
1694 This option can be used to resolve ambiguity in cases where paths
1695 look like tag names, reference names, or object IDs.
1696 .It Fl r Ar repository-path
1697 Use the repository at the specified path.
1698 If not specified, assume the repository is located at or above the current
1700 If this directory is a
1702 work tree, use the repository path associated with this work tree.
1704 .It Cm info Op Ar path ...
1705 Display meta-data stored in a work tree.
1710 The work tree to use is resolved implicitly by walking upwards from the
1711 current working directory.
1715 arguments are specified, show additional per-file information for tracked
1716 files located at or within these paths.
1719 argument corresponds to the work tree's root directory, display information
1720 for all tracked files.
1723 .Bl -tag -width GOT_IGNORE_GITCONFIG
1725 The author's name and email address, such as
1726 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1737 may fail to parse commits without an email address in author data,
1741 environment variables with a missing email address.
1743 .Ev GOT_AUTHOR will be overridden by configuration settings in
1749 configuration settings in the repository's
1756 configuration settings contained in Git's global
1758 configuration file will only be used if neither
1762 environment variable provide author information.
1763 .It Ev GOT_IGNORE_GITCONFIG
1764 If this variable is set then any remote repository definitions or author
1765 information found in Git configuration files will be ignored.
1766 .It Ev GOT_LOG_DEFAULT_LIMIT
1767 The default limit on the number of commits traversed by
1769 If set to zero, the limit is unbounded.
1770 This variable will be silently ignored if it is set to a non-numeric value.
1771 .It Ev VISUAL , EDITOR
1772 The editor spawned by
1780 text editor will be spawned.
1783 .Bl -tag -width packed-refs -compact
1785 Repository-wide configuration settings for
1789 configuration file located in the root directory of a Git repository
1790 supersedes any relevant settings in Git's
1794 .It Pa .cvg/got.conf
1795 Worktree-specific configuration settings for
1799 configuration file in the
1801 meta-data directory of a work tree supersedes any relevant settings in
1804 configuration file and Git's
1811 Enable tab-completion of
1816 .Dl $ set -A complete_got_1 -- $(got -h 2>&1 | sed -n s/commands://p)
1818 Clone an existing Git repository for use with
1822 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1824 Unfortunately, many of the popular Git hosting sites do not offer anonymous
1826 Such sites will require an account to be created, and a public SSH key to be
1827 uploaded to this account, before repository access via ssh:// URLs will work.
1829 Use of HTTP URLs currently requires
1833 .Dl $ git clone --bare https://github.com/openbsd/src.git
1835 Alternatively, for quick and dirty local testing of
1837 a new Git repository could be created and populated with files,
1838 e.g. from a temporary CVS checkout located at
1841 .Dl $ gotadmin init /var/git/src.git
1842 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1844 Check out a work tree from the Git repository to /usr/src:
1846 .Dl $ got checkout /var/git/src.git /usr/src
1848 View local changes in a work tree directory:
1850 .Dl $ got diff | less
1852 In a work tree, display files in a potentially problematic state:
1854 .Dl $ got status -s 'C!~?'
1856 Interactively revert selected local changes in a work tree directory:
1858 .Dl $ got revert -p -R\ .
1860 In a work tree or a git repository directory, list all branch references:
1864 As above, but list the most recently modified branches only:
1866 .Dl $ got branch -lt | head
1868 In a work tree or a git repository directory, create a new branch called
1869 .Dq unified-buffer-cache
1870 which is forked off the
1874 .Dl $ got branch -c master unified-buffer-cache
1876 Switch an existing work tree to the branch
1877 .Dq unified-buffer-cache .
1878 Local changes in the work tree will be preserved and merged if necessary:
1880 .Dl $ got update -b unified-buffer-cache
1882 Create a new commit from local changes in a work tree directory.
1883 This new commit will become the head commit of the work tree's current branch:
1887 In a work tree or a git repository directory, view changes committed in
1888 the 3 most recent commits to the work tree's branch, or the branch resolved
1889 via the repository's HEAD reference, respectively:
1891 .Dl $ got log -p -l 3
1893 As above, but display changes in the order in which
1895 could apply them in sequence:
1897 .Dl $ got log -p -l 3 -R
1899 In a work tree or a git repository directory, log the history of a subdirectory:
1901 .Dl $ got log sys/uvm
1903 While operating inside a work tree, paths are specified relative to the current
1904 working directory, so this command will log the subdirectory
1907 .Dl $ cd sys/uvm && got log\ .
1909 And this command has the same effect:
1911 .Dl $ cd sys/dev/usb && got log ../../uvm
1913 And this command displays work tree meta-data about all tracked files:
1916 .Dl $ got info\ . | less
1918 Add new files and remove obsolete files in a work tree directory:
1920 .Dl $ got add sys/uvm/uvm_ubc.c
1921 .Dl $ got remove sys/uvm/uvm_vnode.c
1923 Create a new commit from local changes in a work tree directory
1924 with a pre-defined log message.
1926 .Dl $ got commit -m 'unify the buffer cache'
1928 Alternatively, create a new commit from local changes in a work tree
1929 directory with a log message that has been prepared in the file
1932 .Dl $ got commit -F /tmp/msg
1934 Update any work tree checked out from the
1935 .Dq unified-buffer-cache
1936 branch to the latest commit on this branch:
1940 Roll file content on the unified-buffer-cache branch back by one commit,
1941 and then fetch the rolled-back change into the work tree as a local change
1942 to be amended and perhaps committed again:
1944 .Dl $ got backout unified-buffer-cache
1945 .Dl $ got commit -m 'roll back previous'
1946 .Dl $ # now back out the previous backout :-)
1947 .Dl $ got backout unified-buffer-cache
1949 Fetch new changes on the remote repository's
1951 branch, making them visible on the local repository's
1958 In a repository created with a HTTP URL and
1959 .Cm git clone --bare
1962 command must be used instead:
1964 .Dl $ cd /var/git/src.git
1965 .Dl $ git fetch origin master:refs/remotes/origin/master
1969 branch to merge the new changes that are now visible on the
1974 .Dl $ got update -b origin/master
1975 .Dl $ got rebase master
1978 .Dq unified-buffer-cache
1979 branch on top of the new head commit of the
1983 .Dl $ got update -b master
1984 .Dl $ got rebase unified-buffer-cache
1986 Create a patch from all changes on the unified-buffer-cache branch.
1987 The patch can be mailed out for review and applied to
1991 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1993 Edit the entire commit history of the
1994 .Dq unified-buffer-cache
1997 .Dl $ got update -b unified-buffer-cache
1998 .Dl $ got update -c master
2001 Before working against existing branches in a repository cloned with
2002 .Cm git clone --bare
2007 must be configured to map all references in the remote repository
2010 namespace of the local repository.
2011 This can be achieved by setting Git's
2012 .Pa remote.origin.fetch
2013 configuration variable to the value
2014 .Dq +refs/heads/*:refs/remotes/origin/*
2019 .Dl $ cd /var/git/repo
2020 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
2024 option must be disabled:
2026 .Dl $ cd /var/git/repo
2027 .Dl $ git config remote.origin.mirror false
2029 Alternatively, the following
2031 configuration item can be added manually to the Git repository's
2035 .Dl [remote \&"origin\&"]
2037 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2040 This configuration leaves the local repository's
2042 namespace free for use by local branches checked out with
2044 and, if needed, created with
2047 .Dq refs/remotes/origin
2048 namespace can now be updated with incoming changes from the remote
2053 without extra command line arguments.
2054 Newly fetched changes can be examined with
2057 Display changes on the remote repository's version of the
2059 branch, as of the last time
2063 .Dl $ got log -c origin/master | less
2065 As shown here, most commands accept abbreviated reference names such as
2068 .Dq refs/remotes/origin/master .
2069 The latter is only needed in case of ambiguity.
2072 can be used to merge changes which are visible on the
2077 This will also merge local changes, if any, with the incoming changes:
2079 .Dl $ got update -b origin/master
2080 .Dl $ got rebase master
2082 In order to make changes committed to the
2083 .Dq unified-buffer-cache
2087 .Dq unified-buffer-cache
2088 branch can be rebased onto the
2092 .Dl $ got update -b master
2093 .Dl $ got rebase unified-buffer-cache
2096 .Dq unified-buffer-cache
2097 branch can now be made visible on the
2101 Because the rebase operation switched the work tree to the
2102 .Dq unified-buffer-cache
2103 branch, the work tree must be switched back to the
2107 .Dl $ got update -b master
2108 .Dl $ got integrate unified-buffer-cache
2112 branch, log messages for local changes can now be amended with
2114 by other developers and any other important new information:
2116 .Dl $ got update -c origin/master
2117 .Dl $ got histedit -m
2119 If the remote repository offers write access, local changes on the
2121 branch can be sent to the remote repository with
2125 can be run without further arguments.
2126 The arguments shown here match defaults, provided the work tree's
2127 current branch is the
2131 .Dl $ got send -b master origin
2133 If the remote repository requires the HTTPS protocol, the
2135 command must be used instead:
2137 .Dl $ cd /var/git/src.git
2138 .Dl $ git push origin master
2140 When making contributions to projects which use the
2142 workflow, SSH protocol repository access needs to be set up first.
2143 Once an account has been created on a Git hosting site it should
2144 be possible to upload a public SSH key for repository access
2149 workflow will usually involve two remote repositories.
2150 In the real-life example below, the
2152 repository was forked from the
2154 repository by using the Git hosting site's web interface.
2157 file in the local repository describes both remote repositories:
2158 .Bd -literal -offset indent
2159 # Jelmers's repository, which accepts pull requests
2161 server git@github.com
2163 repository "/jelmer/dulwich"
2167 # Stefan's fork, used as the default remote repository
2169 server git@github.com
2171 repository "/stspdotname/dulwich"
2176 With this configuration, Stefan can create commits on
2177 .Dq refs/heads/master
2178 and send them to the
2180 repository by running:
2182 .Dl $ got send -b master origin
2184 The changes can now be proposed to Jelmer by opening a pull request
2185 via the Git hosting site's web interface.
2186 If Jelmer requests further changes to be made, additional commits
2187 can be created on the
2189 branch and be added to the pull request by running
2193 If Jelmer prefers additional commits to be
2195 then the following commands can be used to achieve this:
2197 .Dl $ got update -b master
2198 .Dl $ got update -c origin/master
2199 .Dl $ got histedit -f
2200 .Dl $ got send -f -b master origin
2202 In addition to reviewing the pull request in the web user interface,
2203 Jelmer can fetch the pull request's branch into his local repository
2204 and create a local branch which contains the proposed changes:
2206 .Dl $ got fetch -R refs/pull/1046/head origin
2207 .Dl $ got branch -c refs/remotes/origin/pull/1046/head pr1046
2209 Once Jelmer has accepted the pull request, Stefan can fetch the
2210 merged changes, and possibly several other new changes, by running:
2212 .Dl $ got fetch upstream
2214 The merged changes will now be visible under the reference
2215 .Dq refs/remotes/upstream/master .
2218 branch can now be rebased on top of the latest changes
2221 .Dl $ got update -b upstream/master
2222 .Dl $ got rebase master
2224 As an alternative to
2226 branches can be merged with
2229 .Dl $ got update -b master
2230 .Dl $ got merge upstream/master
2232 The question of whether to rebase or merge branches is philosophical.
2233 When in doubt, refer to the software project's policies set by project
2236 As a final step, the forked repository's copy of the master branch needs
2237 to be kept in sync by sending the new changes there:
2239 .Dl $ got send -f -b master origin
2241 If multiple pull requests need to be managed in parallel, a separate branch
2242 must be created for each pull request with
2244 Each such branch can then be used as above, in place of
2245 .Dq refs/heads/master .
2246 Changes for any accepted pull requests will still appear under
2247 .Dq refs/remotes/upstream/master,
2248 regardless of which branch was used in the forked repository to
2249 create a pull request.
2253 .Xr git-repository 5 ,
2254 .Xr got-worktree 5 ,
2258 .An Anthony J. Bentley Aq Mt bentley@openbsd.org
2259 .An Christian Weisgerber Aq Mt naddy@openbsd.org
2260 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
2261 .An Josh Rickmar Aq Mt jrick@zettaport.com
2262 .An Joshua Stein Aq Mt jcs@openbsd.org
2263 .An Klemens Nanni Aq Mt kn@openbsd.org
2264 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2265 .An Neels Hofmeyr Aq Mt neels@hofmeyr.de
2266 .An Omar Polo Aq Mt op@openbsd.org
2267 .An Ori Bernstein Aq Mt ori@openbsd.org
2268 .An Sebastien Marie Aq Mt semarie@openbsd.org
2269 .An Stefan Sperling Aq Mt stsp@openbsd.org
2270 .An Steven McDonald Aq Mt steven@steven-mcdonald.id.au
2271 .An Theo Buehler Aq Mt tb@openbsd.org
2272 .An Thomas Adam Aq Mt thomas@xteddy.org
2273 .An Tracey Emery Aq Mt tracey@traceyemery.net
2274 .An Yang Zhong Aq Mt yzhong@freebsdfoundation.org
2281 were derived from code under copyright by:
2283 .An Caldera International
2284 .An Daniel Hartmeier
2289 .An Jean-Francois Brousseau
2295 .An Niklas Hallqvist
2300 .An Xavier Santolaria
2303 contains code contributed to the public domain by
2304 .An Austin Appleby .
2307 is a work-in-progress and some features remain to be implemented.
2309 At present, the user has to fall back on
2311 to perform some tasks.
2315 Reading from remote repositories over HTTP or HTTPS protocols requires
2320 Writing to remote repositories over HTTP or HTTPS protocols requires
2323 The creation of merge commits with more than two parent commits requires
2326 In situations where files or directories were moved around
2328 will not automatically merge changes to new locations and
2330 will usually produce better results.
