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 Files which already contain merge conflicts will not be updated to avoid
524 further complications.
525 Such files will be updated when
527 is run again after merge conflicts have been resolved.
528 If the conflicting changes are no longer needed affected files can be
535 Show the status of each affected file, using the following status codes:
536 .Bl -column YXZ description
537 .It U Ta file was updated and contained no local changes
538 .It G Ta file was updated and local changes were merged cleanly
539 .It C Ta file was updated and conflicts occurred during merge
540 .It D Ta file was deleted
541 .It A Ta new file was added
542 .It \(a~ Ta versioned file is obstructed by a non-regular file
543 .It ! Ta a missing versioned file was restored
544 .It # Ta file was not updated because it contains merge conflicts
549 is specified, update the entire work tree.
550 Otherwise, restrict the update operation to files at or within the
552 Each path is required to exist in the update operation's target commit.
553 Files in the work tree outside specified paths will remain unchanged and
554 will retain their previously recorded base commit.
557 commands may refuse to run while the work tree contains files from
558 multiple base commits.
559 The base commit of such a work tree can be made consistent by running
561 across the entire work tree.
564 is incompatible with the
569 cannot update paths with staged changes.
570 If changes have been staged with
572 these changes must first be committed with
582 Switch the work tree's branch reference to the specified
584 before updating the work tree.
585 This option requires that all paths in the work tree are updated.
587 As usual, any local changes in the work tree will be preserved.
588 This can be useful when switching to a newly created branch in order
589 to commit existing local changes to this branch.
591 Any local changes must be dealt with separately in order to obtain a
592 work tree with pristine file contents corresponding exactly to the specified
594 Such changes could first be committed to a different branch with
596 or could be discarded with
599 Update the work tree to the specified
601 The expected argument is a commit ID SHA1 hash or an existing reference
602 or tag name which will be resolved to a commit ID.
603 An abbreviated hash argument will be expanded to a full SHA1 hash
604 automatically, provided the abbreviation is unique.
605 If this option is not specified, the most recent commit on the work tree's
611 .It Cm status Op Ar path ...
612 Show the current modification status of files in a work tree,
613 using the following status codes:
614 .Bl -column YXZ description
615 .It M Ta modified file
616 .It A Ta file scheduled for addition in next commit
617 .It D Ta file scheduled for deletion in next commit
618 .It C Ta modified or added file which contains merge conflicts
619 .It ! Ta versioned file was expected on disk but is missing
620 .It \(a~ Ta versioned file is obstructed by a non-regular file
621 .It ? Ta unversioned item not tracked by
623 .It m Ta modified file modes (executable bit only)
624 .It N Ta non-existent
626 specified on the command line
631 is specified, show modifications in the entire work tree.
632 Otherwise, show modifications at or within the specified paths.
634 If changes have been staged with
636 staged changes are shown in the second output column, using the following
638 .Bl -column YXZ description
639 .It M Ta file modification is staged
640 .It A Ta file addition is staged
641 .It D Ta file deletion is staged
644 Changes created on top of staged changes are indicated in the first column:
645 .Bl -column YXZ description
646 .It MM Ta file was modified after earlier changes have been staged
647 .It MA Ta file was modified after having been staged for addition
650 For compatibility with
661 files in each traversed directory and will not display unversioned files
662 which match these patterns.
667 supports consecutive asterisks,
669 which will match an arbitrary amount of directories.
673 only supports a single ignore pattern per line.
677 does not support negated ignore patterns prefixed with
679 and gives no special significance to the location of path component separators,
685 .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 R Oc Oo Fl x Ar commit Oc Op Ar path
686 Display history of a repository.
689 is specified, show only commits which modified this path.
690 If invoked in a work tree, the
692 is interpreted relative to the current working directory,
693 and the work tree's path prefix is implicitly prepended.
694 Otherwise, the path is interpreted relative to the repository root.
701 Display individual commits which were merged into the current branch
705 shows the linear history of the current branch only.
707 Start traversing history at the specified
709 The expected argument is a commit ID SHA1 hash or an existing reference
710 or tag name which will be resolved to a commit ID.
711 An abbreviated hash argument will be expanded to a full SHA1 hash
712 automatically, provided the abbreviation is unique.
713 If this option is not specified, default to the work tree's current branch
714 if invoked in a work tree, or to the repository's HEAD reference.
716 Set the number of context lines shown in diffs with
718 By default, 3 lines of context are shown.
720 Limit history traversal to a given number of commits.
721 If this option is not specified, a default limit value of zero is used,
722 which is treated as an unbounded limit.
724 .Ev GOT_LOG_DEFAULT_LIMIT
725 environment variable may be set to change this default value.
727 Display the patch of modifications made in each commit.
730 is specified, only show the patch of modifications at or within this path.
731 .It Fl s Ar search-pattern
732 If specified, show only commits with a log message matched by the extended
735 Regular expression syntax is documented in
737 .It Fl r Ar repository-path
738 Use the repository at the specified path.
739 If not specified, assume the repository is located at or above the current
741 If this directory is a
743 work tree, use the repository path associated with this work tree.
745 Determine a set of commits to display as usual, but display these commits
748 Stop traversing commit history as soon as the specified
751 This option has no effect if the specified
755 .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
756 When invoked within a work tree with less than two arguments, display
757 uncommitted changes in the work tree.
760 is specified, only show changes within this path.
762 If two arguments are provided, treat each argument as a reference, a tag
763 name, or an object ID SHA1 hash, and display differences between the
764 corresponding objects.
765 Both objects must be of the same type (blobs, trees, or commits).
766 An abbreviated hash argument will be expanded to a full SHA1 hash
767 automatically, provided the abbreviation is unique.
774 Set the number of context lines shown in the diff.
775 By default, 3 lines of context are shown.
776 .It Fl r Ar repository-path
777 Use the repository at the specified path.
778 If not specified, assume the repository is located at or above the current
780 If this directory is a
782 work tree, use the repository path associated with this work tree.
784 Show changes staged with
786 instead of showing local changes.
787 This option is only valid when
789 is invoked in a work tree.
791 Ignore whitespace-only changes.
796 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
797 Display line-by-line history of a file at the specified path.
804 Start traversing history at the specified
806 The expected argument is a commit ID SHA1 hash or an existing reference
807 or tag name which will be resolved to a commit ID.
808 An abbreviated hash argument will be expanded to a full SHA1 hash
809 automatically, provided the abbreviation is unique.
810 .It Fl r Ar repository-path
811 Use the repository at the specified path.
812 If not specified, assume the repository is located at or above the current
814 If this directory is a
816 work tree, use the repository path associated with this work tree.
821 .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
822 Display a listing of files and directories at the specified
823 directory path in the repository.
824 Entries shown in this listing may carry one of the following trailing
826 .Bl -column YXZ description
827 .It @ Ta entry is a symbolic link
828 .It / Ta entry is a directory
829 .It * Ta entry is an executable file
830 .It $ Ta entry is a Git submodule
835 is specified, list the repository path corresponding to the current
836 directory of the work tree, or the root directory of the repository
837 if there is no work tree.
844 List files and directories as they appear in the specified
846 The expected argument is a commit ID SHA1 hash or an existing reference
847 or tag name which will be resolved to a commit ID.
848 An abbreviated hash argument will be expanded to a full SHA1 hash
849 automatically, provided the abbreviation is unique.
850 .It Fl r Ar repository-path
851 Use the repository at the specified path.
852 If not specified, assume the repository is located at or above the current
854 If this directory is a
856 work tree, use the repository path associated with this work tree.
858 Show object IDs of files (blob objects) and directories (tree objects).
860 Recurse into sub-directories in the repository.
865 .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
866 Manage references in a repository.
868 References may be listed, created, deleted, and changed.
869 When creating, deleting, or changing a reference the specified
871 must be an absolute reference name, i.e. it must begin with
878 .It Fl r Ar repository-path
879 Use the repository at the specified path.
880 If not specified, assume the repository is located at or above the current
882 If this directory is a
884 work tree, use the repository path associated with this work tree.
886 List references in the repository.
889 is specified, list all existing references in the repository.
892 is a reference namespace, list all references in this namespace.
893 Otherwise, show only the reference with the given
895 Cannot be used together with any other options except
898 Create a reference or change an existing reference.
899 The reference with the specified
901 will point at the specified
905 argument is a ID SHA1 hash or an existing reference or tag name which will
906 be resolved to the ID of a corresponding commit, tree, tag, or blob object.
907 Cannot be used together with any other options except
909 .It Fl s Ar reference
910 Create a symbolic reference, or change an existing symbolic reference.
911 The symbolic reference with the specified
913 will point at the specified
915 which must already exist in the repository.
916 Care should be taken not to create loops between references when
918 Cannot be used together with any other options except
921 Delete the reference with the specified
924 Cannot be used together with any other options except
927 .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
928 Create, list, or delete branches.
930 Branches are managed via references which live in the
935 command operates on references in this namespace only.
937 If invoked in a work tree without any arguments, print the name of the
938 work tree's current branch.
942 argument is passed, attempt to create a branch reference with the given name.
943 By default the new branch reference will point at the latest commit on the
944 work tree's current branch if invoked in a work tree, and otherwise to a commit
945 resolved via the repository's HEAD reference.
947 If invoked in a work tree, once the branch was created successfully
948 switch the work tree's head reference to the newly created branch and
949 update files across the entire work tree, just like
950 .Cm got update -b Ar name
952 Show the status of each affected file, using the following status codes:
953 .Bl -column YXZ description
954 .It U Ta file was updated and contained no local changes
955 .It G Ta file was updated and local changes were merged cleanly
956 .It C Ta file was updated and conflicts occurred during merge
957 .It D Ta file was deleted
958 .It A Ta new file was added
959 .It \(a~ Ta versioned file is obstructed by a non-regular file
960 .It ! Ta a missing versioned file was restored
968 Make a newly created branch reference point at the specified
972 argument is a commit ID SHA1 hash or an existing reference
973 or tag name which will be resolved to a commit ID.
974 .It Fl r Ar repository-path
975 Use the repository at the specified path.
976 If not specified, assume the repository is located at or above the current
978 If this directory is a
980 work tree, use the repository path associated with this work tree.
982 List all existing branches in the repository.
983 If invoked in a work tree, the work tree's current branch is shown
984 with one the following annotations:
985 .Bl -column YXZ description
986 .It * Ta work tree's base commit matches the branch tip
987 .It \(a~ Ta work tree's base commit is out-of-date
990 Delete the branch with the specified name from the repository.
991 Only the branch reference is deleted.
992 Any commit, tree, and blob objects belonging to the branch
993 remain in the repository and may be removed separately with
994 Git's garbage collector.
996 Do not switch and update the work tree after creating a new branch.
1001 .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
1002 Manage tags in a repository.
1004 Tags are managed via references which live in the
1006 reference namespace.
1009 command operates on references in this namespace only.
1010 References in this namespace point at tag objects which contain a pointer
1011 to another object, a tag message, as well as author and timestamp information.
1013 Attempt to create a tag with the given
1015 and make this tag point at the given
1017 If no commit is specified, default to the latest commit on the work tree's
1018 current branch if invoked in a work tree, and to a commit resolved via
1019 the repository's HEAD reference otherwise.
1026 Make the newly created tag reference point at the specified
1030 argument is a commit ID SHA1 hash or an existing reference or tag name which
1031 will be resolved to a commit ID.
1032 An abbreviated hash argument will be expanded to a full SHA1 hash
1033 automatically, provided the abbreviation is unique.
1035 Use the specified tag message when creating the new tag.
1040 opens a temporary file in an editor where a tag message can be written.
1041 .It Fl r Ar repository-path
1042 Use the repository at the specified path.
1043 If not specified, assume the repository is located at or above the current
1045 If this directory is a
1047 work tree, use the repository path associated with this work tree.
1049 List all existing tags in the repository instead of creating a new tag.
1050 If this option is used, no other command-line arguments are allowed.
1055 command will not delete tags or change existing tags.
1056 If a tag must be deleted, the
1058 command may be used to delete a tag's reference.
1059 This should only be done if the tag has not already been copied to
1061 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
1062 Schedule unversioned files in a work tree for addition to the
1063 repository in the next commit.
1070 Permit recursion into directories.
1071 If this option is not specified,
1073 will refuse to run if a specified
1077 With -R, add files even if they match a
1081 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
1082 Remove versioned files from a work tree and schedule them for deletion
1083 from the repository in the next commit.
1090 Perform the operation even if a file contains uncommitted modifications.
1092 Keep affected files on disk.
1094 Permit recursion into directories.
1095 If this option is not specified,
1097 will refuse to run if a specified
1104 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
1105 Revert any uncommitted changes in files at the specified paths.
1106 File contents will be overwritten with those contained in the
1107 work tree's base commit.
1108 There is no way to bring discarded changes back after
1111 If a file was added with
1113 it will become an unversioned file again.
1114 If a file was deleted with
1116 it will be restored.
1123 Instead of reverting all changes in files, interactively select or reject
1124 changes to revert based on
1130 (quit reverting this file) responses.
1131 If a file is in modified status, individual patches derived from the
1132 modified file content can be reverted.
1133 Files in added or deleted status may only be reverted in their entirety.
1134 .It Fl F Ar response-script
1142 responses line-by-line from the specified
1144 file instead of prompting interactively.
1146 Permit recursion into directories.
1147 If this option is not specified,
1149 will refuse to run if a specified
1156 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1157 Create a new commit in the repository from changes in a work tree
1158 and use this commit as the new base commit for the work tree.
1161 is specified, commit all changes in the work tree.
1162 Otherwise, commit changes at or within the specified paths.
1164 If changes have been explicitly staged for commit with
1166 only commit staged changes and reject any specified paths which
1167 have not been staged.
1169 Show the status of each affected file, using the following status codes:
1170 .Bl -column YXZ description
1171 .It M Ta modified file
1172 .It D Ta file was deleted
1173 .It A Ta new file was added
1174 .It m Ta modified file modes (executable bit only)
1177 Files which are not part of the new commit will retain their previously
1178 recorded base commit.
1181 commands may refuse to run while the work tree contains files from
1182 multiple base commits.
1183 The base commit of such a work tree can be made consistent by running
1185 across the entire work tree.
1189 command requires the
1191 environment variable to be set,
1196 configuration settings can be
1197 obtained from the repository's
1199 file or from Git's global
1208 Use the specified log message when creating the new commit.
1213 opens a temporary file in an editor where a log message can be written.
1217 will refuse to run if certain preconditions are not met.
1218 If the work tree's current branch is not in the
1220 reference namespace, new commits may not be created on this branch.
1221 Local changes may only be committed if they are based on file content
1222 found in the most recent commit on the work tree's branch.
1223 If a path is found to be out of date,
1225 must be used first in order to merge local changes with changes made
1230 .It Cm cherrypick Ar commit
1231 Merge changes from a single
1236 must be on a different branch than the work tree's base commit.
1237 The expected argument is a reference or a commit ID SHA1 hash.
1238 An abbreviated hash argument will be expanded to a full SHA1 hash
1239 automatically, provided the abbreviation is unique.
1241 Show the status of each affected file, using the following status codes:
1242 .Bl -column YXZ description
1243 .It G Ta file was merged
1244 .It C Ta file was merged and conflicts occurred during merge
1245 .It ! Ta changes destined for a missing file were not merged
1246 .It D Ta file was deleted
1247 .It d Ta file's deletion was obstructed by local modifications
1248 .It A Ta new file was added
1249 .It \(a~ Ta changes destined for a non-regular file were not merged
1252 The merged changes will appear as local changes in the work tree, which
1255 amended manually or with further
1260 or discarded again with
1264 will refuse to run if certain preconditions are not met.
1265 If the work tree contains multiple base commits it must first be updated
1266 to a single base commit with
1268 If the work tree already contains files with merge conflicts, these
1269 conflicts must be resolved first.
1273 .It Cm backout Ar commit
1274 Reverse-merge changes from a single
1279 must be on the same branch as the work tree's base commit.
1280 The expected argument is a reference or a commit ID SHA1 hash.
1281 An abbreviated hash argument will be expanded to a full SHA1 hash
1282 automatically, provided the abbreviation is unique.
1284 Show the status of each affected file, using the following status codes:
1285 .Bl -column YXZ description
1286 .It G Ta file was merged
1287 .It C Ta file was merged and conflicts occurred during merge
1288 .It ! Ta changes destined for a missing file were not merged
1289 .It D Ta file was deleted
1290 .It d Ta file's deletion was obstructed by local modifications
1291 .It A Ta new file was added
1292 .It \(a~ Ta changes destined for a non-regular file were not merged
1295 The reverse-merged changes will appear as local changes in the work tree,
1296 which may be viewed with
1298 amended manually or with further
1303 or discarded again with
1307 will refuse to run if certain preconditions are not met.
1308 If the work tree contains multiple base commits it must first be updated
1309 to a single base commit with
1311 If the work tree already contains files with merge conflicts, these
1312 conflicts must be resolved first.
1316 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1317 Rebase commits on the specified
1319 onto the tip of the current branch of the work tree.
1322 must share common ancestry with the work tree's current branch.
1323 Rebasing begins with the first descendant commit of the youngest
1324 common ancestor commit shared by the specified
1326 and the work tree's current branch, and stops once the tip commit
1333 is used as intended, the specified
1335 represents a local commit history and may already contain changes
1336 that are not yet visible in any other repositories.
1337 The work tree's current branch, which must be set with
1341 operation, represents a branch from a remote repository which shares
1342 a common history with the specified
1344 but has progressed, and perhaps diverged, due to commits added to the
1347 Rebased commits are accumulated on a temporary branch which the work tree
1348 will remain switched to throughout the entire rebase operation.
1349 Commits on this branch represent the same changes with the same log
1350 messages as their counterparts on the original
1352 but with different commit IDs.
1353 Once rebasing has completed successfully, the temporary branch becomes
1354 the new version of the specified
1356 and the work tree is automatically switched to it.
1358 While rebasing commits, show the status of each affected file,
1359 using the following status codes:
1360 .Bl -column YXZ description
1361 .It G Ta file was merged
1362 .It C Ta file was merged and conflicts occurred during merge
1363 .It ! Ta changes destined for a missing file were not merged
1364 .It D Ta file was deleted
1365 .It d Ta file's deletion was obstructed by local modifications
1366 .It A Ta new file was added
1367 .It \(a~ Ta changes destined for a non-regular file were not merged
1370 If merge conflicts occur the rebase operation is interrupted and may
1371 be continued once conflicts have been resolved.
1372 Alternatively, the rebase operation may be aborted which will leave
1374 unmodified and the work tree switched back to its original branch.
1376 If a merge conflict is resolved in a way which renders the merged
1377 change into a no-op change, the corresponding commit will be elided
1378 when the rebase operation continues.
1381 will refuse to run if certain preconditions are not met.
1382 If the work tree is not yet fully updated to the tip commit of its
1383 branch then the work tree must first be updated with
1385 If changes have been staged with
1387 these changes must first be committed with
1391 If the work tree contains local changes, these changes must first be
1398 contains changes to files outside of the work tree's path prefix,
1399 the work tree cannot be used to rebase this branch.
1405 commands will refuse to run while a rebase operation is in progress.
1406 Other commands which manipulate the work tree may be used for
1407 conflict resolution purposes.
1414 Abort an interrupted rebase operation.
1415 If this option is used, no other command-line arguments are allowed.
1417 Continue an interrupted rebase operation.
1418 If this option is used, no other command-line arguments are allowed.
1423 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1424 Edit commit history between the work tree's current base commit and
1425 the tip commit of the work tree's current branch.
1429 operation the work tree's current branch must be set with
1431 to the branch which should be edited, unless this branch is already the
1432 current branch of the work tree.
1433 The tip of this branch represents the upper bound (inclusive) of commits
1438 Furthermore, the work tree's base commit
1441 to a point in this branch's commit history where editing should begin.
1442 This commit represents the lower bound (non-inclusive) of commits touched
1447 Editing of commit history is controlled via a
1449 which can be written in an editor based on a template, passed on the
1450 command line, or generated with the
1452 option if only log messages need to be edited.
1454 The format of the histedit script is line-based.
1455 Each line in the script begins with a command name, followed by
1456 whitespace and an argument.
1457 For most commands, the expected argument is a commit ID SHA1 hash.
1458 Any remaining text on the line is ignored.
1459 Lines which begin with the
1461 character are ignored entirely.
1463 The available commands are as follows:
1464 .Bl -column YXZ pick-commit
1465 .It pick Ar commit Ta Use the specified commit as it is.
1466 .It edit Ar commit Ta Use the specified commit but once changes have been
1467 merged into the work tree interrupt the histedit operation for amending.
1468 .It fold Ar commit Ta Combine the specified commit with the next commit
1469 listed further below that will be used.
1470 .It drop Ar commit Ta Remove this commit from the edited history.
1471 .It mesg Ar log-message Ta Use the specified single-line log message for
1472 the commit on the previous line.
1473 If the log message argument is left empty, open an editor where a new
1474 log message can be written.
1477 Every commit in the history being edited must be mentioned in the script.
1478 Lines may be re-ordered to change the order of commits in the edited history.
1479 No commit may be listed more than once.
1481 Edited commits are accumulated on a temporary branch which the work tree
1482 will remain switched to throughout the entire histedit operation.
1483 Once history editing has completed successfully, the temporary branch becomes
1484 the new version of the work tree's branch and the work tree is automatically
1487 While merging commits, show the status of each affected file,
1488 using the following status codes:
1489 .Bl -column YXZ description
1490 .It G Ta file was merged
1491 .It C Ta file was merged and conflicts occurred during merge
1492 .It ! Ta changes destined for a missing file were not merged
1493 .It D Ta file was deleted
1494 .It d Ta file's deletion was obstructed by local modifications
1495 .It A Ta new file was added
1496 .It \(a~ Ta changes destined for a non-regular file were not merged
1499 If merge conflicts occur the histedit operation is interrupted and may
1500 be continued once conflicts have been resolved.
1501 Alternatively, the histedit operation may be aborted which will leave
1502 the work tree switched back to its original branch.
1504 If a merge conflict is resolved in a way which renders the merged
1505 change into a no-op change, the corresponding commit will be elided
1506 when the histedit operation continues.
1509 will refuse to run if certain preconditions are not met.
1510 If the work tree's current branch is not in the
1512 reference namespace, the history of the branch may not be edited.
1513 If the work tree contains multiple base commits it must first be updated
1514 to a single base commit with
1516 If changes have been staged with
1518 these changes must first be committed with
1522 If the work tree contains local changes, these changes must first be
1527 If the edited history contains changes to files outside of the work tree's
1528 path prefix, the work tree cannot be used to edit the history of this branch.
1535 commands will refuse to run while a histedit operation is in progress.
1536 Other commands which manipulate the work tree may be used, and the
1538 command may be used to commit arbitrary changes to the temporary branch
1539 while the histedit operation is interrupted.
1546 Abort an interrupted histedit operation.
1547 If this option is used, no other command-line arguments are allowed.
1549 Continue an interrupted histedit operation.
1550 If this option is used, no other command-line arguments are allowed.
1551 .It Fl F Ar histedit-script
1554 instead of opening a temporary file in an editor where a histedit script
1557 Edit log messages only.
1558 This option is a quick equivalent to a histedit script which edits
1559 only log messages but otherwise leaves every picked commit as-is.
1562 option can only be used when starting a new histedit operation.
1563 If this option is used, no other command-line arguments are allowed.
1568 .It Cm integrate Ar branch
1569 Integrate the specified
1571 into the work tree's current branch.
1572 Files in the work tree are updated to match the contents on the integrated
1574 and the reference of the work tree's branch is changed to point at the
1575 head commit of the integrated
1578 Both branches can be considered equivalent after integration since they
1579 will be pointing at the same commit.
1580 Both branches remain available for future work, if desired.
1581 In case the integrated
1583 is no longer needed it may be deleted with
1586 Show the status of each affected file, using the following status codes:
1587 .Bl -column YXZ description
1588 .It U Ta file was updated
1589 .It D Ta file was deleted
1590 .It A Ta new file was added
1591 .It \(a~ Ta versioned file is obstructed by a non-regular file
1592 .It ! Ta a missing versioned file was restored
1596 will refuse to run if certain preconditions are not met.
1597 Most importantly, the
1599 must have been rebased onto the work tree's current branch with
1601 before it can be integrated, in order to linearize commit history and
1602 resolve merge conflicts.
1603 If the work tree contains multiple base commits it must first be updated
1604 to a single base commit with
1606 If changes have been staged with
1608 these changes must first be committed with
1612 If the work tree contains local changes, these changes must first be
1620 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1621 Stage local changes for inclusion in the next commit.
1624 is specified, stage all changes in the work tree.
1625 Otherwise, stage changes at or within the specified paths.
1626 Paths may be staged if they are added, modified, or deleted according to
1629 Show the status of each affected file, using the following status codes:
1630 .Bl -column YXZ description
1631 .It A Ta file addition has been staged
1632 .It M Ta file modification has been staged
1633 .It D Ta file deletion has been staged
1636 Staged file contents are saved in newly created blob objects in the repository.
1637 These blobs will be referred to by tree objects once staged changes have been
1640 Staged changes affect the behaviour of
1645 While paths with staged changes exist, the
1647 command will refuse to commit any paths which do not have staged changes.
1648 Local changes created on top of staged changes can only be committed if
1649 the path is staged again, or if the staged changes are committed first.
1652 command will show both local changes and staged changes.
1655 command is able to display local changes relative to staged changes,
1656 and to display staged changes relative to the repository.
1659 command cannot revert staged changes but may be used to revert
1660 local changes created on top of staged changes.
1667 Instead of staging new changes, list paths which are already staged,
1668 along with the IDs of staged blob objects and stage status codes.
1669 If paths were provided in the command line show the staged paths
1670 among the specified paths.
1671 Otherwise, show all staged paths.
1673 Instead of staging the entire content of a changed file, interactively
1674 select or reject changes for staging based on
1678 (reject change), and
1680 (quit staging this file) responses.
1681 If a file is in modified status, individual patches derived from the
1682 modified file content can be staged.
1683 Files in added or deleted status may only be staged or rejected in
1685 .It Fl F Ar response-script
1693 responses line-by-line from the specified
1695 file instead of prompting interactively.
1699 will refuse to run if certain preconditions are not met.
1700 If a file contains merge conflicts, these conflicts must be resolved first.
1701 If a file is found to be out of date relative to the head commit on the
1702 work tree's current branch, the file must be updated with
1704 before it can be staged (however, this does not prevent the file from
1705 becoming out-of-date at some point after having been staged).
1712 commands will refuse to run while staged changes exist.
1713 If staged changes cannot be committed because a staged path
1714 is out of date, the path must be unstaged with
1716 before it can be updated with
1718 and may then be staged again if necessary.
1722 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1723 Merge staged changes back into the work tree and put affected paths
1724 back into non-staged status.
1727 is specified, unstage all staged changes across the entire work tree.
1728 Otherwise, unstage changes at or within the specified paths.
1730 Show the status of each affected file, using the following status codes:
1731 .Bl -column YXZ description
1732 .It G Ta file was unstaged
1733 .It C Ta file was unstaged and conflicts occurred during merge
1734 .It ! Ta changes destined for a missing file were not merged
1735 .It D Ta file was staged as deleted and still is deleted
1736 .It d Ta file's deletion was obstructed by local modifications
1737 .It \(a~ Ta changes destined for a non-regular file were not merged
1745 Instead of unstaging the entire content of a changed file, interactively
1746 select or reject changes for unstaging based on
1750 (keep change staged), and
1752 (quit unstaging this file) responses.
1753 If a file is staged in modified status, individual patches derived from the
1754 staged file content can be unstaged.
1755 Files staged in added or deleted status may only be unstaged in their entirety.
1756 .It Fl F Ar response-script
1764 responses line-by-line from the specified
1766 file instead of prompting interactively.
1771 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1772 Parse and print contents of objects to standard output in a line-based
1774 Content of commit, tree, and tag objects is printed in a way similar
1775 to the actual content stored in such objects.
1776 Blob object contents are printed as they would appear in files on disk.
1778 Attempt to interpret each argument as a reference, a tag name, or
1779 an object ID SHA1 hash.
1780 References will be resolved to an object ID.
1781 Tag names will resolved to a tag object.
1782 An abbreviated hash argument will be expanded to a full SHA1 hash
1783 automatically, provided the abbreviation is unique.
1785 If none of the above interpretations produce a valid result, or if the
1787 option is used, attempt to interpret the argument as a path which will
1788 be resolved to the ID of an object found at this path in the repository.
1795 Look up paths in the specified
1797 If this option is not used, paths are looked up in the commit resolved
1798 via the repository's HEAD reference.
1799 The expected argument is a commit ID SHA1 hash or an existing reference
1800 or tag name which will be resolved to a commit ID.
1801 An abbreviated hash argument will be expanded to a full SHA1 hash
1802 automatically, provided the abbreviation is unique.
1803 .It Fl r Ar repository-path
1804 Use the repository at the specified path.
1805 If not specified, assume the repository is located at or above the current
1807 If this directory is a
1809 work tree, use the repository path associated with this work tree.
1811 Interpret all arguments as paths only.
1812 This option can be used to resolve ambiguity in cases where paths
1813 look like tag names, reference names, or object IDs.
1817 .Bl -tag -width GOT_AUTHOR
1819 The author's name and email address for
1824 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1827 may fail to parse commits without an email address in author data,
1831 environment variables with a missing email address.
1837 configuration settings in the repository's
1839 file will override the value of
1845 configuration settings contained in Git's global
1847 configuration file will be used only if the
1849 environment variable is
1852 .It Ev VISUAL , EDITOR
1853 The editor spawned by
1858 .It Ev GOT_LOG_DEFAULT_LIMIT
1859 The default limit on the number of commits traversed by
1861 If set to zero, the limit is unbounded.
1862 This variable will be silently ignored if it is set to a non-numeric value.
1867 Clone an existing Git repository for use with
1871 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1873 Use of HTTP URLs currently requires
1877 .Dl $ git clone --bare https://github.com/openbsd/src.git
1879 Alternatively, for quick and dirty local testing of
1881 a new Git repository could be created and populated with files,
1882 e.g. from a temporary CVS checkout located at
1885 .Dl $ got init /var/git/src.git
1886 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1888 Check out a work tree from the Git repository to /usr/src:
1890 .Dl $ got checkout /var/git/src.git /usr/src
1892 View local changes in a work tree directory:
1895 .Dl $ got diff | less
1897 Interactively revert selected local changes in a work tree directory:
1899 .Dl $ got revert -p -R\ .
1901 In a work tree or a git repository directory, list all branch references:
1905 In a work tree or a git repository directory, create a new branch called
1906 .Dq unified-buffer-cache
1907 which is forked off the
1911 .Dl $ got branch unified-buffer-cache master
1913 Switch an existing work tree to the branch
1914 .Dq unified-buffer-cache .
1915 Local changes in the work tree will be preserved and merged if necessary:
1917 .Dl $ got update -b unified-buffer-cache
1919 Create a new commit from local changes in a work tree directory.
1920 This new commit will become the head commit of the work tree's current branch:
1924 In a work tree or a git repository directory, view changes committed in
1925 the 3 most recent commits to the work tree's branch, or the branch resolved
1926 via the repository's HEAD reference, respectively:
1928 .Dl $ got log -p -l 3
1930 As above, but display changes in the order in which
1932 could apply them in sequence:
1934 .Dl $ got log -p -l 3 -R
1936 In a work tree or a git repository directory, log the history of a subdirectory:
1938 .Dl $ got log sys/uvm
1940 While operating inside a work tree, paths are specified relative to the current
1941 working directory, so this command will log the subdirectory
1944 .Dl $ cd sys/uvm && got log '.'
1946 And this command has the same effect:
1948 .Dl $ cd sys/dev/usb && got log ../../uvm
1950 Add new files and remove obsolete files in a work tree directory:
1952 .Dl $ got add sys/uvm/uvm_ubc.c
1953 .Dl $ got remove sys/uvm/uvm_vnode.c
1955 Create a new commit from local changes in a work tree directory
1956 with a pre-defined log message.
1958 .Dl $ got commit -m 'unify the buffer cache'
1960 Update any work tree checked out from the
1961 .Dq unified-buffer-cache
1962 branch to the latest commit on this branch:
1966 Roll file content on the unified-buffer-cache branch back by one commit,
1967 and then fetch the rolled-back change into the work tree as a local change
1968 to be amended and perhaps committed again:
1970 .Dl $ got backout unified-buffer-cache
1971 .Dl $ got commit -m 'roll back previous'
1972 .Dl $ # now back out the previous backout :-)
1973 .Dl $ got backout unified-buffer-cache
1975 Fetch new upstream commits into the local repository's
1982 In a repository created with a HTTP URL and
1983 .Cm git clone --bare
1986 command must be used instead:
1988 .Dl $ cd /var/git/src.git
1989 .Dl $ git fetch origin master:refs/remotes/origin/master
1993 branch to merge the new changes that are now visible on the
1998 .Dl $ got update -b origin/master
1999 .Dl $ got rebase master
2002 .Dq unified-buffer-cache
2003 branch on top of the new head commit of the
2007 .Dl $ got update -b master
2008 .Dl $ got rebase unified-buffer-cache
2010 Create a patch from all changes on the unified-buffer-cache branch.
2011 The patch can be mailed out for review and applied to
2015 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
2017 Edit the entire commit history of the
2018 .Dq unified-buffer-cache
2021 .Dl $ got update -b unified-buffer-cache
2022 .Dl $ got update -c master
2025 In order to merge changes committed to the
2026 .Dq unified-buffer-cache
2027 branch back into the
2030 .Dq unified-buffer-cache
2031 branch must first be rebased onto the
2035 .Dl $ got update -b master
2036 .Dl $ got rebase unified-buffer-cache
2039 .Dq unified-buffer-cache
2040 branch can now be made visible on the
2044 Because the rebase operation switched the work tree to the
2045 .Dq unified-buffer-cache
2046 branch, the work tree must be switched back to the
2049 .Dq unified-buffer-cache
2050 branch can be integrated into
2053 .Dl $ got update -b master
2054 .Dl $ got integrate unified-buffer-cache
2056 Additional steps may be necessary if local changes need to be pushed back
2057 to the remote repository, which currently requires
2059 Before working against existing branches in a repository cloned with
2060 .Cm git clone --bare
2065 must be configured to map all references in the remote repository
2068 namespace of the local repository.
2069 This can achieved by setting Git's
2070 .Pa remote.origin.fetch
2071 configuration variable to the value
2072 .Dq +refs/heads/*:refs/remotes/origin/*
2077 .Dl $ cd /var/git/repo
2078 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
2082 option must be disabled:
2084 .Dl $ cd /var/git/repo
2085 .Dl $ git config remote.origin.mirror false
2087 Alternatively, the following
2089 configuration item can be added manually to the Git repository's
2093 .Dl [remote "origin"]
2095 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2098 This configuration leaves the local repository's
2100 namespace free for use by local branches checked out with
2102 and, if needed, created with
2107 namespace can now be updated with incoming changes from the remote
2112 without extra command line arguments:
2114 .Dl $ cd /var/git/repo
2117 To make changes fetched from the remote repository appear on the
2121 branch must be rebased onto the
2124 This will also merge local changes, if any, with the incoming changes:
2126 .Dl $ got update -b origin/master
2127 .Dl $ got rebase master
2131 branch, log messages for local changes can now be amended with
2133 by other developers and any other important new information:
2135 .Dl $ got update -c origin/master
2136 .Dl $ got histedit -m
2138 Local changes on the
2140 branch can then be pushed to the remote
2144 .Dl $ cd /var/git/repo
2145 .Dl $ git push origin master
2148 .Xr git-repository 5 ,
2151 .An Stefan Sperling Aq Mt stsp@openbsd.org
2152 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2153 .An Joshua Stein Aq Mt jcs@openbsd.org
2154 .An Ori Bernstein Aq Mt ori@openbsd.org
2157 is a work-in-progress and many commands remain to be implemented.
2158 At present, the user has to fall back on
2160 to perform many tasks, in particular tasks related to repository
2161 administration and tasks which require a network connection.
