2 .\" Copyright (c) 2017 Martin Pieuchot
3 .\" Copyright (c) 2018, 2019, 2020 Stefan Sperling
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
30 is a version control system which stores the history of tracked files
31 in a Git repository, as used by the Git version control system.
32 This repository format is described in
33 .Xr git-repository 5 .
38 version control system because every copy of a repository is writeable.
39 Modifications made to files can be synchronized between repositories
44 must be checked out from the repository for modification.
45 Checked out files are stored in a
47 which can be placed at an arbitrary directory in the filesystem hierarchy.
48 The on-disk format of this work tree is described in
52 provides global and command-specific options.
53 Global options must precede the command name, and are as follows:
54 .Bl -tag -width tenletters
56 Display usage information and exit immediately.
58 Display program version and exit immediately.
64 .Bl -tag -width checkout
65 .It Cm init Ar repository-path
66 Create a new empty repository at the specified
73 command must be used to populate the empty repository before
79 .It Cm import Oo Fl b Ar branch Oc Oo Fl m Ar message Oc Oo Fl r Ar repository-path Oc Oo Fl I Ar pattern Oc Ar directory
80 Create an initial commit in a repository from the file hierarchy
83 The created commit will not have any parent commits, i.e. it will be a
85 Also create a new reference which provides a branch name for the newly
87 Show the path of each imported file to indicate progress.
93 environment variable to be set,
98 configuration settings can be obtained from the repository's
100 file or from Git's global
111 instead of creating the default branch
113 Use of this option is required if the
115 branch already exists.
117 Use the specified log message when creating the new commit.
122 opens a temporary file in an editor where a log message can be written.
123 .It Fl r Ar repository-path
124 Use the repository at the specified path.
125 If not specified, assume the repository is located at or above the current
128 Ignore files or directories with a name which matches the specified
130 This option may be specified multiple times to build a list of ignore patterns.
133 follows the globbing rules documented in
139 .It Cm clone Oo Fl a Oc Oo Fl b Ar branch Oc Oo Fl l Oc Oo Fl m Oc Oo Fl q Oc Oo Fl v Oc Ar repository-URL Op Ar directory
140 Clone a Git repository at the specified
146 is specified the directory name will be derived from the name of the
149 will refuse to run if the
155 specifies a protocol scheme, a server hostname, an optional port number
156 separated from the hostname by a colon, and a path to the repository on
158 .Lk scheme://hostname:port/path/to/repository
160 The following protocol schemes are supported:
161 .Bl -tag -width git+ssh
163 The Git protocol as implemented by the
166 Use of this protocol is discouraged since it supports neither authentication
169 The Git protocol wrapped in an authenticated and encrypted
172 With this protocol the hostname may contain an embedded username for
177 Short alias for git+ssh.
180 Objects in the cloned repository are stored in a pack file which is downloaded
182 This pack file will then be indexed to facilitate access to the objects stored
184 If any objects in the pack file are stored in deltified form, all deltas will
185 be fully resolved in order to compute the ID of such objects.
186 This can take some time.
187 More details about the pack file format are documented in
188 .Xr git-repository 5 .
191 creates a remote repository entry in the
193 file of the cloned repository to store the
205 Fetch all branches from the remote repository's
208 If this option is not specified, a branch resolved via the remote
209 repository's HEAD reference will be fetched.
210 Cannot be used together with the
216 from the remote repository's
219 This option may be specified multiple times to build a list of branches
221 If the branch corresponding to the remote repository's HEAD reference is not
222 in this list, the cloned repository's HEAD reference will be set to the first
223 branch which was fetched.
224 If this option is not specified, a branch resolved via the remote
225 repository's HEAD reference will be fetched.
226 Cannot be used together with the
230 List branches and tags available for cloning from the remote repository
231 and exit immediately.
232 Cannot be used together with any of the other options except
235 Create the cloned repository as a mirror of the original repository.
236 This is useful if the cloned repository will not be used to store
237 local changes as created by
242 file will be set up with the
244 option enabled, such that
248 will write incoming changes directly to local branches in the
250 reference namespace, rather than to branches in the
253 This avoids the usual requirement of having to run
257 in order to make incoming changes appear on local branches.
258 But maintaining local changes in the cloned repository becomes difficult
259 since local changes will be at risk of being discarded whenever incoming
262 Suppress progress reporting output.
263 The same option will be passed to
270 to print debugging messages to standard error output.
271 This option will be passed to
274 Multiple -v options increase the verbosity.
280 .It Cm fetch Oo Fl a Oc Oo Fl b Ar branch Oc Oo Fl d Oc Oo Fl l Oc Oo Fl r Ar repository-path Oc Oo Fl t Oc Oo Fl q Oc Oo Fl v Oc Op Ar remote-repository
281 Fetch new changes from a remote repository.
283 .Ar remote-repository
287 The remote repository's URL is obtained from the corresponding entry in the
289 file of the local repository, as created by
292 New changes will be stored in a separate pack file downloaded from the server.
293 Optionally, separate pack files stored in the repository can be combined with
296 By default, branch references in the
298 reference namespace will be updated to point at the newly fetched commits.
301 command can then be used to make new changes visible on local branches in the
303 namespace, merging incoming changes with local changes as necessary.
305 If the repository was created as a mirror with
307 then all branches in the
309 namespace will be updated directly to match the corresponding branches in
310 the remote repository.
311 If those branches contained local commits, these commits will no longer be
312 reachable via a reference and will therefore be at risk of being discarded
313 by Git's garbage collector.
314 Maintaining local changes in a mirror repository is therefore discouraged.
316 In any case, references in the
318 namespace will always be fetched and mapped directly to local references
319 in the same namespace.
326 Fetch all branches from the remote repository's
329 If this option is not specified, a branch resolved via the remote
330 repository's HEAD reference will be fetched.
331 Cannot be used together with the
337 from the remote repository's
340 This option may be specified multiple times to build a list of branches
342 If this option is not specified, a branch resolved via the remote
343 repository's HEAD reference will be fetched.
344 Cannot be used together with the
348 Delete branches and tags from the local repository which are no longer
349 present in the remote repository.
350 Only references are deleted.
351 Any commit, tree, and blob objects belonging to deleted branches or
352 tags remain in the repository and may be removed separately with
353 Git's garbage collector.
355 List branches and tags available for fetching from the remote repository
356 and exit immediately.
357 Cannot be used together with any of the other options except
362 Allow existing references in the
364 namespace to be updated if they have changed on the server.
365 If not specified, only new tag references will be created.
366 .It Fl r Ar repository-path
367 Use the repository at the specified path.
368 If not specified, assume the repository is located at or above the current
370 If this directory is a
372 work tree, use the repository path associated with this work tree.
374 Suppress progress reporting output.
375 The same option will be passed to
382 to print debugging messages to standard error output.
383 The same option will be passed to
386 Multiple -v options increase the verbosity.
392 .It Cm checkout Oo Fl E Oc Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Oo Fl p Ar path-prefix Oc Ar repository-path Op Ar work-tree-path
393 Copy files from a repository into a new work tree.
394 Show the status of each affected file, using the following status codes:
395 .Bl -column YXZ description
396 .It A Ta new file was added
397 .It E Ta file already exists in work tree's meta-data
402 is not specified, either use the last component of
403 .Ar repository path ,
406 was specified use the last component of
414 Proceed with the checkout operation even if the directory at
417 Existing files will be left intact.
419 Check out files from a commit on the specified
421 If this option is not specified, a branch resolved via the repository's HEAD
422 reference will be used.
424 Check out files from the specified
426 on the selected branch.
427 The expected argument is a commit ID SHA1 hash or an existing reference
428 or tag name which will be resolved to a commit ID.
429 An abbreviated hash argument will be expanded to a full SHA1 hash
430 automatically, provided the abbreviation is unique.
431 If this option is not specified, the most recent commit on the selected
436 is not contained in the selected branch, a different branch which contains
437 this commit must be specified with the
440 If no such branch is known a new branch must be created for this
446 Checking out work trees with an unknown branch is intentionally not supported.
447 .It Fl p Ar path-prefix
448 Restrict the work tree to a subset of the repository's tree hierarchy.
449 Only files beneath the specified
456 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
457 Update an existing work tree to a different commit.
458 Show the status of each affected file, using the following status codes:
459 .Bl -column YXZ description
460 .It U Ta file was updated and contained no local changes
461 .It G Ta file was updated and local changes were merged cleanly
462 .It C Ta file was updated and conflicts occurred during merge
463 .It D Ta file was deleted
464 .It A Ta new file was added
465 .It \(a~ Ta versioned file is obstructed by a non-regular file
466 .It ! Ta a missing versioned file was restored
471 is specified, update the entire work tree.
472 Otherwise, restrict the update operation to files at or within the
474 Each path is required to exist in the update operation's target commit.
475 Files in the work tree outside specified paths will remain unchanged and
476 will retain their previously recorded base commit.
479 commands may refuse to run while the work tree contains files from
480 multiple base commits.
481 The base commit of such a work tree can be made consistent by running
483 across the entire work tree.
486 is incompatible with the
491 cannot update paths with staged changes.
492 If changes have been staged with
494 these changes must first be committed with
504 Switch the work tree's branch reference to the specified
506 before updating the work tree.
507 This option requires that all paths in the work tree are updated.
509 Update the work tree to the specified
511 The expected argument is a commit ID SHA1 hash or an existing reference
512 or tag name which will be resolved to a commit ID.
513 An abbreviated hash argument will be expanded to a full SHA1 hash
514 automatically, provided the abbreviation is unique.
515 If this option is not specified, the most recent commit on the work tree's
521 .It Cm status Op Ar path ...
522 Show the current modification status of files in a work tree,
523 using the following status codes:
524 .Bl -column YXZ description
525 .It M Ta modified file
526 .It A Ta file scheduled for addition in next commit
527 .It D Ta file scheduled for deletion in next commit
528 .It C Ta modified or added file which contains merge conflicts
529 .It ! Ta versioned file was expected on disk but is missing
530 .It \(a~ Ta versioned file is obstructed by a non-regular file
531 .It ? Ta unversioned item not tracked by
533 .It m Ta modified file modes (executable bit only)
534 .It N Ta non-existent
536 specified on the command line
541 is specified, show modifications in the entire work tree.
542 Otherwise, show modifications at or within the specified paths.
544 If changes have been staged with
546 staged changes are shown in the second output column, using the following
548 .Bl -column YXZ description
549 .It M Ta file modification is staged
550 .It A Ta file addition is staged
551 .It D Ta file deletion is staged
554 Changes created on top of staged changes are indicated in the first column:
555 .Bl -column YXZ description
556 .It MM Ta file was modified after earlier changes have been staged
557 .It MA Ta file was modified after having been staged for addition
560 For compatibility with
571 files in each traversed directory and will not display unversioned files
572 which match these patterns.
577 supports consecutive asterisks,
579 which will match an arbitrary amount of directories.
583 only supports a single ignore pattern per line.
587 does not support negated ignore patterns prefixed with
589 and gives no special significance to the location of path component separators,
595 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl C Ar number Oc Oo Fl l Ar N Oc Oo Fl p Oc Oo Fl s Ar search-pattern Oc Oo Fl r Ar repository-path Oc Op Ar path
596 Display history of a repository.
599 is specified, show only commits which modified this path.
600 If invoked in a work tree, the
602 is interpreted relative to the current working directory,
603 and the work tree's path prefix is implicitly prepended.
604 Otherwise, the path is interpreted relative to the repository root.
611 Display individual commits which were merged into the current branch
615 shows the linear history of the current branch only.
617 Start traversing history at the specified
619 The expected argument is a commit ID SHA1 hash or an existing reference
620 or tag name which will be resolved to a commit ID.
621 An abbreviated hash argument will be expanded to a full SHA1 hash
622 automatically, provided the abbreviation is unique.
623 If this option is not specified, default to the work tree's current branch
624 if invoked in a work tree, or to the repository's HEAD reference.
626 Set the number of context lines shown in diffs with
628 By default, 3 lines of context are shown.
630 Limit history traversal to a given number of commits.
631 If this option is not specified, a default limit value of zero is used,
632 which is treated as an unbounded limit.
634 .Ev GOT_LOG_DEFAULT_LIMIT
635 environment variable may be set to change this default value.
637 Display the patch of modifications made in each commit.
640 is specified, only show the patch of modifications at or within this path.
641 .It Fl s Ar search-pattern
642 If specified, show only commits with a log message matched by the extended
645 Regular expression syntax is documented in
647 .It Fl r Ar repository-path
648 Use the repository at the specified path.
649 If not specified, assume the repository is located at or above the current
651 If this directory is a
653 work tree, use the repository path associated with this work tree.
655 .It Cm diff Oo Fl C Ar number Oc Oo Fl r Ar repository-path Oc Oo Fl s Oc Oo Fl w Oc Op Ar object1 Ar object2 | Ar path
656 When invoked within a work tree with less than two arguments, display
657 uncommitted changes in the work tree.
660 is specified, only show changes within this path.
662 If two arguments are provided, treat each argument as a reference, a tag
663 name, or an object ID SHA1 hash, and display differences between the
664 corresponding objects.
665 Both objects must be of the same type (blobs, trees, or commits).
666 An abbreviated hash argument will be expanded to a full SHA1 hash
667 automatically, provided the abbreviation is unique.
674 Set the number of context lines shown in the diff.
675 By default, 3 lines of context are shown.
676 .It Fl r Ar repository-path
677 Use the repository at the specified path.
678 If not specified, assume the repository is located at or above the current
680 If this directory is a
682 work tree, use the repository path associated with this work tree.
684 Show changes staged with
686 instead of showing local changes.
687 This option is only valid when
689 is invoked in a work tree.
691 Ignore whitespace-only changes.
696 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
697 Display line-by-line history of a file at the specified path.
704 Start traversing history at the specified
706 The expected argument is a commit ID SHA1 hash or an existing reference
707 or tag name which will be resolved to a commit ID.
708 An abbreviated hash argument will be expanded to a full SHA1 hash
709 automatically, provided the abbreviation is unique.
710 .It Fl r Ar repository-path
711 Use the repository at the specified path.
712 If not specified, assume the repository is located at or above the current
714 If this directory is a
716 work tree, use the repository path associated with this work tree.
721 .It Cm tree Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl i Oc Oo Fl R Oc Op Ar path
722 Display a listing of files and directories at the specified
723 directory path in the repository.
724 Entries shown in this listing may carry one of the following trailing
726 .Bl -column YXZ description
727 .It @ Ta entry is a symbolic link
728 .It / Ta entry is a directory
729 .It * Ta entry is an executable file
730 .It $ Ta entry is a Git submodule
735 is specified, list the repository path corresponding to the current
736 directory of the work tree, or the root directory of the repository
737 if there is no work tree.
744 List files and directories as they appear in the specified
746 The expected argument is a commit ID SHA1 hash or an existing reference
747 or tag name which will be resolved to a commit ID.
748 An abbreviated hash argument will be expanded to a full SHA1 hash
749 automatically, provided the abbreviation is unique.
750 .It Fl r Ar repository-path
751 Use the repository at the specified path.
752 If not specified, assume the repository is located at or above the current
754 If this directory is a
756 work tree, use the repository path associated with this work tree.
758 Show object IDs of files (blob objects) and directories (tree objects).
760 Recurse into sub-directories in the repository.
765 .It Cm ref Oo Fl r Ar repository-path Oc Oo Fl l Oc Oo Fl d Ar name Oc Oo Fl s Oc Op Ar name Ar target
766 Manage references in a repository.
768 If no options are passed, expect two arguments and attempt to create,
769 or update, the reference with the given
771 and make it point at the given
773 The name must be an absolute reference name, i.e. it must begin with
775 The target may be an object ID SHA1 hash or an existing reference which
776 will be resolved to an object ID.
777 An abbreviated hash argument will be expanded to a full SHA1 hash
778 automatically, provided the abbreviation is unique.
784 .It Fl r Ar repository-path
785 Use the repository at the specified path.
786 If not specified, assume the repository is located at or above the current
788 If this directory is a
790 work tree, use the repository path associated with this work tree.
792 List all existing references in the repository.
794 Delete the reference with the specified name from the repository.
796 Create a symbolic reference pointing at the specified
798 which must be an existing reference.
799 Care should be taken not to create loops between references when
802 .It Cm branch Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl l Oc Oo Fl d Ar name Oc Oo Fl n Oc Op Ar name
803 Create, list, or delete branches.
805 Branches are managed via references which live in the
810 command operates on references in this namespace only.
812 If invoked in a work tree without any arguments, print the name of the
813 work tree's current branch.
817 argument is passed, attempt to create a branch reference with the given name.
818 By default the new branch reference will point at the latest commit on the
819 work tree's current branch if invoked in a work tree, and otherwise to a commit
820 resolved via the repository's HEAD reference.
822 If invoked in a work tree, once the branch was created successfully
823 switch the work tree's head reference to the newly created branch and
824 update files across the entire work tree, just like
825 .Cm got update -b Ar name
827 Show the status of each affected file, using the following status codes:
828 .Bl -column YXZ description
829 .It U Ta file was updated and contained no local changes
830 .It G Ta file was updated and local changes were merged cleanly
831 .It C Ta file was updated and conflicts occurred during merge
832 .It D Ta file was deleted
833 .It A Ta new file was added
834 .It \(a~ Ta versioned file is obstructed by a non-regular file
835 .It ! Ta a missing versioned file was restored
843 Make a newly created branch reference point at the specified
847 argument is a commit ID SHA1 hash or an existing reference
848 or tag name which will be resolved to a commit ID.
849 .It Fl r Ar repository-path
850 Use the repository at the specified path.
851 If not specified, assume the repository is located at or above the current
853 If this directory is a
855 work tree, use the repository path associated with this work tree.
857 List all existing branches in the repository.
858 If invoked in a work tree, the work tree's current branch is shown
859 with one the following annotations:
860 .Bl -column YXZ description
861 .It * Ta work tree's base commit matches the branch tip
862 .It \(a~ Ta work tree's base commit is out-of-date
865 Delete the branch with the specified name from the repository.
866 Only the branch reference is deleted.
867 Any commit, tree, and blob objects belonging to the branch
868 remain in the repository and may be removed separately with
869 Git's garbage collector.
871 Do not switch and update the work tree after creating a new branch.
876 .It Cm tag Oo Fl c Ar commit Oc Oo Fl m Ar message Oc Oo Fl r Ar repository-path Oc Oo Fl l Oc Ar name
877 Manage tags in a repository.
879 Tags are managed via references which live in the
884 command operates on references in this namespace only.
885 References in this namespace point at tag objects which contain a pointer
886 to another object, a tag message, as well as author and timestamp information.
888 Attempt to create a tag with the given
890 and make this tag point at the given
892 If no commit is specified, default to the latest commit on the work tree's
893 current branch if invoked in a work tree, and to a commit resolved via
894 the repository's HEAD reference otherwise.
901 Make the newly created tag reference point at the specified
905 argument is a commit ID SHA1 hash or an existing reference or tag name which
906 will be resolved to a commit ID.
907 An abbreviated hash argument will be expanded to a full SHA1 hash
908 automatically, provided the abbreviation is unique.
910 Use the specified tag message when creating the new tag.
915 opens a temporary file in an editor where a tag message can be written.
916 .It Fl r Ar repository-path
917 Use the repository at the specified path.
918 If not specified, assume the repository is located at or above the current
920 If this directory is a
922 work tree, use the repository path associated with this work tree.
924 List all existing tags in the repository instead of creating a new tag.
925 If this option is used, no other command-line arguments are allowed.
930 command will not delete tags or change existing tags.
931 If a tag must be deleted, the
933 command may be used to delete a tag's reference.
934 This should only be done if the tag has not already been copied to
936 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
937 Schedule unversioned files in a work tree for addition to the
938 repository in the next commit.
945 Permit recursion into directories.
946 If this option is not specified,
948 will refuse to run if a specified
952 With -R, add files even if they match a
956 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
957 Remove versioned files from a work tree and schedule them for deletion
958 from the repository in the next commit.
965 Perform the operation even if a file contains uncommitted modifications.
967 Keep affected files on disk.
969 Permit recursion into directories.
970 If this option is not specified,
972 will refuse to run if a specified
979 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
980 Revert any uncommitted changes in files at the specified paths.
981 File contents will be overwritten with those contained in the
982 work tree's base commit.
983 There is no way to bring discarded changes back after
986 If a file was added with
988 it will become an unversioned file again.
989 If a file was deleted with
998 Instead of reverting all changes in files, interactively select or reject
999 changes to revert based on
1005 (quit reverting this file) responses.
1006 If a file is in modified status, individual patches derived from the
1007 modified file content can be reverted.
1008 Files in added or deleted status may only be reverted in their entirety.
1009 .It Fl F Ar response-script
1017 responses line-by-line from the specified
1019 file instead of prompting interactively.
1021 Permit recursion into directories.
1022 If this option is not specified,
1024 will refuse to run if a specified
1031 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1032 Create a new commit in the repository from changes in a work tree
1033 and use this commit as the new base commit for the work tree.
1036 is specified, commit all changes in the work tree.
1037 Otherwise, commit changes at or within the specified paths.
1039 If changes have been explicitly staged for commit with
1041 only commit staged changes and reject any specified paths which
1042 have not been staged.
1044 Show the status of each affected file, using the following status codes:
1045 .Bl -column YXZ description
1046 .It M Ta modified file
1047 .It D Ta file was deleted
1048 .It A Ta new file was added
1049 .It m Ta modified file modes (executable bit only)
1052 Files which are not part of the new commit will retain their previously
1053 recorded base commit.
1056 commands may refuse to run while the work tree contains files from
1057 multiple base commits.
1058 The base commit of such a work tree can be made consistent by running
1060 across the entire work tree.
1064 command requires the
1066 environment variable to be set,
1071 configuration settings can be
1072 obtained from the repository's
1074 file or from Git's global
1083 Use the specified log message when creating the new commit.
1088 opens a temporary file in an editor where a log message can be written.
1092 will refuse to run if certain preconditions are not met.
1093 If the work tree's current branch is not in the
1095 reference namespace, new commits may not be created on this branch.
1096 Local changes may only be committed if they are based on file content
1097 found in the most recent commit on the work tree's branch.
1098 If a path is found to be out of date,
1100 must be used first in order to merge local changes with changes made
1105 .It Cm cherrypick Ar commit
1106 Merge changes from a single
1111 must be on a different branch than the work tree's base commit.
1112 The expected argument is a reference or a commit ID SHA1 hash.
1113 An abbreviated hash argument will be expanded to a full SHA1 hash
1114 automatically, provided the abbreviation is unique.
1116 Show the status of each affected file, using the following status codes:
1117 .Bl -column YXZ description
1118 .It G Ta file was merged
1119 .It C Ta file was merged and conflicts occurred during merge
1120 .It ! Ta changes destined for a missing file were not merged
1121 .It D Ta file was deleted
1122 .It d Ta file's deletion was obstructed by local modifications
1123 .It A Ta new file was added
1124 .It \(a~ Ta changes destined for a non-regular file were not merged
1127 The merged changes will appear as local changes in the work tree, which
1130 amended manually or with further
1135 or discarded again with
1139 will refuse to run if certain preconditions are not met.
1140 If the work tree contains multiple base commits it must first be updated
1141 to a single base commit with
1143 If the work tree already contains files with merge conflicts, these
1144 conflicts must be resolved first.
1148 .It Cm backout Ar commit
1149 Reverse-merge changes from a single
1154 must be on the same branch as the work tree's base commit.
1155 The expected argument is a reference or a commit ID SHA1 hash.
1156 An abbreviated hash argument will be expanded to a full SHA1 hash
1157 automatically, provided the abbreviation is unique.
1159 Show the status of each affected file, using the following status codes:
1160 .Bl -column YXZ description
1161 .It G Ta file was merged
1162 .It C Ta file was merged and conflicts occurred during merge
1163 .It ! Ta changes destined for a missing file were not merged
1164 .It D Ta file was deleted
1165 .It d Ta file's deletion was obstructed by local modifications
1166 .It A Ta new file was added
1167 .It \(a~ Ta changes destined for a non-regular file were not merged
1170 The reverse-merged changes will appear as local changes in the work tree,
1171 which may be viewed with
1173 amended manually or with further
1178 or discarded again with
1182 will refuse to run if certain preconditions are not met.
1183 If the work tree contains multiple base commits it must first be updated
1184 to a single base commit with
1186 If the work tree already contains files with merge conflicts, these
1187 conflicts must be resolved first.
1191 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1192 Rebase commits on the specified
1194 onto the tip of the current branch of the work tree.
1197 must share common ancestry with the work tree's current branch.
1198 Rebasing begins with the first descendant commit of the youngest
1199 common ancestor commit shared by the specified
1201 and the work tree's current branch, and stops once the tip commit
1208 is used as intended, the specified
1210 represents a local commit history and may already contain changes
1211 that are not yet visible in any other repositories.
1212 The work tree's current branch, which must be set with
1216 operation, represents a branch from a remote repository which shares
1217 a common history with the specified
1219 but has progressed, and perhaps diverged, due to commits added to the
1222 Rebased commits are accumulated on a temporary branch which the work tree
1223 will remain switched to throughout the entire rebase operation.
1224 Commits on this branch represent the same changes with the same log
1225 messages as their counterparts on the original
1227 but with different commit IDs.
1228 Once rebasing has completed successfully, the temporary branch becomes
1229 the new version of the specified
1231 and the work tree is automatically switched to it.
1233 While rebasing commits, show the status of each affected file,
1234 using the following status codes:
1235 .Bl -column YXZ description
1236 .It G Ta file was merged
1237 .It C Ta file was merged and conflicts occurred during merge
1238 .It ! Ta changes destined for a missing file were not merged
1239 .It D Ta file was deleted
1240 .It d Ta file's deletion was obstructed by local modifications
1241 .It A Ta new file was added
1242 .It \(a~ Ta changes destined for a non-regular file were not merged
1245 If merge conflicts occur the rebase operation is interrupted and may
1246 be continued once conflicts have been resolved.
1247 Alternatively, the rebase operation may be aborted which will leave
1249 unmodified and the work tree switched back to its original branch.
1251 If a merge conflict is resolved in a way which renders the merged
1252 change into a no-op change, the corresponding commit will be elided
1253 when the rebase operation continues.
1256 will refuse to run if certain preconditions are not met.
1257 If the work tree is not yet fully updated to the tip commit of its
1258 branch then the work tree must first be updated with
1260 If changes have been staged with
1262 these changes must first be committed with
1266 If the work tree contains local changes, these changes must first be
1273 contains changes to files outside of the work tree's path prefix,
1274 the work tree cannot be used to rebase this branch.
1280 commands will refuse to run while a rebase operation is in progress.
1281 Other commands which manipulate the work tree may be used for
1282 conflict resolution purposes.
1289 Abort an interrupted rebase operation.
1290 If this option is used, no other command-line arguments are allowed.
1292 Continue an interrupted rebase operation.
1293 If this option is used, no other command-line arguments are allowed.
1298 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1299 Edit commit history between the work tree's current base commit and
1300 the tip commit of the work tree's current branch.
1304 operation the work tree's current branch must be set with
1306 to the branch which should be edited, unless this branch is already the
1307 current branch of the work tree.
1308 The tip of this branch represents the upper bound (inclusive) of commits
1313 Furthermore, the work tree's base commit
1316 to a point in this branch's commit history where editing should begin.
1317 This commit represents the lower bound (non-inclusive) of commits touched
1322 Editing of commit history is controlled via a
1324 which can be written in an editor based on a template, passed on the
1325 command line, or generated with the
1327 option if only log messages need to be edited.
1329 The format of the histedit script is line-based.
1330 Each line in the script begins with a command name, followed by
1331 whitespace and an argument.
1332 For most commands, the expected argument is a commit ID SHA1 hash.
1333 Any remaining text on the line is ignored.
1334 Lines which begin with the
1336 character are ignored entirely.
1338 The available commands are as follows:
1339 .Bl -column YXZ pick-commit
1340 .It pick Ar commit Ta Use the specified commit as it is.
1341 .It edit Ar commit Ta Use the specified commit but once changes have been
1342 merged into the work tree interrupt the histedit operation for amending.
1343 .It fold Ar commit Ta Combine the specified commit with the next commit
1344 listed further below that will be used.
1345 .It drop Ar commit Ta Remove this commit from the edited history.
1346 .It mesg Ar log-message Ta Use the specified single-line log message for
1347 the commit on the previous line.
1348 If the log message argument is left empty, open an editor where a new
1349 log message can be written.
1352 Every commit in the history being edited must be mentioned in the script.
1353 Lines may be re-ordered to change the order of commits in the edited history.
1354 No commit may be listed more than once.
1356 Edited commits are accumulated on a temporary branch which the work tree
1357 will remain switched to throughout the entire histedit operation.
1358 Once history editing has completed successfully, the temporary branch becomes
1359 the new version of the work tree's branch and the work tree is automatically
1362 While merging commits, show the status of each affected file,
1363 using the following status codes:
1364 .Bl -column YXZ description
1365 .It G Ta file was merged
1366 .It C Ta file was merged and conflicts occurred during merge
1367 .It ! Ta changes destined for a missing file were not merged
1368 .It D Ta file was deleted
1369 .It d Ta file's deletion was obstructed by local modifications
1370 .It A Ta new file was added
1371 .It \(a~ Ta changes destined for a non-regular file were not merged
1374 If merge conflicts occur the histedit operation is interrupted and may
1375 be continued once conflicts have been resolved.
1376 Alternatively, the histedit operation may be aborted which will leave
1377 the work tree switched back to its original branch.
1379 If a merge conflict is resolved in a way which renders the merged
1380 change into a no-op change, the corresponding commit will be elided
1381 when the histedit operation continues.
1384 will refuse to run if certain preconditions are not met.
1385 If the work tree's current branch is not in the
1387 reference namespace, the history of the branch may not be edited.
1388 If the work tree contains multiple base commits it must first be updated
1389 to a single base commit with
1391 If changes have been staged with
1393 these changes must first be committed with
1397 If the work tree contains local changes, these changes must first be
1402 If the edited history contains changes to files outside of the work tree's
1403 path prefix, the work tree cannot be used to edit the history of this branch.
1410 commands will refuse to run while a histedit operation is in progress.
1411 Other commands which manipulate the work tree may be used, and the
1413 command may be used to commit arbitrary changes to the temporary branch
1414 while the histedit operation is interrupted.
1421 Abort an interrupted histedit operation.
1422 If this option is used, no other command-line arguments are allowed.
1424 Continue an interrupted histedit operation.
1425 If this option is used, no other command-line arguments are allowed.
1426 .It Fl F Ar histedit-script
1429 instead of opening a temporary file in an editor where a histedit script
1432 Edit log messages only.
1433 This option is a quick equivalent to a histedit script which edits
1434 only log messages but otherwise leaves every picked commit as-is.
1437 option can only be used when starting a new histedit operation.
1438 If this option is used, no other command-line arguments are allowed.
1443 .It Cm integrate Ar branch
1444 Integrate the specified
1446 into the work tree's current branch.
1447 Files in the work tree are updated to match the contents on the integrated
1449 and the reference of the work tree's branch is changed to point at the
1450 head commit of the integrated
1453 Both branches can be considered equivalent after integration since they
1454 will be pointing at the same commit.
1455 Both branches remain available for future work, if desired.
1456 In case the integrated
1458 is no longer needed it may be deleted with
1461 Show the status of each affected file, using the following status codes:
1462 .Bl -column YXZ description
1463 .It U Ta file was updated
1464 .It D Ta file was deleted
1465 .It A Ta new file was added
1466 .It \(a~ Ta versioned file is obstructed by a non-regular file
1467 .It ! Ta a missing versioned file was restored
1471 will refuse to run if certain preconditions are not met.
1472 Most importantly, the
1474 must have been rebased onto the work tree's current branch with
1476 before it can be integrated, in order to linearize commit history and
1477 resolve merge conflicts.
1478 If the work tree contains multiple base commits it must first be updated
1479 to a single base commit with
1481 If changes have been staged with
1483 these changes must first be committed with
1487 If the work tree contains local changes, these changes must first be
1495 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1496 Stage local changes for inclusion in the next commit.
1499 is specified, stage all changes in the work tree.
1500 Otherwise, stage changes at or within the specified paths.
1501 Paths may be staged if they are added, modified, or deleted according to
1504 Show the status of each affected file, using the following status codes:
1505 .Bl -column YXZ description
1506 .It A Ta file addition has been staged
1507 .It M Ta file modification has been staged
1508 .It D Ta file deletion has been staged
1511 Staged file contents are saved in newly created blob objects in the repository.
1512 These blobs will be referred to by tree objects once staged changes have been
1515 Staged changes affect the behaviour of
1520 While paths with staged changes exist, the
1522 command will refuse to commit any paths which do not have staged changes.
1523 Local changes created on top of staged changes can only be committed if
1524 the path is staged again, or if the staged changes are committed first.
1527 command will show both local changes and staged changes.
1530 command is able to display local changes relative to staged changes,
1531 and to display staged changes relative to the repository.
1534 command cannot revert staged changes but may be used to revert
1535 local changes created on top of staged changes.
1542 Instead of staging new changes, list paths which are already staged,
1543 along with the IDs of staged blob objects and stage status codes.
1544 If paths were provided in the command line show the staged paths
1545 among the specified paths.
1546 Otherwise, show all staged paths.
1548 Instead of staging the entire content of a changed file, interactively
1549 select or reject changes for staging based on
1553 (reject change), and
1555 (quit staging this file) responses.
1556 If a file is in modified status, individual patches derived from the
1557 modified file content can be staged.
1558 Files in added or deleted status may only be staged or rejected in
1560 .It Fl F Ar response-script
1568 responses line-by-line from the specified
1570 file instead of prompting interactively.
1574 will refuse to run if certain preconditions are not met.
1575 If a file contains merge conflicts, these conflicts must be resolved first.
1576 If a file is found to be out of date relative to the head commit on the
1577 work tree's current branch, the file must be updated with
1579 before it can be staged (however, this does not prevent the file from
1580 becoming out-of-date at some point after having been staged).
1587 commands will refuse to run while staged changes exist.
1588 If staged changes cannot be committed because a staged path
1589 is out of date, the path must be unstaged with
1591 before it can be updated with
1593 and may then be staged again if necessary.
1597 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1598 Merge staged changes back into the work tree and put affected paths
1599 back into non-staged status.
1602 is specified, unstage all staged changes across the entire work tree.
1603 Otherwise, unstage changes at or within the specified paths.
1605 Show the status of each affected file, using the following status codes:
1606 .Bl -column YXZ description
1607 .It G Ta file was unstaged
1608 .It C Ta file was unstaged and conflicts occurred during merge
1609 .It ! Ta changes destined for a missing file were not merged
1610 .It D Ta file was staged as deleted and still is deleted
1611 .It d Ta file's deletion was obstructed by local modifications
1612 .It \(a~ Ta changes destined for a non-regular file were not merged
1620 Instead of unstaging the entire content of a changed file, interactively
1621 select or reject changes for unstaging based on
1625 (keep change staged), and
1627 (quit unstaging this file) responses.
1628 If a file is staged in modified status, individual patches derived from the
1629 staged file content can be unstaged.
1630 Files staged in added or deleted status may only be unstaged in their entirety.
1631 .It Fl F Ar response-script
1639 responses line-by-line from the specified
1641 file instead of prompting interactively.
1646 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1647 Parse and print contents of objects to standard output in a line-based
1649 Content of commit, tree, and tag objects is printed in a way similar
1650 to the actual content stored in such objects.
1651 Blob object contents are printed as they would appear in files on disk.
1653 Attempt to interpret each argument as a reference, a tag name, or
1654 an object ID SHA1 hash.
1655 References will be resolved to an object ID.
1656 Tag names will resolved to a tag object.
1657 An abbreviated hash argument will be expanded to a full SHA1 hash
1658 automatically, provided the abbreviation is unique.
1660 If none of the above interpretations produce a valid result, or if the
1662 option is used, attempt to interpret the argument as a path which will
1663 be resolved to the ID of an object found at this path in the repository.
1670 Look up paths in the specified
1672 If this option is not used, paths are looked up in the commit resolved
1673 via the repository's HEAD reference.
1674 The expected argument is a commit ID SHA1 hash or an existing reference
1675 or tag name which will be resolved to a commit ID.
1676 An abbreviated hash argument will be expanded to a full SHA1 hash
1677 automatically, provided the abbreviation is unique.
1678 .It Fl r Ar repository-path
1679 Use the repository at the specified path.
1680 If not specified, assume the repository is located at or above the current
1682 If this directory is a
1684 work tree, use the repository path associated with this work tree.
1686 Interpret all arguments as paths only.
1687 This option can be used to resolve ambiguity in cases where paths
1688 look like tag names, reference names, or object IDs.
1692 .Bl -tag -width GOT_AUTHOR
1694 The author's name and email address for
1699 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1702 may fail to parse commits without an email address in author data,
1706 environment variables with a missing email address.
1712 configuration settings in the repository's
1714 file will override the value of
1720 configuration settings contained in Git's global
1722 configuration file will be used only if the
1724 environment variable is
1727 .It Ev VISUAL , EDITOR
1728 The editor spawned by
1733 .It Ev GOT_LOG_DEFAULT_LIMIT
1734 The default limit on the number of commits traversed by
1736 If set to zero, the limit is unbounded.
1737 This variable will be silently ignored if it is set to a non-numeric value.
1742 Clone an existing Git repository for use with
1746 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1748 Use of HTTP URLs currently requires
1752 .Dl $ git clone --bare https://github.com/openbsd/src.git
1754 Alternatively, for quick and dirty local testing of
1756 a new Git repository could be created and populated with files,
1757 e.g. from a temporary CVS checkout located at
1760 .Dl $ got init /var/git/src.git
1761 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1763 Check out a work tree from the Git repository to /usr/src:
1765 .Dl $ got checkout /var/git/src.git /usr/src
1767 View local changes in a work tree directory:
1770 .Dl $ got diff | less
1772 Interactively revert selected local changes in a work tree directory:
1774 .Dl $ got revert -p -R\ .
1776 In a work tree or a git repository directory, list all branch references:
1780 In a work tree or a git repository directory, create a new branch called
1781 .Dq unified-buffer-cache
1782 which is forked off the
1786 .Dl $ got branch unified-buffer-cache master
1788 Switch an existing work tree to the branch
1789 .Dq unified-buffer-cache .
1790 Local changes in the work tree will be preserved and merged if necessary:
1792 .Dl $ got update -b unified-buffer-cache
1794 Create a new commit from local changes in a work tree directory.
1795 This new commit will become the head commit of the work tree's current branch:
1799 In a work tree or a git repository directory, view changes committed in
1800 the 3 most recent commits to the work tree's branch, or the branch resolved
1801 via the repository's HEAD reference, respectively:
1803 .Dl $ got log -p -l 3
1805 In a work tree or a git repository directory, log the history of a subdirectory:
1807 .Dl $ got log sys/uvm
1809 While operating inside a work tree, paths are specified relative to the current
1810 working directory, so this command will log the subdirectory
1813 .Dl $ cd sys/uvm && got log '.'
1815 And this command has the same effect:
1817 .Dl $ cd sys/dev/usb && got log ../../uvm
1819 Add new files and remove obsolete files in a work tree directory:
1821 .Dl $ got add sys/uvm/uvm_ubc.c
1822 .Dl $ got remove sys/uvm/uvm_vnode.c
1824 Create a new commit from local changes in a work tree directory
1825 with a pre-defined log message.
1827 .Dl $ got commit -m 'unify the buffer cache'
1829 Update any work tree checked out from the
1830 .Dq unified-buffer-cache
1831 branch to the latest commit on this branch:
1835 Roll file content on the unified-buffer-cache branch back by one commit,
1836 and then fetch the rolled-back change into the work tree as a local change
1837 to be amended and perhaps committed again:
1839 .Dl $ got backout unified-buffer-cache
1840 .Dl $ got commit -m 'roll back previous'
1841 .Dl $ # now back out the previous backout :-)
1842 .Dl $ got backout unified-buffer-cache
1844 Fetch new upstream commits into the local repository's
1851 In a repository created with a HTTP URL and
1852 .Cm git clone --bare
1855 command must be used instead:
1857 .Dl $ cd /var/git/src.git
1858 .Dl $ git fetch origin master:refs/remotes/origin/master
1862 branch to merge the new changes that are now visible on the
1867 .Dl $ got update -b origin/master
1868 .Dl $ got rebase master
1871 .Dq unified-buffer-cache
1872 branch on top of the new head commit of the
1876 .Dl $ got update -b master
1877 .Dl $ got rebase unified-buffer-cache
1879 Create a patch from all changes on the unified-buffer-cache branch.
1880 The patch can be mailed out for review and applied to
1884 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1886 Edit the entire commit history of the
1887 .Dq unified-buffer-cache
1890 .Dl $ got update -b unified-buffer-cache
1891 .Dl $ got update -c master
1894 In order to merge changes committed to the
1895 .Dq unified-buffer-cache
1896 branch back into the
1899 .Dq unified-buffer-cache
1900 branch must first be rebased onto the
1904 .Dl $ got update -b master
1905 .Dl $ got rebase unified-buffer-cache
1908 .Dq unified-buffer-cache
1909 branch can now be made visible on the
1913 Because the rebase operation switched the work tree to the
1914 .Dq unified-buffer-cache
1915 branch, the work tree must be switched back to the
1918 .Dq unified-buffer-cache
1919 branch can be integrated into
1922 .Dl $ got update -b master
1923 .Dl $ got integrate unified-buffer-cache
1925 Additional steps may be necessary if local changes need to be pushed back
1926 to the remote repository, which currently requires
1928 Before working against existing branches in a repository cloned with
1929 .Cm git clone --bare
1934 must be configured to map all references in the remote repository
1937 namespace of the local repository.
1938 This can achieved by setting Git's
1939 .Pa remote.origin.fetch
1940 configuration variable to the value
1941 .Dq +refs/heads/*:refs/remotes/origin/*
1946 .Dl $ cd /var/git/repo
1947 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1950 option must be disabled:
1952 .Dl $ cd /var/git/repo
1953 .Dl $ git config remote.origin.mirror false
1955 Alternatively, the following
1957 configuration item can be added manually to the Git repository's
1961 .Dl [remote "origin"]
1963 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
1966 This configuration leaves the local repository's
1968 namespace free for use by local branches checked out with
1970 and, if needed, created with
1975 namespace can now be updated with incoming changes from the remote
1980 without extra command line arguments:
1982 .Dl $ cd /var/git/repo
1985 To make changes fetched from the remote repository appear on the
1989 branch must be rebased onto the
1992 This will also merge local changes, if any, with the incoming changes:
1994 .Dl $ got update -b origin/master
1995 .Dl $ got rebase master
1999 branch, log messages for local changes can now be amended with
2001 by other developers and any other important new information:
2003 .Dl $ got update -c origin/master
2004 .Dl $ got histedit -m
2006 Local changes on the
2008 branch can then be pushed to the remote
2012 .Dl $ cd /var/git/repo
2013 .Dl $ git push origin master
2016 .Xr git-repository 5 ,
2019 .An Stefan Sperling Aq Mt stsp@openbsd.org
2020 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2021 .An Joshua Stein Aq Mt jcs@openbsd.org
2022 .An Ori Bernstein Aq Mt ori@openbsd.org
2025 is a work-in-progress and many commands remain to be implemented.
2026 At present, the user has to fall back on
2028 to perform many tasks, in particular tasks related to repository
2029 administration and tasks which require a network connection.
