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 Oo Fl R Ar reference 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 fetching 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.
276 .It Fl R Ar reference
277 In addition to the branches and tags that will be fetched, fetch an arbitrary
279 from the remote repository's
282 This option may be specified multiple times to build a list of additional
286 may either be a path to a specific reference, or a reference namespace
287 which will cause all references in this namespace to be fetched.
289 Each reference will be mapped into the cloned repository's
291 namespace, unless the
293 option is used to mirror references directly into the cloned repository's
298 will refuse to fetch references from the remote repository's
307 .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 Oo Fl R Ar reference Oc Op Ar remote-repository
308 Fetch new changes from a remote repository.
310 .Ar remote-repository
314 The remote repository's URL is obtained from the corresponding entry in the
316 file of the local repository, as created by
319 New changes will be stored in a separate pack file downloaded from the server.
320 Optionally, separate pack files stored in the repository can be combined with
323 By default, branch references in the
325 reference namespace will be updated to point at the newly fetched commits.
328 command can then be used to make new changes visible on local branches in the
330 namespace, merging incoming changes with local changes as necessary.
332 If the repository was created as a mirror with
334 then all branches in the
336 namespace will be updated directly to match the corresponding branches in
337 the remote repository.
338 If those branches contained local commits, these commits will no longer be
339 reachable via a reference and will therefore be at risk of being discarded
340 by Git's garbage collector.
341 Maintaining local changes in a mirror repository is therefore discouraged.
343 In any case, references in the
345 namespace will always be fetched and mapped directly to local references
346 in the same namespace.
353 Fetch all branches from the remote repository's
356 If this option is not specified, a branch resolved via the remote
357 repository's HEAD reference will be fetched.
358 Cannot be used together with the
364 from the remote repository's
367 This option may be specified multiple times to build a list of branches
369 If this option is not specified, a branch resolved via the remote
370 repository's HEAD reference will be fetched.
371 Cannot be used together with the
375 Delete branches and tags from the local repository which are no longer
376 present in the remote repository.
377 Only references are deleted.
378 Any commit, tree, tag, and blob objects belonging to deleted branches or
379 tags remain in the repository and may be removed separately with
380 Git's garbage collector.
382 List branches and tags available for fetching from the remote repository
383 and exit immediately.
384 Cannot be used together with any of the other options except
389 Allow existing references in the
391 namespace to be updated if they have changed on the server.
392 If not specified, only new tag references will be created.
393 .It Fl r Ar repository-path
394 Use the repository at the specified path.
395 If not specified, assume the repository is located at or above the current
397 If this directory is a
399 work tree, use the repository path associated with this work tree.
401 Suppress progress reporting output.
402 The same option will be passed to
409 to print debugging messages to standard error output.
410 The same option will be passed to
413 Multiple -v options increase the verbosity.
415 .It Fl R Ar reference
416 In addition to the branches and tags that will be fetched, fetch an arbitrary
418 from the remote repository's
421 This option may be specified multiple times to build a list of additional
425 may either be a path to a specific reference, or a reference namespace
426 which will cause all references in this namespace to be fetched.
428 Each reference will be mapped into the local repository's
430 namespace, unless the local repository was created as a mirror with
432 in which case references will be mapped directly into the local repository's
436 Once a reference has been fetched, a local branch based on it can be
442 will refuse to fetch references from the remote repository's
451 .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
452 Copy files from a repository into a new work tree.
453 Show the status of each affected file, using the following status codes:
454 .Bl -column YXZ description
455 .It A Ta new file was added
456 .It E Ta file already exists in work tree's meta-data
461 is not specified, either use the last component of
462 .Ar repository path ,
465 was specified use the last component of
473 Proceed with the checkout operation even if the directory at
476 Existing files will be left intact.
478 Check out files from a commit on the specified
480 If this option is not specified, a branch resolved via the repository's HEAD
481 reference will be used.
483 Check out files from the specified
485 on the selected branch.
486 The expected argument is a commit ID SHA1 hash or an existing reference
487 or tag name which will be resolved to a commit ID.
488 An abbreviated hash argument will be expanded to a full SHA1 hash
489 automatically, provided the abbreviation is unique.
490 If this option is not specified, the most recent commit on the selected
495 is not contained in the selected branch, a different branch which contains
496 this commit must be specified with the
499 If no such branch is known a new branch must be created for this
505 Checking out work trees with an unknown branch is intentionally not supported.
506 .It Fl p Ar path-prefix
507 Restrict the work tree to a subset of the repository's tree hierarchy.
508 Only files beneath the specified
515 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
516 Update an existing work tree to a different
518 Change existing files in the work tree as necessary to match file contents
520 Preserve any local changes in the work tree and merge them with the
523 Show the status of each affected file, using the following status codes:
524 .Bl -column YXZ description
525 .It U Ta file was updated and contained no local changes
526 .It G Ta file was updated and local changes were merged cleanly
527 .It C Ta file was updated and conflicts occurred during merge
528 .It D Ta file was deleted
529 .It A Ta new file was added
530 .It \(a~ Ta versioned file is obstructed by a non-regular file
531 .It ! Ta a missing versioned file was restored
536 is specified, update the entire work tree.
537 Otherwise, restrict the update operation to files at or within the
539 Each path is required to exist in the update operation's target commit.
540 Files in the work tree outside specified paths will remain unchanged and
541 will retain their previously recorded base commit.
544 commands may refuse to run while the work tree contains files from
545 multiple base commits.
546 The base commit of such a work tree can be made consistent by running
548 across the entire work tree.
551 is incompatible with the
556 cannot update paths with staged changes.
557 If changes have been staged with
559 these changes must first be committed with
569 Switch the work tree's branch reference to the specified
571 before updating the work tree.
572 This option requires that all paths in the work tree are updated.
574 As usual, any local changes in the work tree will be preserved.
575 This can be useful when switching to a newly created branch in order
576 to commit existing local changes to this branch.
578 Any local changes must be dealt with separately in order to obtain a
579 work tree with pristine file contents corresponding exactly to the specified
581 Such changes could first be committed to a different branch with
583 or could be discarded with
586 Update the work tree to the specified
588 The expected argument is a commit ID SHA1 hash or an existing reference
589 or tag name which will be resolved to a commit ID.
590 An abbreviated hash argument will be expanded to a full SHA1 hash
591 automatically, provided the abbreviation is unique.
592 If this option is not specified, the most recent commit on the work tree's
598 .It Cm status Op Ar path ...
599 Show the current modification status of files in a work tree,
600 using the following status codes:
601 .Bl -column YXZ description
602 .It M Ta modified file
603 .It A Ta file scheduled for addition in next commit
604 .It D Ta file scheduled for deletion in next commit
605 .It C Ta modified or added file which contains merge conflicts
606 .It ! Ta versioned file was expected on disk but is missing
607 .It \(a~ Ta versioned file is obstructed by a non-regular file
608 .It ? Ta unversioned item not tracked by
610 .It m Ta modified file modes (executable bit only)
611 .It N Ta non-existent
613 specified on the command line
618 is specified, show modifications in the entire work tree.
619 Otherwise, show modifications at or within the specified paths.
621 If changes have been staged with
623 staged changes are shown in the second output column, using the following
625 .Bl -column YXZ description
626 .It M Ta file modification is staged
627 .It A Ta file addition is staged
628 .It D Ta file deletion is staged
631 Changes created on top of staged changes are indicated in the first column:
632 .Bl -column YXZ description
633 .It MM Ta file was modified after earlier changes have been staged
634 .It MA Ta file was modified after having been staged for addition
637 For compatibility with
648 files in each traversed directory and will not display unversioned files
649 which match these patterns.
654 supports consecutive asterisks,
656 which will match an arbitrary amount of directories.
660 only supports a single ignore pattern per line.
664 does not support negated ignore patterns prefixed with
666 and gives no special significance to the location of path component separators,
672 .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 Oo Fl x Ar commit Oc Op Ar path
673 Display history of a repository.
676 is specified, show only commits which modified this path.
677 If invoked in a work tree, the
679 is interpreted relative to the current working directory,
680 and the work tree's path prefix is implicitly prepended.
681 Otherwise, the path is interpreted relative to the repository root.
688 Display individual commits which were merged into the current branch
692 shows the linear history of the current branch only.
694 Start traversing history at the specified
696 The expected argument is a commit ID SHA1 hash or an existing reference
697 or tag name which will be resolved to a commit ID.
698 An abbreviated hash argument will be expanded to a full SHA1 hash
699 automatically, provided the abbreviation is unique.
700 If this option is not specified, default to the work tree's current branch
701 if invoked in a work tree, or to the repository's HEAD reference.
703 Set the number of context lines shown in diffs with
705 By default, 3 lines of context are shown.
707 Limit history traversal to a given number of commits.
708 If this option is not specified, a default limit value of zero is used,
709 which is treated as an unbounded limit.
711 .Ev GOT_LOG_DEFAULT_LIMIT
712 environment variable may be set to change this default value.
714 Display the patch of modifications made in each commit.
717 is specified, only show the patch of modifications at or within this path.
718 .It Fl s Ar search-pattern
719 If specified, show only commits with a log message matched by the extended
722 Regular expression syntax is documented in
724 .It Fl r Ar repository-path
725 Use the repository at the specified path.
726 If not specified, assume the repository is located at or above the current
728 If this directory is a
730 work tree, use the repository path associated with this work tree.
732 Stop displaying commits as soon as the specified
735 This option has no effect if the specified
739 .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
740 When invoked within a work tree with less than two arguments, display
741 uncommitted changes in the work tree.
744 is specified, only show changes within this path.
746 If two arguments are provided, treat each argument as a reference, a tag
747 name, or an object ID SHA1 hash, and display differences between the
748 corresponding objects.
749 Both objects must be of the same type (blobs, trees, or commits).
750 An abbreviated hash argument will be expanded to a full SHA1 hash
751 automatically, provided the abbreviation is unique.
758 Set the number of context lines shown in the diff.
759 By default, 3 lines of context are shown.
760 .It Fl r Ar repository-path
761 Use the repository at the specified path.
762 If not specified, assume the repository is located at or above the current
764 If this directory is a
766 work tree, use the repository path associated with this work tree.
768 Show changes staged with
770 instead of showing local changes.
771 This option is only valid when
773 is invoked in a work tree.
775 Ignore whitespace-only changes.
780 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
781 Display line-by-line history of a file at the specified path.
788 Start traversing history at the specified
790 The expected argument is a commit ID SHA1 hash or an existing reference
791 or tag name which will be resolved to a commit ID.
792 An abbreviated hash argument will be expanded to a full SHA1 hash
793 automatically, provided the abbreviation is unique.
794 .It Fl r Ar repository-path
795 Use the repository at the specified path.
796 If not specified, assume the repository is located at or above the current
798 If this directory is a
800 work tree, use the repository path associated with this work tree.
805 .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
806 Display a listing of files and directories at the specified
807 directory path in the repository.
808 Entries shown in this listing may carry one of the following trailing
810 .Bl -column YXZ description
811 .It @ Ta entry is a symbolic link
812 .It / Ta entry is a directory
813 .It * Ta entry is an executable file
814 .It $ Ta entry is a Git submodule
819 is specified, list the repository path corresponding to the current
820 directory of the work tree, or the root directory of the repository
821 if there is no work tree.
828 List files and directories as they appear in the specified
830 The expected argument is a commit ID SHA1 hash or an existing reference
831 or tag name which will be resolved to a commit ID.
832 An abbreviated hash argument will be expanded to a full SHA1 hash
833 automatically, provided the abbreviation is unique.
834 .It Fl r Ar repository-path
835 Use the repository at the specified path.
836 If not specified, assume the repository is located at or above the current
838 If this directory is a
840 work tree, use the repository path associated with this work tree.
842 Show object IDs of files (blob objects) and directories (tree objects).
844 Recurse into sub-directories in the repository.
849 .It Cm ref Oo Fl r Ar repository-path Oc Oo Fl l Oc Oo Fl c Ar object Oc Oo Fl s Ar reference Oc Oo Fl d Oc Op Ar name
850 Manage references in a repository.
852 References may be listed, created, deleted, and changed.
853 When creating, deleting, or changing a reference the specified
855 must be an absolute reference name, i.e. it must begin with
862 .It Fl r Ar repository-path
863 Use the repository at the specified path.
864 If not specified, assume the repository is located at or above the current
866 If this directory is a
868 work tree, use the repository path associated with this work tree.
870 List references in the repository.
873 is specified, list all existing references in the repository.
876 is a reference namespace, list all references in this namespace.
877 Otherwise, show only the reference with the given
879 Cannot be used together with any other options except
882 Create a reference or change an existing reference.
883 The reference with the specified
885 will point at the specified
889 argument is a ID SHA1 hash or an existing reference or tag name which will
890 be resolved to the ID of a corresponding commit, tree, tag, or blob object.
891 Cannot be used together with any other options except
893 .It Fl s Ar reference
894 Create a symbolic reference, or change an existing symbolic reference.
895 The symbolic reference with the specified
897 will point at the specified
899 which must already exist in the repository.
900 Care should be taken not to create loops between references when
902 Cannot be used together with any other options except
905 Delete the reference with the specified
908 Cannot be used together with any other options except
911 .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
912 Create, list, or delete branches.
914 Branches are managed via references which live in the
919 command operates on references in this namespace only.
921 If invoked in a work tree without any arguments, print the name of the
922 work tree's current branch.
926 argument is passed, attempt to create a branch reference with the given name.
927 By default the new branch reference will point at the latest commit on the
928 work tree's current branch if invoked in a work tree, and otherwise to a commit
929 resolved via the repository's HEAD reference.
931 If invoked in a work tree, once the branch was created successfully
932 switch the work tree's head reference to the newly created branch and
933 update files across the entire work tree, just like
934 .Cm got update -b Ar name
936 Show the status of each affected file, using the following status codes:
937 .Bl -column YXZ description
938 .It U Ta file was updated and contained no local changes
939 .It G Ta file was updated and local changes were merged cleanly
940 .It C Ta file was updated and conflicts occurred during merge
941 .It D Ta file was deleted
942 .It A Ta new file was added
943 .It \(a~ Ta versioned file is obstructed by a non-regular file
944 .It ! Ta a missing versioned file was restored
952 Make a newly created branch reference point at the specified
956 argument is a commit ID SHA1 hash or an existing reference
957 or tag name which will be resolved to a commit ID.
958 .It Fl r Ar repository-path
959 Use the repository at the specified path.
960 If not specified, assume the repository is located at or above the current
962 If this directory is a
964 work tree, use the repository path associated with this work tree.
966 List all existing branches in the repository.
967 If invoked in a work tree, the work tree's current branch is shown
968 with one the following annotations:
969 .Bl -column YXZ description
970 .It * Ta work tree's base commit matches the branch tip
971 .It \(a~ Ta work tree's base commit is out-of-date
974 Delete the branch with the specified name from the repository.
975 Only the branch reference is deleted.
976 Any commit, tree, and blob objects belonging to the branch
977 remain in the repository and may be removed separately with
978 Git's garbage collector.
980 Do not switch and update the work tree after creating a new branch.
985 .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
986 Manage tags in a repository.
988 Tags are managed via references which live in the
993 command operates on references in this namespace only.
994 References in this namespace point at tag objects which contain a pointer
995 to another object, a tag message, as well as author and timestamp information.
997 Attempt to create a tag with the given
999 and make this tag point at the given
1001 If no commit is specified, default to the latest commit on the work tree's
1002 current branch if invoked in a work tree, and to a commit resolved via
1003 the repository's HEAD reference otherwise.
1010 Make the newly created tag reference point at the specified
1014 argument is a commit ID SHA1 hash or an existing reference or tag name which
1015 will be resolved to a commit ID.
1016 An abbreviated hash argument will be expanded to a full SHA1 hash
1017 automatically, provided the abbreviation is unique.
1019 Use the specified tag message when creating the new tag.
1024 opens a temporary file in an editor where a tag message can be written.
1025 .It Fl r Ar repository-path
1026 Use the repository at the specified path.
1027 If not specified, assume the repository is located at or above the current
1029 If this directory is a
1031 work tree, use the repository path associated with this work tree.
1033 List all existing tags in the repository instead of creating a new tag.
1034 If this option is used, no other command-line arguments are allowed.
1039 command will not delete tags or change existing tags.
1040 If a tag must be deleted, the
1042 command may be used to delete a tag's reference.
1043 This should only be done if the tag has not already been copied to
1045 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
1046 Schedule unversioned files in a work tree for addition to the
1047 repository in the next commit.
1054 Permit recursion into directories.
1055 If this option is not specified,
1057 will refuse to run if a specified
1061 With -R, add files even if they match a
1065 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
1066 Remove versioned files from a work tree and schedule them for deletion
1067 from the repository in the next commit.
1074 Perform the operation even if a file contains uncommitted modifications.
1076 Keep affected files on disk.
1078 Permit recursion into directories.
1079 If this option is not specified,
1081 will refuse to run if a specified
1088 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
1089 Revert any uncommitted changes in files at the specified paths.
1090 File contents will be overwritten with those contained in the
1091 work tree's base commit.
1092 There is no way to bring discarded changes back after
1095 If a file was added with
1097 it will become an unversioned file again.
1098 If a file was deleted with
1100 it will be restored.
1107 Instead of reverting all changes in files, interactively select or reject
1108 changes to revert based on
1114 (quit reverting this file) responses.
1115 If a file is in modified status, individual patches derived from the
1116 modified file content can be reverted.
1117 Files in added or deleted status may only be reverted in their entirety.
1118 .It Fl F Ar response-script
1126 responses line-by-line from the specified
1128 file instead of prompting interactively.
1130 Permit recursion into directories.
1131 If this option is not specified,
1133 will refuse to run if a specified
1140 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1141 Create a new commit in the repository from changes in a work tree
1142 and use this commit as the new base commit for the work tree.
1145 is specified, commit all changes in the work tree.
1146 Otherwise, commit changes at or within the specified paths.
1148 If changes have been explicitly staged for commit with
1150 only commit staged changes and reject any specified paths which
1151 have not been staged.
1153 Show the status of each affected file, using the following status codes:
1154 .Bl -column YXZ description
1155 .It M Ta modified file
1156 .It D Ta file was deleted
1157 .It A Ta new file was added
1158 .It m Ta modified file modes (executable bit only)
1161 Files which are not part of the new commit will retain their previously
1162 recorded base commit.
1165 commands may refuse to run while the work tree contains files from
1166 multiple base commits.
1167 The base commit of such a work tree can be made consistent by running
1169 across the entire work tree.
1173 command requires the
1175 environment variable to be set,
1180 configuration settings can be
1181 obtained from the repository's
1183 file or from Git's global
1192 Use the specified log message when creating the new commit.
1197 opens a temporary file in an editor where a log message can be written.
1201 will refuse to run if certain preconditions are not met.
1202 If the work tree's current branch is not in the
1204 reference namespace, new commits may not be created on this branch.
1205 Local changes may only be committed if they are based on file content
1206 found in the most recent commit on the work tree's branch.
1207 If a path is found to be out of date,
1209 must be used first in order to merge local changes with changes made
1214 .It Cm cherrypick Ar commit
1215 Merge changes from a single
1220 must be on a different branch than the work tree's base commit.
1221 The expected argument is a reference or a commit ID SHA1 hash.
1222 An abbreviated hash argument will be expanded to a full SHA1 hash
1223 automatically, provided the abbreviation is unique.
1225 Show the status of each affected file, using the following status codes:
1226 .Bl -column YXZ description
1227 .It G Ta file was merged
1228 .It C Ta file was merged and conflicts occurred during merge
1229 .It ! Ta changes destined for a missing file were not merged
1230 .It D Ta file was deleted
1231 .It d Ta file's deletion was obstructed by local modifications
1232 .It A Ta new file was added
1233 .It \(a~ Ta changes destined for a non-regular file were not merged
1236 The merged changes will appear as local changes in the work tree, which
1239 amended manually or with further
1244 or discarded again with
1248 will refuse to run if certain preconditions are not met.
1249 If the work tree contains multiple base commits it must first be updated
1250 to a single base commit with
1252 If the work tree already contains files with merge conflicts, these
1253 conflicts must be resolved first.
1257 .It Cm backout Ar commit
1258 Reverse-merge changes from a single
1263 must be on the same branch as the work tree's base commit.
1264 The expected argument is a reference or a commit ID SHA1 hash.
1265 An abbreviated hash argument will be expanded to a full SHA1 hash
1266 automatically, provided the abbreviation is unique.
1268 Show the status of each affected file, using the following status codes:
1269 .Bl -column YXZ description
1270 .It G Ta file was merged
1271 .It C Ta file was merged and conflicts occurred during merge
1272 .It ! Ta changes destined for a missing file were not merged
1273 .It D Ta file was deleted
1274 .It d Ta file's deletion was obstructed by local modifications
1275 .It A Ta new file was added
1276 .It \(a~ Ta changes destined for a non-regular file were not merged
1279 The reverse-merged changes will appear as local changes in the work tree,
1280 which may be viewed with
1282 amended manually or with further
1287 or discarded again with
1291 will refuse to run if certain preconditions are not met.
1292 If the work tree contains multiple base commits it must first be updated
1293 to a single base commit with
1295 If the work tree already contains files with merge conflicts, these
1296 conflicts must be resolved first.
1300 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1301 Rebase commits on the specified
1303 onto the tip of the current branch of the work tree.
1306 must share common ancestry with the work tree's current branch.
1307 Rebasing begins with the first descendant commit of the youngest
1308 common ancestor commit shared by the specified
1310 and the work tree's current branch, and stops once the tip commit
1317 is used as intended, the specified
1319 represents a local commit history and may already contain changes
1320 that are not yet visible in any other repositories.
1321 The work tree's current branch, which must be set with
1325 operation, represents a branch from a remote repository which shares
1326 a common history with the specified
1328 but has progressed, and perhaps diverged, due to commits added to the
1331 Rebased commits are accumulated on a temporary branch which the work tree
1332 will remain switched to throughout the entire rebase operation.
1333 Commits on this branch represent the same changes with the same log
1334 messages as their counterparts on the original
1336 but with different commit IDs.
1337 Once rebasing has completed successfully, the temporary branch becomes
1338 the new version of the specified
1340 and the work tree is automatically switched to it.
1342 While rebasing commits, show the status of each affected file,
1343 using the following status codes:
1344 .Bl -column YXZ description
1345 .It G Ta file was merged
1346 .It C Ta file was merged and conflicts occurred during merge
1347 .It ! Ta changes destined for a missing file were not merged
1348 .It D Ta file was deleted
1349 .It d Ta file's deletion was obstructed by local modifications
1350 .It A Ta new file was added
1351 .It \(a~ Ta changes destined for a non-regular file were not merged
1354 If merge conflicts occur the rebase operation is interrupted and may
1355 be continued once conflicts have been resolved.
1356 Alternatively, the rebase operation may be aborted which will leave
1358 unmodified and the work tree switched back to its original branch.
1360 If a merge conflict is resolved in a way which renders the merged
1361 change into a no-op change, the corresponding commit will be elided
1362 when the rebase operation continues.
1365 will refuse to run if certain preconditions are not met.
1366 If the work tree is not yet fully updated to the tip commit of its
1367 branch then the work tree must first be updated with
1369 If changes have been staged with
1371 these changes must first be committed with
1375 If the work tree contains local changes, these changes must first be
1382 contains changes to files outside of the work tree's path prefix,
1383 the work tree cannot be used to rebase this branch.
1389 commands will refuse to run while a rebase operation is in progress.
1390 Other commands which manipulate the work tree may be used for
1391 conflict resolution purposes.
1398 Abort an interrupted rebase operation.
1399 If this option is used, no other command-line arguments are allowed.
1401 Continue an interrupted rebase operation.
1402 If this option is used, no other command-line arguments are allowed.
1407 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1408 Edit commit history between the work tree's current base commit and
1409 the tip commit of the work tree's current branch.
1413 operation the work tree's current branch must be set with
1415 to the branch which should be edited, unless this branch is already the
1416 current branch of the work tree.
1417 The tip of this branch represents the upper bound (inclusive) of commits
1422 Furthermore, the work tree's base commit
1425 to a point in this branch's commit history where editing should begin.
1426 This commit represents the lower bound (non-inclusive) of commits touched
1431 Editing of commit history is controlled via a
1433 which can be written in an editor based on a template, passed on the
1434 command line, or generated with the
1436 option if only log messages need to be edited.
1438 The format of the histedit script is line-based.
1439 Each line in the script begins with a command name, followed by
1440 whitespace and an argument.
1441 For most commands, the expected argument is a commit ID SHA1 hash.
1442 Any remaining text on the line is ignored.
1443 Lines which begin with the
1445 character are ignored entirely.
1447 The available commands are as follows:
1448 .Bl -column YXZ pick-commit
1449 .It pick Ar commit Ta Use the specified commit as it is.
1450 .It edit Ar commit Ta Use the specified commit but once changes have been
1451 merged into the work tree interrupt the histedit operation for amending.
1452 .It fold Ar commit Ta Combine the specified commit with the next commit
1453 listed further below that will be used.
1454 .It drop Ar commit Ta Remove this commit from the edited history.
1455 .It mesg Ar log-message Ta Use the specified single-line log message for
1456 the commit on the previous line.
1457 If the log message argument is left empty, open an editor where a new
1458 log message can be written.
1461 Every commit in the history being edited must be mentioned in the script.
1462 Lines may be re-ordered to change the order of commits in the edited history.
1463 No commit may be listed more than once.
1465 Edited commits are accumulated on a temporary branch which the work tree
1466 will remain switched to throughout the entire histedit operation.
1467 Once history editing has completed successfully, the temporary branch becomes
1468 the new version of the work tree's branch and the work tree is automatically
1471 While merging commits, show the status of each affected file,
1472 using the following status codes:
1473 .Bl -column YXZ description
1474 .It G Ta file was merged
1475 .It C Ta file was merged and conflicts occurred during merge
1476 .It ! Ta changes destined for a missing file were not merged
1477 .It D Ta file was deleted
1478 .It d Ta file's deletion was obstructed by local modifications
1479 .It A Ta new file was added
1480 .It \(a~ Ta changes destined for a non-regular file were not merged
1483 If merge conflicts occur the histedit operation is interrupted and may
1484 be continued once conflicts have been resolved.
1485 Alternatively, the histedit operation may be aborted which will leave
1486 the work tree switched back to its original branch.
1488 If a merge conflict is resolved in a way which renders the merged
1489 change into a no-op change, the corresponding commit will be elided
1490 when the histedit operation continues.
1493 will refuse to run if certain preconditions are not met.
1494 If the work tree's current branch is not in the
1496 reference namespace, the history of the branch may not be edited.
1497 If the work tree contains multiple base commits it must first be updated
1498 to a single base commit with
1500 If changes have been staged with
1502 these changes must first be committed with
1506 If the work tree contains local changes, these changes must first be
1511 If the edited history contains changes to files outside of the work tree's
1512 path prefix, the work tree cannot be used to edit the history of this branch.
1519 commands will refuse to run while a histedit operation is in progress.
1520 Other commands which manipulate the work tree may be used, and the
1522 command may be used to commit arbitrary changes to the temporary branch
1523 while the histedit operation is interrupted.
1530 Abort an interrupted histedit operation.
1531 If this option is used, no other command-line arguments are allowed.
1533 Continue an interrupted histedit operation.
1534 If this option is used, no other command-line arguments are allowed.
1535 .It Fl F Ar histedit-script
1538 instead of opening a temporary file in an editor where a histedit script
1541 Edit log messages only.
1542 This option is a quick equivalent to a histedit script which edits
1543 only log messages but otherwise leaves every picked commit as-is.
1546 option can only be used when starting a new histedit operation.
1547 If this option is used, no other command-line arguments are allowed.
1552 .It Cm integrate Ar branch
1553 Integrate the specified
1555 into the work tree's current branch.
1556 Files in the work tree are updated to match the contents on the integrated
1558 and the reference of the work tree's branch is changed to point at the
1559 head commit of the integrated
1562 Both branches can be considered equivalent after integration since they
1563 will be pointing at the same commit.
1564 Both branches remain available for future work, if desired.
1565 In case the integrated
1567 is no longer needed it may be deleted with
1570 Show the status of each affected file, using the following status codes:
1571 .Bl -column YXZ description
1572 .It U Ta file was updated
1573 .It D Ta file was deleted
1574 .It A Ta new file was added
1575 .It \(a~ Ta versioned file is obstructed by a non-regular file
1576 .It ! Ta a missing versioned file was restored
1580 will refuse to run if certain preconditions are not met.
1581 Most importantly, the
1583 must have been rebased onto the work tree's current branch with
1585 before it can be integrated, in order to linearize commit history and
1586 resolve merge conflicts.
1587 If the work tree contains multiple base commits it must first be updated
1588 to a single base commit with
1590 If changes have been staged with
1592 these changes must first be committed with
1596 If the work tree contains local changes, these changes must first be
1604 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1605 Stage local changes for inclusion in the next commit.
1608 is specified, stage all changes in the work tree.
1609 Otherwise, stage changes at or within the specified paths.
1610 Paths may be staged if they are added, modified, or deleted according to
1613 Show the status of each affected file, using the following status codes:
1614 .Bl -column YXZ description
1615 .It A Ta file addition has been staged
1616 .It M Ta file modification has been staged
1617 .It D Ta file deletion has been staged
1620 Staged file contents are saved in newly created blob objects in the repository.
1621 These blobs will be referred to by tree objects once staged changes have been
1624 Staged changes affect the behaviour of
1629 While paths with staged changes exist, the
1631 command will refuse to commit any paths which do not have staged changes.
1632 Local changes created on top of staged changes can only be committed if
1633 the path is staged again, or if the staged changes are committed first.
1636 command will show both local changes and staged changes.
1639 command is able to display local changes relative to staged changes,
1640 and to display staged changes relative to the repository.
1643 command cannot revert staged changes but may be used to revert
1644 local changes created on top of staged changes.
1651 Instead of staging new changes, list paths which are already staged,
1652 along with the IDs of staged blob objects and stage status codes.
1653 If paths were provided in the command line show the staged paths
1654 among the specified paths.
1655 Otherwise, show all staged paths.
1657 Instead of staging the entire content of a changed file, interactively
1658 select or reject changes for staging based on
1662 (reject change), and
1664 (quit staging this file) responses.
1665 If a file is in modified status, individual patches derived from the
1666 modified file content can be staged.
1667 Files in added or deleted status may only be staged or rejected in
1669 .It Fl F Ar response-script
1677 responses line-by-line from the specified
1679 file instead of prompting interactively.
1683 will refuse to run if certain preconditions are not met.
1684 If a file contains merge conflicts, these conflicts must be resolved first.
1685 If a file is found to be out of date relative to the head commit on the
1686 work tree's current branch, the file must be updated with
1688 before it can be staged (however, this does not prevent the file from
1689 becoming out-of-date at some point after having been staged).
1696 commands will refuse to run while staged changes exist.
1697 If staged changes cannot be committed because a staged path
1698 is out of date, the path must be unstaged with
1700 before it can be updated with
1702 and may then be staged again if necessary.
1706 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1707 Merge staged changes back into the work tree and put affected paths
1708 back into non-staged status.
1711 is specified, unstage all staged changes across the entire work tree.
1712 Otherwise, unstage changes at or within the specified paths.
1714 Show the status of each affected file, using the following status codes:
1715 .Bl -column YXZ description
1716 .It G Ta file was unstaged
1717 .It C Ta file was unstaged and conflicts occurred during merge
1718 .It ! Ta changes destined for a missing file were not merged
1719 .It D Ta file was staged as deleted and still is deleted
1720 .It d Ta file's deletion was obstructed by local modifications
1721 .It \(a~ Ta changes destined for a non-regular file were not merged
1729 Instead of unstaging the entire content of a changed file, interactively
1730 select or reject changes for unstaging based on
1734 (keep change staged), and
1736 (quit unstaging this file) responses.
1737 If a file is staged in modified status, individual patches derived from the
1738 staged file content can be unstaged.
1739 Files staged in added or deleted status may only be unstaged in their entirety.
1740 .It Fl F Ar response-script
1748 responses line-by-line from the specified
1750 file instead of prompting interactively.
1755 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1756 Parse and print contents of objects to standard output in a line-based
1758 Content of commit, tree, and tag objects is printed in a way similar
1759 to the actual content stored in such objects.
1760 Blob object contents are printed as they would appear in files on disk.
1762 Attempt to interpret each argument as a reference, a tag name, or
1763 an object ID SHA1 hash.
1764 References will be resolved to an object ID.
1765 Tag names will resolved to a tag object.
1766 An abbreviated hash argument will be expanded to a full SHA1 hash
1767 automatically, provided the abbreviation is unique.
1769 If none of the above interpretations produce a valid result, or if the
1771 option is used, attempt to interpret the argument as a path which will
1772 be resolved to the ID of an object found at this path in the repository.
1779 Look up paths in the specified
1781 If this option is not used, paths are looked up in the commit resolved
1782 via the repository's HEAD reference.
1783 The expected argument is a commit ID SHA1 hash or an existing reference
1784 or tag name which will be resolved to a commit ID.
1785 An abbreviated hash argument will be expanded to a full SHA1 hash
1786 automatically, provided the abbreviation is unique.
1787 .It Fl r Ar repository-path
1788 Use the repository at the specified path.
1789 If not specified, assume the repository is located at or above the current
1791 If this directory is a
1793 work tree, use the repository path associated with this work tree.
1795 Interpret all arguments as paths only.
1796 This option can be used to resolve ambiguity in cases where paths
1797 look like tag names, reference names, or object IDs.
1801 .Bl -tag -width GOT_AUTHOR
1803 The author's name and email address for
1808 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1811 may fail to parse commits without an email address in author data,
1815 environment variables with a missing email address.
1821 configuration settings in the repository's
1823 file will override the value of
1829 configuration settings contained in Git's global
1831 configuration file will be used only if the
1833 environment variable is
1836 .It Ev VISUAL , EDITOR
1837 The editor spawned by
1842 .It Ev GOT_LOG_DEFAULT_LIMIT
1843 The default limit on the number of commits traversed by
1845 If set to zero, the limit is unbounded.
1846 This variable will be silently ignored if it is set to a non-numeric value.
1851 Clone an existing Git repository for use with
1855 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1857 Use of HTTP URLs currently requires
1861 .Dl $ git clone --bare https://github.com/openbsd/src.git
1863 Alternatively, for quick and dirty local testing of
1865 a new Git repository could be created and populated with files,
1866 e.g. from a temporary CVS checkout located at
1869 .Dl $ got init /var/git/src.git
1870 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1872 Check out a work tree from the Git repository to /usr/src:
1874 .Dl $ got checkout /var/git/src.git /usr/src
1876 View local changes in a work tree directory:
1879 .Dl $ got diff | less
1881 Interactively revert selected local changes in a work tree directory:
1883 .Dl $ got revert -p -R\ .
1885 In a work tree or a git repository directory, list all branch references:
1889 In a work tree or a git repository directory, create a new branch called
1890 .Dq unified-buffer-cache
1891 which is forked off the
1895 .Dl $ got branch unified-buffer-cache master
1897 Switch an existing work tree to the branch
1898 .Dq unified-buffer-cache .
1899 Local changes in the work tree will be preserved and merged if necessary:
1901 .Dl $ got update -b unified-buffer-cache
1903 Create a new commit from local changes in a work tree directory.
1904 This new commit will become the head commit of the work tree's current branch:
1908 In a work tree or a git repository directory, view changes committed in
1909 the 3 most recent commits to the work tree's branch, or the branch resolved
1910 via the repository's HEAD reference, respectively:
1912 .Dl $ got log -p -l 3
1914 In a work tree or a git repository directory, log the history of a subdirectory:
1916 .Dl $ got log sys/uvm
1918 While operating inside a work tree, paths are specified relative to the current
1919 working directory, so this command will log the subdirectory
1922 .Dl $ cd sys/uvm && got log '.'
1924 And this command has the same effect:
1926 .Dl $ cd sys/dev/usb && got log ../../uvm
1928 Add new files and remove obsolete files in a work tree directory:
1930 .Dl $ got add sys/uvm/uvm_ubc.c
1931 .Dl $ got remove sys/uvm/uvm_vnode.c
1933 Create a new commit from local changes in a work tree directory
1934 with a pre-defined log message.
1936 .Dl $ got commit -m 'unify the buffer cache'
1938 Update any work tree checked out from the
1939 .Dq unified-buffer-cache
1940 branch to the latest commit on this branch:
1944 Roll file content on the unified-buffer-cache branch back by one commit,
1945 and then fetch the rolled-back change into the work tree as a local change
1946 to be amended and perhaps committed again:
1948 .Dl $ got backout unified-buffer-cache
1949 .Dl $ got commit -m 'roll back previous'
1950 .Dl $ # now back out the previous backout :-)
1951 .Dl $ got backout unified-buffer-cache
1953 Fetch new upstream commits into the local repository's
1960 In a repository created with a HTTP URL and
1961 .Cm git clone --bare
1964 command must be used instead:
1966 .Dl $ cd /var/git/src.git
1967 .Dl $ git fetch origin master:refs/remotes/origin/master
1971 branch to merge the new changes that are now visible on the
1976 .Dl $ got update -b origin/master
1977 .Dl $ got rebase master
1980 .Dq unified-buffer-cache
1981 branch on top of the new head commit of the
1985 .Dl $ got update -b master
1986 .Dl $ got rebase unified-buffer-cache
1988 Create a patch from all changes on the unified-buffer-cache branch.
1989 The patch can be mailed out for review and applied to
1993 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1995 Edit the entire commit history of the
1996 .Dq unified-buffer-cache
1999 .Dl $ got update -b unified-buffer-cache
2000 .Dl $ got update -c master
2003 In order to merge changes committed to the
2004 .Dq unified-buffer-cache
2005 branch back into the
2008 .Dq unified-buffer-cache
2009 branch must first be rebased onto the
2013 .Dl $ got update -b master
2014 .Dl $ got rebase unified-buffer-cache
2017 .Dq unified-buffer-cache
2018 branch can now be made visible on the
2022 Because the rebase operation switched the work tree to the
2023 .Dq unified-buffer-cache
2024 branch, the work tree must be switched back to the
2027 .Dq unified-buffer-cache
2028 branch can be integrated into
2031 .Dl $ got update -b master
2032 .Dl $ got integrate unified-buffer-cache
2034 Additional steps may be necessary if local changes need to be pushed back
2035 to the remote repository, which currently requires
2037 Before working against existing branches in a repository cloned with
2038 .Cm git clone --bare
2043 must be configured to map all references in the remote repository
2046 namespace of the local repository.
2047 This can achieved by setting Git's
2048 .Pa remote.origin.fetch
2049 configuration variable to the value
2050 .Dq +refs/heads/*:refs/remotes/origin/*
2055 .Dl $ cd /var/git/repo
2056 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
2060 option must be disabled:
2062 .Dl $ cd /var/git/repo
2063 .Dl $ git config remote.origin.mirror false
2065 Alternatively, the following
2067 configuration item can be added manually to the Git repository's
2071 .Dl [remote "origin"]
2073 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2076 This configuration leaves the local repository's
2078 namespace free for use by local branches checked out with
2080 and, if needed, created with
2085 namespace can now be updated with incoming changes from the remote
2090 without extra command line arguments:
2092 .Dl $ cd /var/git/repo
2095 To make changes fetched from the remote repository appear on the
2099 branch must be rebased onto the
2102 This will also merge local changes, if any, with the incoming changes:
2104 .Dl $ got update -b origin/master
2105 .Dl $ got rebase master
2109 branch, log messages for local changes can now be amended with
2111 by other developers and any other important new information:
2113 .Dl $ got update -c origin/master
2114 .Dl $ got histedit -m
2116 Local changes on the
2118 branch can then be pushed to the remote
2122 .Dl $ cd /var/git/repo
2123 .Dl $ git push origin master
2126 .Xr git-repository 5 ,
2129 .An Stefan Sperling Aq Mt stsp@openbsd.org
2130 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2131 .An Joshua Stein Aq Mt jcs@openbsd.org
2132 .An Ori Bernstein Aq Mt ori@openbsd.org
2135 is a work-in-progress and many commands remain to be implemented.
2136 At present, the user has to fall back on
2138 to perform many tasks, in particular tasks related to repository
2139 administration and tasks which require a network connection.
