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
1659 .Op Fl r Ar repository-path
1662 Parse and print contents of objects to standard output in a line-based
1664 Content of commit, tree, and tag objects is printed in a way similar
1665 to the actual content stored in such objects.
1666 Blob object contents are printed as they would appear in files on disk.
1668 Attempt to interpret each argument as a reference, a tag name, or
1669 an object ID SHA1 hash.
1670 References will be resolved to an object ID.
1671 Tag names will resolved to a tag object.
1672 An abbreviated hash argument will be expanded to a full SHA1 hash
1673 automatically, provided the abbreviation is unique.
1675 If none of the above interpretations produce a valid result, or if the
1677 option is used, attempt to interpret the argument as a path which will
1678 be resolved to the ID of an object found at this path in the repository.
1685 Look up paths in the specified
1687 If this option is not used, paths are looked up in the commit resolved
1688 via the repository's HEAD reference.
1689 The expected argument is a commit ID SHA1 hash or an existing reference
1690 or tag name which will be resolved to a commit ID.
1691 An abbreviated hash argument will be expanded to a full SHA1 hash
1692 automatically, provided the abbreviation is unique.
1694 Interpret all arguments as paths only.
1695 This option can be used to resolve ambiguity in cases where paths
1696 look like tag names, reference names, or object IDs.
1697 .It Fl r Ar repository-path
1698 Use the repository at the specified path.
1699 If not specified, assume the repository is located at or above the current
1701 If this directory is a
1703 work tree, use the repository path associated with this work tree.
1705 .It Cm info Op Ar path ...
1706 Display meta-data stored in a work tree.
1711 The work tree to use is resolved implicitly by walking upwards from the
1712 current working directory.
1716 arguments are specified, show additional per-file information for tracked
1717 files located at or within these paths.
1720 argument corresponds to the work tree's root directory, display information
1721 for all tracked files.
1724 .Bl -tag -width GOT_IGNORE_GITCONFIG
1726 The author's name and email address, such as
1727 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1738 may fail to parse commits without an email address in author data,
1742 environment variables with a missing email address.
1744 .Ev GOT_AUTHOR will be overridden by configuration settings in
1750 configuration settings in the repository's
1757 configuration settings contained in Git's global
1759 configuration file will only be used if neither
1763 environment variable provide author information.
1764 .It Ev GOT_IGNORE_GITCONFIG
1765 If this variable is set then any remote repository definitions or author
1766 information found in Git configuration files will be ignored.
1767 .It Ev GOT_LOG_DEFAULT_LIMIT
1768 The default limit on the number of commits traversed by
1770 If set to zero, the limit is unbounded.
1771 This variable will be silently ignored if it is set to a non-numeric value.
1772 .It Ev VISUAL , EDITOR
1773 The editor spawned by
1781 text editor will be spawned.
1784 .Bl -tag -width packed-refs -compact
1786 Repository-wide configuration settings for
1790 configuration file located in the root directory of a Git repository
1791 supersedes any relevant settings in Git's
1795 .It Pa .cvg/got.conf
1796 Worktree-specific configuration settings for
1800 configuration file in the
1802 meta-data directory of a work tree supersedes any relevant settings in
1805 configuration file and Git's
1812 Enable tab-completion of
1817 .Dl $ set -A complete_got_1 -- $(got -h 2>&1 | sed -n s/commands://p)
1819 Clone an existing Git repository for use with
1823 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1825 Unfortunately, many of the popular Git hosting sites do not offer anonymous
1827 Such sites will require an account to be created, and a public SSH key to be
1828 uploaded to this account, before repository access via ssh:// URLs will work.
1830 Use of HTTP URLs currently requires
1834 .Dl $ git clone --bare https://github.com/openbsd/src.git
1836 Alternatively, for quick and dirty local testing of
1838 a new Git repository could be created and populated with files,
1839 e.g. from a temporary CVS checkout located at
1842 .Dl $ gotadmin init /var/git/src.git
1843 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1845 Check out a work tree from the Git repository to /usr/src:
1847 .Dl $ got checkout /var/git/src.git /usr/src
1849 View local changes in a work tree directory:
1851 .Dl $ got diff | less
1853 In a work tree, display files in a potentially problematic state:
1855 .Dl $ got status -s 'C!~?'
1857 Interactively revert selected local changes in a work tree directory:
1859 .Dl $ got revert -p -R\ .
1861 In a work tree or a git repository directory, list all branch references:
1865 As above, but list the most recently modified branches only:
1867 .Dl $ got branch -lt | head
1869 In a work tree or a git repository directory, create a new branch called
1870 .Dq unified-buffer-cache
1871 which is forked off the
1875 .Dl $ got branch -c master unified-buffer-cache
1877 Switch an existing work tree to the branch
1878 .Dq unified-buffer-cache .
1879 Local changes in the work tree will be preserved and merged if necessary:
1881 .Dl $ got update -b unified-buffer-cache
1883 Create a new commit from local changes in a work tree directory.
1884 This new commit will become the head commit of the work tree's current branch:
1888 In a work tree or a git repository directory, view changes committed in
1889 the 3 most recent commits to the work tree's branch, or the branch resolved
1890 via the repository's HEAD reference, respectively:
1892 .Dl $ got log -p -l 3
1894 As above, but display changes in the order in which
1896 could apply them in sequence:
1898 .Dl $ got log -p -l 3 -R
1900 In a work tree or a git repository directory, log the history of a subdirectory:
1902 .Dl $ got log sys/uvm
1904 While operating inside a work tree, paths are specified relative to the current
1905 working directory, so this command will log the subdirectory
1908 .Dl $ cd sys/uvm && got log\ .
1910 And this command has the same effect:
1912 .Dl $ cd sys/dev/usb && got log ../../uvm
1914 And this command displays work tree meta-data about all tracked files:
1917 .Dl $ got info\ . | less
1919 Add new files and remove obsolete files in a work tree directory:
1921 .Dl $ got add sys/uvm/uvm_ubc.c
1922 .Dl $ got remove sys/uvm/uvm_vnode.c
1924 Create a new commit from local changes in a work tree directory
1925 with a pre-defined log message.
1927 .Dl $ got commit -m 'unify the buffer cache'
1929 Alternatively, create a new commit from local changes in a work tree
1930 directory with a log message that has been prepared in the file
1933 .Dl $ got commit -F /tmp/msg
1935 Update any work tree checked out from the
1936 .Dq unified-buffer-cache
1937 branch to the latest commit on this branch:
1941 Roll file content on the unified-buffer-cache branch back by one commit,
1942 and then fetch the rolled-back change into the work tree as a local change
1943 to be amended and perhaps committed again:
1945 .Dl $ got backout unified-buffer-cache
1946 .Dl $ got commit -m 'roll back previous'
1947 .Dl $ # now back out the previous backout :-)
1948 .Dl $ got backout unified-buffer-cache
1950 Fetch new changes on the remote repository's
1952 branch, making them visible on the local repository's
1959 In a repository created with a HTTP URL and
1960 .Cm git clone --bare
1963 command must be used instead:
1965 .Dl $ cd /var/git/src.git
1966 .Dl $ git fetch origin master:refs/remotes/origin/master
1970 branch to merge the new changes that are now visible on the
1975 .Dl $ got update -b origin/master
1976 .Dl $ got rebase master
1979 .Dq unified-buffer-cache
1980 branch on top of the new head commit of the
1984 .Dl $ got update -b master
1985 .Dl $ got rebase unified-buffer-cache
1987 Create a patch from all changes on the unified-buffer-cache branch.
1988 The patch can be mailed out for review and applied to
1992 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1994 Edit the entire commit history of the
1995 .Dq unified-buffer-cache
1998 .Dl $ got update -b unified-buffer-cache
1999 .Dl $ got update -c master
2002 Before working against existing branches in a repository cloned with
2003 .Cm git clone --bare
2008 must be configured to map all references in the remote repository
2011 namespace of the local repository.
2012 This can be achieved by setting Git's
2013 .Pa remote.origin.fetch
2014 configuration variable to the value
2015 .Dq +refs/heads/*:refs/remotes/origin/*
2020 .Dl $ cd /var/git/repo
2021 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
2025 option must be disabled:
2027 .Dl $ cd /var/git/repo
2028 .Dl $ git config remote.origin.mirror false
2030 Alternatively, the following
2032 configuration item can be added manually to the Git repository's
2036 .Dl [remote \&"origin\&"]
2038 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2041 This configuration leaves the local repository's
2043 namespace free for use by local branches checked out with
2045 and, if needed, created with
2048 .Dq refs/remotes/origin
2049 namespace can now be updated with incoming changes from the remote
2054 without extra command line arguments.
2055 Newly fetched changes can be examined with
2058 Display changes on the remote repository's version of the
2060 branch, as of the last time
2064 .Dl $ got log -c origin/master | less
2066 As shown here, most commands accept abbreviated reference names such as
2069 .Dq refs/remotes/origin/master .
2070 The latter is only needed in case of ambiguity.
2073 can be used to merge changes which are visible on the
2078 This will also merge local changes, if any, with the incoming changes:
2080 .Dl $ got update -b origin/master
2081 .Dl $ got rebase master
2083 In order to make changes committed to the
2084 .Dq unified-buffer-cache
2088 .Dq unified-buffer-cache
2089 branch can be rebased onto the
2093 .Dl $ got update -b master
2094 .Dl $ got rebase unified-buffer-cache
2097 .Dq unified-buffer-cache
2098 branch can now be made visible on the
2102 Because the rebase operation switched the work tree to the
2103 .Dq unified-buffer-cache
2104 branch, the work tree must be switched back to the
2108 .Dl $ got update -b master
2109 .Dl $ got integrate unified-buffer-cache
2113 branch, log messages for local changes can now be amended with
2115 by other developers and any other important new information:
2117 .Dl $ got update -c origin/master
2118 .Dl $ got histedit -m
2120 If the remote repository offers write access, local changes on the
2122 branch can be sent to the remote repository with
2126 can be run without further arguments.
2127 The arguments shown here match defaults, provided the work tree's
2128 current branch is the
2132 .Dl $ got send -b master origin
2134 If the remote repository requires the HTTPS protocol, the
2136 command must be used instead:
2138 .Dl $ cd /var/git/src.git
2139 .Dl $ git push origin master
2141 When making contributions to projects which use the
2143 workflow, SSH protocol repository access needs to be set up first.
2144 Once an account has been created on a Git hosting site it should
2145 be possible to upload a public SSH key for repository access
2150 workflow will usually involve two remote repositories.
2151 In the real-life example below, the
2153 repository was forked from the
2155 repository by using the Git hosting site's web interface.
2158 file in the local repository describes both remote repositories:
2159 .Bd -literal -offset indent
2160 # Jelmers's repository, which accepts pull requests
2162 server git@github.com
2164 repository "/jelmer/dulwich"
2168 # Stefan's fork, used as the default remote repository
2170 server git@github.com
2172 repository "/stspdotname/dulwich"
2177 With this configuration, Stefan can create commits on
2178 .Dq refs/heads/master
2179 and send them to the
2181 repository by running:
2183 .Dl $ got send -b master origin
2185 The changes can now be proposed to Jelmer by opening a pull request
2186 via the Git hosting site's web interface.
2187 If Jelmer requests further changes to be made, additional commits
2188 can be created on the
2190 branch and be added to the pull request by running
2194 If Jelmer prefers additional commits to be
2196 then the following commands can be used to achieve this:
2198 .Dl $ got update -b master
2199 .Dl $ got update -c origin/master
2200 .Dl $ got histedit -f
2201 .Dl $ got send -f -b master origin
2203 In addition to reviewing the pull request in the web user interface,
2204 Jelmer can fetch the pull request's branch into his local repository
2205 and create a local branch which contains the proposed changes:
2207 .Dl $ got fetch -R refs/pull/1046/head origin
2208 .Dl $ got branch -c refs/remotes/origin/pull/1046/head pr1046
2210 Once Jelmer has accepted the pull request, Stefan can fetch the
2211 merged changes, and possibly several other new changes, by running:
2213 .Dl $ got fetch upstream
2215 The merged changes will now be visible under the reference
2216 .Dq refs/remotes/upstream/master .
2219 branch can now be rebased on top of the latest changes
2222 .Dl $ got update -b upstream/master
2223 .Dl $ got rebase master
2225 As an alternative to
2227 branches can be merged with
2230 .Dl $ got update -b master
2231 .Dl $ got merge upstream/master
2233 The question of whether to rebase or merge branches is philosophical.
2234 When in doubt, refer to the software project's policies set by project
2237 As a final step, the forked repository's copy of the master branch needs
2238 to be kept in sync by sending the new changes there:
2240 .Dl $ got send -f -b master origin
2242 If multiple pull requests need to be managed in parallel, a separate branch
2243 must be created for each pull request with
2245 Each such branch can then be used as above, in place of
2246 .Dq refs/heads/master .
2247 Changes for any accepted pull requests will still appear under
2248 .Dq refs/remotes/upstream/master,
2249 regardless of which branch was used in the forked repository to
2250 create a pull request.
2254 .Xr git-repository 5 ,
2255 .Xr got-worktree 5 ,
2259 .An Anthony J. Bentley Aq Mt bentley@openbsd.org
2260 .An Christian Weisgerber Aq Mt naddy@openbsd.org
2261 .An Hiltjo Posthuma Aq Mt hiltjo@codemadness.org
2262 .An Josh Rickmar Aq Mt jrick@zettaport.com
2263 .An Joshua Stein Aq Mt jcs@openbsd.org
2264 .An Klemens Nanni Aq Mt kn@openbsd.org
2265 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2266 .An Neels Hofmeyr Aq Mt neels@hofmeyr.de
2267 .An Omar Polo Aq Mt op@openbsd.org
2268 .An Ori Bernstein Aq Mt ori@openbsd.org
2269 .An Sebastien Marie Aq Mt semarie@openbsd.org
2270 .An Stefan Sperling Aq Mt stsp@openbsd.org
2271 .An Steven McDonald Aq Mt steven@steven-mcdonald.id.au
2272 .An Theo Buehler Aq Mt tb@openbsd.org
2273 .An Thomas Adam Aq Mt thomas@xteddy.org
2274 .An Tracey Emery Aq Mt tracey@traceyemery.net
2275 .An Yang Zhong Aq Mt yzhong@freebsdfoundation.org
2282 were derived from code under copyright by:
2284 .An Caldera International
2285 .An Daniel Hartmeier
2290 .An Jean-Francois Brousseau
2296 .An Niklas Hallqvist
2301 .An Xavier Santolaria
2304 contains code contributed to the public domain by
2305 .An Austin Appleby .
2308 is a work-in-progress and some features remain to be implemented.
2310 At present, the user has to fall back on
2312 to perform some tasks.
2316 Reading from remote repositories over HTTP or HTTPS protocols requires
2321 Writing to remote repositories over HTTP or HTTPS protocols requires
2324 The creation of merge commits with more than two parent commits requires
2327 In situations where files or directories were moved around
2329 will not automatically merge changes to new locations and
2331 will usually produce better results.