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 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 .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
733 When invoked within a work tree with less than two arguments, display
734 uncommitted changes in the work tree.
737 is specified, only show changes within this path.
739 If two arguments are provided, treat each argument as a reference, a tag
740 name, or an object ID SHA1 hash, and display differences between the
741 corresponding objects.
742 Both objects must be of the same type (blobs, trees, or commits).
743 An abbreviated hash argument will be expanded to a full SHA1 hash
744 automatically, provided the abbreviation is unique.
751 Set the number of context lines shown in the diff.
752 By default, 3 lines of context are shown.
753 .It Fl r Ar repository-path
754 Use the repository at the specified path.
755 If not specified, assume the repository is located at or above the current
757 If this directory is a
759 work tree, use the repository path associated with this work tree.
761 Show changes staged with
763 instead of showing local changes.
764 This option is only valid when
766 is invoked in a work tree.
768 Ignore whitespace-only changes.
773 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
774 Display line-by-line history of a file at the specified path.
781 Start traversing history at the specified
783 The expected argument is a commit ID SHA1 hash or an existing reference
784 or tag name which will be resolved to a commit ID.
785 An abbreviated hash argument will be expanded to a full SHA1 hash
786 automatically, provided the abbreviation is unique.
787 .It Fl r Ar repository-path
788 Use the repository at the specified path.
789 If not specified, assume the repository is located at or above the current
791 If this directory is a
793 work tree, use the repository path associated with this work tree.
798 .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
799 Display a listing of files and directories at the specified
800 directory path in the repository.
801 Entries shown in this listing may carry one of the following trailing
803 .Bl -column YXZ description
804 .It @ Ta entry is a symbolic link
805 .It / Ta entry is a directory
806 .It * Ta entry is an executable file
807 .It $ Ta entry is a Git submodule
812 is specified, list the repository path corresponding to the current
813 directory of the work tree, or the root directory of the repository
814 if there is no work tree.
821 List files and directories as they appear in the specified
823 The expected argument is a commit ID SHA1 hash or an existing reference
824 or tag name which will be resolved to a commit ID.
825 An abbreviated hash argument will be expanded to a full SHA1 hash
826 automatically, provided the abbreviation is unique.
827 .It Fl r Ar repository-path
828 Use the repository at the specified path.
829 If not specified, assume the repository is located at or above the current
831 If this directory is a
833 work tree, use the repository path associated with this work tree.
835 Show object IDs of files (blob objects) and directories (tree objects).
837 Recurse into sub-directories in the repository.
842 .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
843 Manage references in a repository.
845 References may be listed, created, deleted, and changed.
846 When creating, deleting, or changing a reference the specified
848 must be an absolute reference name, i.e. it must begin with
855 .It Fl r Ar repository-path
856 Use the repository at the specified path.
857 If not specified, assume the repository is located at or above the current
859 If this directory is a
861 work tree, use the repository path associated with this work tree.
863 List references in the repository.
866 is specified, list all existing references in the repository.
869 is a reference namespace, list all references in this namespace.
870 Otherwise, show only the reference with the given
872 Cannot be used together with any other options except
875 Create a reference or change an existing reference.
876 The reference with the specified
878 will point at the specified
882 argument is a ID SHA1 hash or an existing reference or tag name which will
883 be resolved to the ID of a corresponding commit, tree, tag, or blob object.
884 Cannot be used together with any other options except
886 .It Fl s Ar reference
887 Create a symbolic reference, or change an existing symbolic reference.
888 The symbolic reference with the specified
890 will point at the specified
892 which must already exist in the repository.
893 Care should be taken not to create loops between references when
895 Cannot be used together with any other options except
898 Delete the reference with the specified
901 Cannot be used together with any other options except
904 .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
905 Create, list, or delete branches.
907 Branches are managed via references which live in the
912 command operates on references in this namespace only.
914 If invoked in a work tree without any arguments, print the name of the
915 work tree's current branch.
919 argument is passed, attempt to create a branch reference with the given name.
920 By default the new branch reference will point at the latest commit on the
921 work tree's current branch if invoked in a work tree, and otherwise to a commit
922 resolved via the repository's HEAD reference.
924 If invoked in a work tree, once the branch was created successfully
925 switch the work tree's head reference to the newly created branch and
926 update files across the entire work tree, just like
927 .Cm got update -b Ar name
929 Show the status of each affected file, using the following status codes:
930 .Bl -column YXZ description
931 .It U Ta file was updated and contained no local changes
932 .It G Ta file was updated and local changes were merged cleanly
933 .It C Ta file was updated and conflicts occurred during merge
934 .It D Ta file was deleted
935 .It A Ta new file was added
936 .It \(a~ Ta versioned file is obstructed by a non-regular file
937 .It ! Ta a missing versioned file was restored
945 Make a newly created branch reference point at the specified
949 argument is a commit ID SHA1 hash or an existing reference
950 or tag name which will be resolved to a commit ID.
951 .It Fl r Ar repository-path
952 Use the repository at the specified path.
953 If not specified, assume the repository is located at or above the current
955 If this directory is a
957 work tree, use the repository path associated with this work tree.
959 List all existing branches in the repository.
960 If invoked in a work tree, the work tree's current branch is shown
961 with one the following annotations:
962 .Bl -column YXZ description
963 .It * Ta work tree's base commit matches the branch tip
964 .It \(a~ Ta work tree's base commit is out-of-date
967 Delete the branch with the specified name from the repository.
968 Only the branch reference is deleted.
969 Any commit, tree, and blob objects belonging to the branch
970 remain in the repository and may be removed separately with
971 Git's garbage collector.
973 Do not switch and update the work tree after creating a new branch.
978 .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
979 Manage tags in a repository.
981 Tags are managed via references which live in the
986 command operates on references in this namespace only.
987 References in this namespace point at tag objects which contain a pointer
988 to another object, a tag message, as well as author and timestamp information.
990 Attempt to create a tag with the given
992 and make this tag point at the given
994 If no commit is specified, default to the latest commit on the work tree's
995 current branch if invoked in a work tree, and to a commit resolved via
996 the repository's HEAD reference otherwise.
1003 Make the newly created tag reference point at the specified
1007 argument is a commit ID SHA1 hash or an existing reference or tag name which
1008 will be resolved to a commit ID.
1009 An abbreviated hash argument will be expanded to a full SHA1 hash
1010 automatically, provided the abbreviation is unique.
1012 Use the specified tag message when creating the new tag.
1017 opens a temporary file in an editor where a tag message can be written.
1018 .It Fl r Ar repository-path
1019 Use the repository at the specified path.
1020 If not specified, assume the repository is located at or above the current
1022 If this directory is a
1024 work tree, use the repository path associated with this work tree.
1026 List all existing tags in the repository instead of creating a new tag.
1027 If this option is used, no other command-line arguments are allowed.
1032 command will not delete tags or change existing tags.
1033 If a tag must be deleted, the
1035 command may be used to delete a tag's reference.
1036 This should only be done if the tag has not already been copied to
1038 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
1039 Schedule unversioned files in a work tree for addition to the
1040 repository in the next commit.
1047 Permit recursion into directories.
1048 If this option is not specified,
1050 will refuse to run if a specified
1054 With -R, add files even if they match a
1058 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
1059 Remove versioned files from a work tree and schedule them for deletion
1060 from the repository in the next commit.
1067 Perform the operation even if a file contains uncommitted modifications.
1069 Keep affected files on disk.
1071 Permit recursion into directories.
1072 If this option is not specified,
1074 will refuse to run if a specified
1081 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
1082 Revert any uncommitted changes in files at the specified paths.
1083 File contents will be overwritten with those contained in the
1084 work tree's base commit.
1085 There is no way to bring discarded changes back after
1088 If a file was added with
1090 it will become an unversioned file again.
1091 If a file was deleted with
1093 it will be restored.
1100 Instead of reverting all changes in files, interactively select or reject
1101 changes to revert based on
1107 (quit reverting this file) responses.
1108 If a file is in modified status, individual patches derived from the
1109 modified file content can be reverted.
1110 Files in added or deleted status may only be reverted in their entirety.
1111 .It Fl F Ar response-script
1119 responses line-by-line from the specified
1121 file instead of prompting interactively.
1123 Permit recursion into directories.
1124 If this option is not specified,
1126 will refuse to run if a specified
1133 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1134 Create a new commit in the repository from changes in a work tree
1135 and use this commit as the new base commit for the work tree.
1138 is specified, commit all changes in the work tree.
1139 Otherwise, commit changes at or within the specified paths.
1141 If changes have been explicitly staged for commit with
1143 only commit staged changes and reject any specified paths which
1144 have not been staged.
1146 Show the status of each affected file, using the following status codes:
1147 .Bl -column YXZ description
1148 .It M Ta modified file
1149 .It D Ta file was deleted
1150 .It A Ta new file was added
1151 .It m Ta modified file modes (executable bit only)
1154 Files which are not part of the new commit will retain their previously
1155 recorded base commit.
1158 commands may refuse to run while the work tree contains files from
1159 multiple base commits.
1160 The base commit of such a work tree can be made consistent by running
1162 across the entire work tree.
1166 command requires the
1168 environment variable to be set,
1173 configuration settings can be
1174 obtained from the repository's
1176 file or from Git's global
1185 Use the specified log message when creating the new commit.
1190 opens a temporary file in an editor where a log message can be written.
1194 will refuse to run if certain preconditions are not met.
1195 If the work tree's current branch is not in the
1197 reference namespace, new commits may not be created on this branch.
1198 Local changes may only be committed if they are based on file content
1199 found in the most recent commit on the work tree's branch.
1200 If a path is found to be out of date,
1202 must be used first in order to merge local changes with changes made
1207 .It Cm cherrypick Ar commit
1208 Merge changes from a single
1213 must be on a different branch than the work tree's base commit.
1214 The expected argument is a reference or a commit ID SHA1 hash.
1215 An abbreviated hash argument will be expanded to a full SHA1 hash
1216 automatically, provided the abbreviation is unique.
1218 Show the status of each affected file, using the following status codes:
1219 .Bl -column YXZ description
1220 .It G Ta file was merged
1221 .It C Ta file was merged and conflicts occurred during merge
1222 .It ! Ta changes destined for a missing file were not merged
1223 .It D Ta file was deleted
1224 .It d Ta file's deletion was obstructed by local modifications
1225 .It A Ta new file was added
1226 .It \(a~ Ta changes destined for a non-regular file were not merged
1229 The merged changes will appear as local changes in the work tree, which
1232 amended manually or with further
1237 or discarded again with
1241 will refuse to run if certain preconditions are not met.
1242 If the work tree contains multiple base commits it must first be updated
1243 to a single base commit with
1245 If the work tree already contains files with merge conflicts, these
1246 conflicts must be resolved first.
1250 .It Cm backout Ar commit
1251 Reverse-merge changes from a single
1256 must be on the same branch as the work tree's base commit.
1257 The expected argument is a reference or a commit ID SHA1 hash.
1258 An abbreviated hash argument will be expanded to a full SHA1 hash
1259 automatically, provided the abbreviation is unique.
1261 Show the status of each affected file, using the following status codes:
1262 .Bl -column YXZ description
1263 .It G Ta file was merged
1264 .It C Ta file was merged and conflicts occurred during merge
1265 .It ! Ta changes destined for a missing file were not merged
1266 .It D Ta file was deleted
1267 .It d Ta file's deletion was obstructed by local modifications
1268 .It A Ta new file was added
1269 .It \(a~ Ta changes destined for a non-regular file were not merged
1272 The reverse-merged changes will appear as local changes in the work tree,
1273 which may be viewed with
1275 amended manually or with further
1280 or discarded again with
1284 will refuse to run if certain preconditions are not met.
1285 If the work tree contains multiple base commits it must first be updated
1286 to a single base commit with
1288 If the work tree already contains files with merge conflicts, these
1289 conflicts must be resolved first.
1293 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1294 Rebase commits on the specified
1296 onto the tip of the current branch of the work tree.
1299 must share common ancestry with the work tree's current branch.
1300 Rebasing begins with the first descendant commit of the youngest
1301 common ancestor commit shared by the specified
1303 and the work tree's current branch, and stops once the tip commit
1310 is used as intended, the specified
1312 represents a local commit history and may already contain changes
1313 that are not yet visible in any other repositories.
1314 The work tree's current branch, which must be set with
1318 operation, represents a branch from a remote repository which shares
1319 a common history with the specified
1321 but has progressed, and perhaps diverged, due to commits added to the
1324 Rebased commits are accumulated on a temporary branch which the work tree
1325 will remain switched to throughout the entire rebase operation.
1326 Commits on this branch represent the same changes with the same log
1327 messages as their counterparts on the original
1329 but with different commit IDs.
1330 Once rebasing has completed successfully, the temporary branch becomes
1331 the new version of the specified
1333 and the work tree is automatically switched to it.
1335 While rebasing commits, show the status of each affected file,
1336 using the following status codes:
1337 .Bl -column YXZ description
1338 .It G Ta file was merged
1339 .It C Ta file was merged and conflicts occurred during merge
1340 .It ! Ta changes destined for a missing file were not merged
1341 .It D Ta file was deleted
1342 .It d Ta file's deletion was obstructed by local modifications
1343 .It A Ta new file was added
1344 .It \(a~ Ta changes destined for a non-regular file were not merged
1347 If merge conflicts occur the rebase operation is interrupted and may
1348 be continued once conflicts have been resolved.
1349 Alternatively, the rebase operation may be aborted which will leave
1351 unmodified and the work tree switched back to its original branch.
1353 If a merge conflict is resolved in a way which renders the merged
1354 change into a no-op change, the corresponding commit will be elided
1355 when the rebase operation continues.
1358 will refuse to run if certain preconditions are not met.
1359 If the work tree is not yet fully updated to the tip commit of its
1360 branch then the work tree must first be updated with
1362 If changes have been staged with
1364 these changes must first be committed with
1368 If the work tree contains local changes, these changes must first be
1375 contains changes to files outside of the work tree's path prefix,
1376 the work tree cannot be used to rebase this branch.
1382 commands will refuse to run while a rebase operation is in progress.
1383 Other commands which manipulate the work tree may be used for
1384 conflict resolution purposes.
1391 Abort an interrupted rebase operation.
1392 If this option is used, no other command-line arguments are allowed.
1394 Continue an interrupted rebase operation.
1395 If this option is used, no other command-line arguments are allowed.
1400 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1401 Edit commit history between the work tree's current base commit and
1402 the tip commit of the work tree's current branch.
1406 operation the work tree's current branch must be set with
1408 to the branch which should be edited, unless this branch is already the
1409 current branch of the work tree.
1410 The tip of this branch represents the upper bound (inclusive) of commits
1415 Furthermore, the work tree's base commit
1418 to a point in this branch's commit history where editing should begin.
1419 This commit represents the lower bound (non-inclusive) of commits touched
1424 Editing of commit history is controlled via a
1426 which can be written in an editor based on a template, passed on the
1427 command line, or generated with the
1429 option if only log messages need to be edited.
1431 The format of the histedit script is line-based.
1432 Each line in the script begins with a command name, followed by
1433 whitespace and an argument.
1434 For most commands, the expected argument is a commit ID SHA1 hash.
1435 Any remaining text on the line is ignored.
1436 Lines which begin with the
1438 character are ignored entirely.
1440 The available commands are as follows:
1441 .Bl -column YXZ pick-commit
1442 .It pick Ar commit Ta Use the specified commit as it is.
1443 .It edit Ar commit Ta Use the specified commit but once changes have been
1444 merged into the work tree interrupt the histedit operation for amending.
1445 .It fold Ar commit Ta Combine the specified commit with the next commit
1446 listed further below that will be used.
1447 .It drop Ar commit Ta Remove this commit from the edited history.
1448 .It mesg Ar log-message Ta Use the specified single-line log message for
1449 the commit on the previous line.
1450 If the log message argument is left empty, open an editor where a new
1451 log message can be written.
1454 Every commit in the history being edited must be mentioned in the script.
1455 Lines may be re-ordered to change the order of commits in the edited history.
1456 No commit may be listed more than once.
1458 Edited commits are accumulated on a temporary branch which the work tree
1459 will remain switched to throughout the entire histedit operation.
1460 Once history editing has completed successfully, the temporary branch becomes
1461 the new version of the work tree's branch and the work tree is automatically
1464 While merging commits, show the status of each affected file,
1465 using the following status codes:
1466 .Bl -column YXZ description
1467 .It G Ta file was merged
1468 .It C Ta file was merged and conflicts occurred during merge
1469 .It ! Ta changes destined for a missing file were not merged
1470 .It D Ta file was deleted
1471 .It d Ta file's deletion was obstructed by local modifications
1472 .It A Ta new file was added
1473 .It \(a~ Ta changes destined for a non-regular file were not merged
1476 If merge conflicts occur the histedit operation is interrupted and may
1477 be continued once conflicts have been resolved.
1478 Alternatively, the histedit operation may be aborted which will leave
1479 the work tree switched back to its original branch.
1481 If a merge conflict is resolved in a way which renders the merged
1482 change into a no-op change, the corresponding commit will be elided
1483 when the histedit operation continues.
1486 will refuse to run if certain preconditions are not met.
1487 If the work tree's current branch is not in the
1489 reference namespace, the history of the branch may not be edited.
1490 If the work tree contains multiple base commits it must first be updated
1491 to a single base commit with
1493 If changes have been staged with
1495 these changes must first be committed with
1499 If the work tree contains local changes, these changes must first be
1504 If the edited history contains changes to files outside of the work tree's
1505 path prefix, the work tree cannot be used to edit the history of this branch.
1512 commands will refuse to run while a histedit operation is in progress.
1513 Other commands which manipulate the work tree may be used, and the
1515 command may be used to commit arbitrary changes to the temporary branch
1516 while the histedit operation is interrupted.
1523 Abort an interrupted histedit operation.
1524 If this option is used, no other command-line arguments are allowed.
1526 Continue an interrupted histedit operation.
1527 If this option is used, no other command-line arguments are allowed.
1528 .It Fl F Ar histedit-script
1531 instead of opening a temporary file in an editor where a histedit script
1534 Edit log messages only.
1535 This option is a quick equivalent to a histedit script which edits
1536 only log messages but otherwise leaves every picked commit as-is.
1539 option can only be used when starting a new histedit operation.
1540 If this option is used, no other command-line arguments are allowed.
1545 .It Cm integrate Ar branch
1546 Integrate the specified
1548 into the work tree's current branch.
1549 Files in the work tree are updated to match the contents on the integrated
1551 and the reference of the work tree's branch is changed to point at the
1552 head commit of the integrated
1555 Both branches can be considered equivalent after integration since they
1556 will be pointing at the same commit.
1557 Both branches remain available for future work, if desired.
1558 In case the integrated
1560 is no longer needed it may be deleted with
1563 Show the status of each affected file, using the following status codes:
1564 .Bl -column YXZ description
1565 .It U Ta file was updated
1566 .It D Ta file was deleted
1567 .It A Ta new file was added
1568 .It \(a~ Ta versioned file is obstructed by a non-regular file
1569 .It ! Ta a missing versioned file was restored
1573 will refuse to run if certain preconditions are not met.
1574 Most importantly, the
1576 must have been rebased onto the work tree's current branch with
1578 before it can be integrated, in order to linearize commit history and
1579 resolve merge conflicts.
1580 If the work tree contains multiple base commits it must first be updated
1581 to a single base commit with
1583 If changes have been staged with
1585 these changes must first be committed with
1589 If the work tree contains local changes, these changes must first be
1597 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1598 Stage local changes for inclusion in the next commit.
1601 is specified, stage all changes in the work tree.
1602 Otherwise, stage changes at or within the specified paths.
1603 Paths may be staged if they are added, modified, or deleted according to
1606 Show the status of each affected file, using the following status codes:
1607 .Bl -column YXZ description
1608 .It A Ta file addition has been staged
1609 .It M Ta file modification has been staged
1610 .It D Ta file deletion has been staged
1613 Staged file contents are saved in newly created blob objects in the repository.
1614 These blobs will be referred to by tree objects once staged changes have been
1617 Staged changes affect the behaviour of
1622 While paths with staged changes exist, the
1624 command will refuse to commit any paths which do not have staged changes.
1625 Local changes created on top of staged changes can only be committed if
1626 the path is staged again, or if the staged changes are committed first.
1629 command will show both local changes and staged changes.
1632 command is able to display local changes relative to staged changes,
1633 and to display staged changes relative to the repository.
1636 command cannot revert staged changes but may be used to revert
1637 local changes created on top of staged changes.
1644 Instead of staging new changes, list paths which are already staged,
1645 along with the IDs of staged blob objects and stage status codes.
1646 If paths were provided in the command line show the staged paths
1647 among the specified paths.
1648 Otherwise, show all staged paths.
1650 Instead of staging the entire content of a changed file, interactively
1651 select or reject changes for staging based on
1655 (reject change), and
1657 (quit staging this file) responses.
1658 If a file is in modified status, individual patches derived from the
1659 modified file content can be staged.
1660 Files in added or deleted status may only be staged or rejected in
1662 .It Fl F Ar response-script
1670 responses line-by-line from the specified
1672 file instead of prompting interactively.
1676 will refuse to run if certain preconditions are not met.
1677 If a file contains merge conflicts, these conflicts must be resolved first.
1678 If a file is found to be out of date relative to the head commit on the
1679 work tree's current branch, the file must be updated with
1681 before it can be staged (however, this does not prevent the file from
1682 becoming out-of-date at some point after having been staged).
1689 commands will refuse to run while staged changes exist.
1690 If staged changes cannot be committed because a staged path
1691 is out of date, the path must be unstaged with
1693 before it can be updated with
1695 and may then be staged again if necessary.
1699 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1700 Merge staged changes back into the work tree and put affected paths
1701 back into non-staged status.
1704 is specified, unstage all staged changes across the entire work tree.
1705 Otherwise, unstage changes at or within the specified paths.
1707 Show the status of each affected file, using the following status codes:
1708 .Bl -column YXZ description
1709 .It G Ta file was unstaged
1710 .It C Ta file was unstaged and conflicts occurred during merge
1711 .It ! Ta changes destined for a missing file were not merged
1712 .It D Ta file was staged as deleted and still is deleted
1713 .It d Ta file's deletion was obstructed by local modifications
1714 .It \(a~ Ta changes destined for a non-regular file were not merged
1722 Instead of unstaging the entire content of a changed file, interactively
1723 select or reject changes for unstaging based on
1727 (keep change staged), and
1729 (quit unstaging this file) responses.
1730 If a file is staged in modified status, individual patches derived from the
1731 staged file content can be unstaged.
1732 Files staged in added or deleted status may only be unstaged in their entirety.
1733 .It Fl F Ar response-script
1741 responses line-by-line from the specified
1743 file instead of prompting interactively.
1748 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1749 Parse and print contents of objects to standard output in a line-based
1751 Content of commit, tree, and tag objects is printed in a way similar
1752 to the actual content stored in such objects.
1753 Blob object contents are printed as they would appear in files on disk.
1755 Attempt to interpret each argument as a reference, a tag name, or
1756 an object ID SHA1 hash.
1757 References will be resolved to an object ID.
1758 Tag names will resolved to a tag object.
1759 An abbreviated hash argument will be expanded to a full SHA1 hash
1760 automatically, provided the abbreviation is unique.
1762 If none of the above interpretations produce a valid result, or if the
1764 option is used, attempt to interpret the argument as a path which will
1765 be resolved to the ID of an object found at this path in the repository.
1772 Look up paths in the specified
1774 If this option is not used, paths are looked up in the commit resolved
1775 via the repository's HEAD reference.
1776 The expected argument is a commit ID SHA1 hash or an existing reference
1777 or tag name which will be resolved to a commit ID.
1778 An abbreviated hash argument will be expanded to a full SHA1 hash
1779 automatically, provided the abbreviation is unique.
1780 .It Fl r Ar repository-path
1781 Use the repository at the specified path.
1782 If not specified, assume the repository is located at or above the current
1784 If this directory is a
1786 work tree, use the repository path associated with this work tree.
1788 Interpret all arguments as paths only.
1789 This option can be used to resolve ambiguity in cases where paths
1790 look like tag names, reference names, or object IDs.
1794 .Bl -tag -width GOT_AUTHOR
1796 The author's name and email address for
1801 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1804 may fail to parse commits without an email address in author data,
1808 environment variables with a missing email address.
1814 configuration settings in the repository's
1816 file will override the value of
1822 configuration settings contained in Git's global
1824 configuration file will be used only if the
1826 environment variable is
1829 .It Ev VISUAL , EDITOR
1830 The editor spawned by
1835 .It Ev GOT_LOG_DEFAULT_LIMIT
1836 The default limit on the number of commits traversed by
1838 If set to zero, the limit is unbounded.
1839 This variable will be silently ignored if it is set to a non-numeric value.
1844 Clone an existing Git repository for use with
1848 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1850 Use of HTTP URLs currently requires
1854 .Dl $ git clone --bare https://github.com/openbsd/src.git
1856 Alternatively, for quick and dirty local testing of
1858 a new Git repository could be created and populated with files,
1859 e.g. from a temporary CVS checkout located at
1862 .Dl $ got init /var/git/src.git
1863 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1865 Check out a work tree from the Git repository to /usr/src:
1867 .Dl $ got checkout /var/git/src.git /usr/src
1869 View local changes in a work tree directory:
1872 .Dl $ got diff | less
1874 Interactively revert selected local changes in a work tree directory:
1876 .Dl $ got revert -p -R\ .
1878 In a work tree or a git repository directory, list all branch references:
1882 In a work tree or a git repository directory, create a new branch called
1883 .Dq unified-buffer-cache
1884 which is forked off the
1888 .Dl $ got branch unified-buffer-cache master
1890 Switch an existing work tree to the branch
1891 .Dq unified-buffer-cache .
1892 Local changes in the work tree will be preserved and merged if necessary:
1894 .Dl $ got update -b unified-buffer-cache
1896 Create a new commit from local changes in a work tree directory.
1897 This new commit will become the head commit of the work tree's current branch:
1901 In a work tree or a git repository directory, view changes committed in
1902 the 3 most recent commits to the work tree's branch, or the branch resolved
1903 via the repository's HEAD reference, respectively:
1905 .Dl $ got log -p -l 3
1907 In a work tree or a git repository directory, log the history of a subdirectory:
1909 .Dl $ got log sys/uvm
1911 While operating inside a work tree, paths are specified relative to the current
1912 working directory, so this command will log the subdirectory
1915 .Dl $ cd sys/uvm && got log '.'
1917 And this command has the same effect:
1919 .Dl $ cd sys/dev/usb && got log ../../uvm
1921 Add new files and remove obsolete files in a work tree directory:
1923 .Dl $ got add sys/uvm/uvm_ubc.c
1924 .Dl $ got remove sys/uvm/uvm_vnode.c
1926 Create a new commit from local changes in a work tree directory
1927 with a pre-defined log message.
1929 .Dl $ got commit -m 'unify the buffer cache'
1931 Update any work tree checked out from the
1932 .Dq unified-buffer-cache
1933 branch to the latest commit on this branch:
1937 Roll file content on the unified-buffer-cache branch back by one commit,
1938 and then fetch the rolled-back change into the work tree as a local change
1939 to be amended and perhaps committed again:
1941 .Dl $ got backout unified-buffer-cache
1942 .Dl $ got commit -m 'roll back previous'
1943 .Dl $ # now back out the previous backout :-)
1944 .Dl $ got backout unified-buffer-cache
1946 Fetch new upstream commits into the local repository's
1953 In a repository created with a HTTP URL and
1954 .Cm git clone --bare
1957 command must be used instead:
1959 .Dl $ cd /var/git/src.git
1960 .Dl $ git fetch origin master:refs/remotes/origin/master
1964 branch to merge the new changes that are now visible on the
1969 .Dl $ got update -b origin/master
1970 .Dl $ got rebase master
1973 .Dq unified-buffer-cache
1974 branch on top of the new head commit of the
1978 .Dl $ got update -b master
1979 .Dl $ got rebase unified-buffer-cache
1981 Create a patch from all changes on the unified-buffer-cache branch.
1982 The patch can be mailed out for review and applied to
1986 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1988 Edit the entire commit history of the
1989 .Dq unified-buffer-cache
1992 .Dl $ got update -b unified-buffer-cache
1993 .Dl $ got update -c master
1996 In order to merge changes committed to the
1997 .Dq unified-buffer-cache
1998 branch back into the
2001 .Dq unified-buffer-cache
2002 branch must first be rebased onto the
2006 .Dl $ got update -b master
2007 .Dl $ got rebase unified-buffer-cache
2010 .Dq unified-buffer-cache
2011 branch can now be made visible on the
2015 Because the rebase operation switched the work tree to the
2016 .Dq unified-buffer-cache
2017 branch, the work tree must be switched back to the
2020 .Dq unified-buffer-cache
2021 branch can be integrated into
2024 .Dl $ got update -b master
2025 .Dl $ got integrate unified-buffer-cache
2027 Additional steps may be necessary if local changes need to be pushed back
2028 to the remote repository, which currently requires
2030 Before working against existing branches in a repository cloned with
2031 .Cm git clone --bare
2036 must be configured to map all references in the remote repository
2039 namespace of the local repository.
2040 This can achieved by setting Git's
2041 .Pa remote.origin.fetch
2042 configuration variable to the value
2043 .Dq +refs/heads/*:refs/remotes/origin/*
2048 .Dl $ cd /var/git/repo
2049 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
2053 option must be disabled:
2055 .Dl $ cd /var/git/repo
2056 .Dl $ git config remote.origin.mirror false
2058 Alternatively, the following
2060 configuration item can be added manually to the Git repository's
2064 .Dl [remote "origin"]
2066 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2069 This configuration leaves the local repository's
2071 namespace free for use by local branches checked out with
2073 and, if needed, created with
2078 namespace can now be updated with incoming changes from the remote
2083 without extra command line arguments:
2085 .Dl $ cd /var/git/repo
2088 To make changes fetched from the remote repository appear on the
2092 branch must be rebased onto the
2095 This will also merge local changes, if any, with the incoming changes:
2097 .Dl $ got update -b origin/master
2098 .Dl $ got rebase master
2102 branch, log messages for local changes can now be amended with
2104 by other developers and any other important new information:
2106 .Dl $ got update -c origin/master
2107 .Dl $ got histedit -m
2109 Local changes on the
2111 branch can then be pushed to the remote
2115 .Dl $ cd /var/git/repo
2116 .Dl $ git push origin master
2119 .Xr git-repository 5 ,
2122 .An Stefan Sperling Aq Mt stsp@openbsd.org
2123 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2124 .An Joshua Stein Aq Mt jcs@openbsd.org
2125 .An Ori Bernstein Aq Mt ori@openbsd.org
2128 is a work-in-progress and many commands remain to be implemented.
2129 At present, the user has to fall back on
2131 to perform many tasks, in particular tasks related to repository
2132 administration and tasks which require a network connection.
