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 q Oc Oo Fl v Oc Ar repository-URL Op Ar target-directory
140 Clone a Git repository at the specified
143 .Ar target-directory .
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, and a path to the repository
157 .Lk scheme://hostname/path/to/repository
159 The following protocol schemes are supported:
160 .Bl -tag -width git+ssh
162 The Git protocol as implemented by the
165 This protocol is discouraged since it supports neither authentication nor
168 The Git protocol wrapped in an authenticated and encrypted
171 With this protocol the hostname may contain an embedded username for
176 Short alias for git+ssh.
184 Suppress progress reporting output.
185 The same option will be passed to
189 Increase the verbosity of progress reporting output.
190 The same option will be passed to
193 Multiple -v options increase the verbosity.
199 .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
200 Copy files from a repository into a new work tree.
201 Show the status of each affected file, using the following status codes:
202 .Bl -column YXZ description
203 .It A Ta new file was added
204 .It E Ta file already exists in work tree's meta-data
209 is not specified, either use the last component of
210 .Ar repository path ,
213 was specified use the last component of
221 Proceed with the checkout operation even if the directory at
224 Existing files will be left intact.
226 Check out files from a commit on the specified
228 If this option is not specified, a branch resolved via the repository's HEAD
229 reference will be used.
231 Check out files from the specified
233 on the selected branch.
234 The expected argument is a commit ID SHA1 hash or an existing reference
235 or tag name which will be resolved to a commit ID.
236 An abbreviated hash argument will be expanded to a full SHA1 hash
237 automatically, provided the abbreviation is unique.
238 If this option is not specified, the most recent commit on the selected
243 is not contained in the selected branch, a different branch which contains
244 this commit must be specified with the
247 If no such branch is known a new branch must be created for this
253 Checking out work trees with an unknown branch is intentionally not supported.
254 .It Fl p Ar path-prefix
255 Restrict the work tree to a subset of the repository's tree hierarchy.
256 Only files beneath the specified
263 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
264 Update an existing work tree to a different commit.
265 Show the status of each affected file, using the following status codes:
266 .Bl -column YXZ description
267 .It U Ta file was updated and contained no local changes
268 .It G Ta file was updated and local changes were merged cleanly
269 .It C Ta file was updated and conflicts occurred during merge
270 .It D Ta file was deleted
271 .It A Ta new file was added
272 .It \(a~ Ta versioned file is obstructed by a non-regular file
273 .It ! Ta a missing versioned file was restored
278 is specified, update the entire work tree.
279 Otherwise, restrict the update operation to files at or within the
281 Each path is required to exist in the update operation's target commit.
282 Files in the work tree outside specified paths will remain unchanged and
283 will retain their previously recorded base commit.
286 commands may refuse to run while the work tree contains files from
287 multiple base commits.
288 The base commit of such a work tree can be made consistent by running
290 across the entire work tree.
293 is incompatible with the
298 cannot update paths with staged changes.
299 If changes have been staged with
301 these changes must first be committed with
311 Switch the work tree's branch reference to the specified
313 before updating the work tree.
314 This option requires that all paths in the work tree are updated.
316 Update the work tree to the specified
318 The expected argument is a commit ID SHA1 hash or an existing reference
319 or tag name which will be resolved to a commit ID.
320 An abbreviated hash argument will be expanded to a full SHA1 hash
321 automatically, provided the abbreviation is unique.
322 If this option is not specified, the most recent commit on the work tree's
328 .It Cm status Op Ar path ...
329 Show the current modification status of files in a work tree,
330 using the following status codes:
331 .Bl -column YXZ description
332 .It M Ta modified file
333 .It A Ta file scheduled for addition in next commit
334 .It D Ta file scheduled for deletion in next commit
335 .It C Ta modified or added file which contains merge conflicts
336 .It ! Ta versioned file was expected on disk but is missing
337 .It \(a~ Ta versioned file is obstructed by a non-regular file
338 .It ? Ta unversioned item not tracked by
340 .It m Ta modified file modes (executable bit only)
341 .It N Ta non-existent
343 specified on the command line
348 is specified, show modifications in the entire work tree.
349 Otherwise, show modifications at or within the specified paths.
351 If changes have been staged with
353 staged changes are shown in the second output column, using the following
355 .Bl -column YXZ description
356 .It M Ta file modification is staged
357 .It A Ta file addition is staged
358 .It D Ta file deletion is staged
361 Changes created on top of staged changes are indicated in the first column:
362 .Bl -column YXZ description
363 .It MM Ta file was modified after earlier changes have been staged
364 .It MA Ta file was modified after having been staged for addition
367 For compatibility with
378 files in each traversed directory and will not display unversioned files
379 which match these patterns.
384 supports consecutive asterisks,
386 which will match an arbitrary amount of directories.
390 only supports a single ignore pattern per line.
394 does not support negated ignore patterns prefixed with
396 and gives no special significance to the location of path component separators,
402 .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
403 Display history of a repository.
406 is specified, show only commits which modified this path.
407 If invoked in a work tree, the
409 is interpreted relative to the current working directory,
410 and the work tree's path prefix is implicitly prepended.
411 Otherwise, the path is interpreted relative to the repository root.
418 Display individual commits which were merged into the current branch
422 shows the linear history of the current branch only.
424 Start traversing history at the specified
426 The expected argument is a commit ID SHA1 hash or an existing reference
427 or tag name which will be resolved to a commit ID.
428 An abbreviated hash argument will be expanded to a full SHA1 hash
429 automatically, provided the abbreviation is unique.
430 If this option is not specified, default to the work tree's current branch
431 if invoked in a work tree, or to the repository's HEAD reference.
433 Set the number of context lines shown in diffs with
435 By default, 3 lines of context are shown.
437 Limit history traversal to a given number of commits.
438 If this option is not specified, a default limit value of zero is used,
439 which is treated as an unbounded limit.
441 .Ev GOT_LOG_DEFAULT_LIMIT
442 environment variable may be set to change this default value.
444 Display the patch of modifications made in each commit.
447 is specified, only show the patch of modifications at or within this path.
448 .It Fl s Ar search-pattern
449 If specified, show only commits with a log message matched by the extended
452 Regular expression syntax is documented in
454 .It Fl r Ar repository-path
455 Use the repository at the specified path.
456 If not specified, assume the repository is located at or above the current
458 If this directory is a
460 work tree, use the repository path associated with this work tree.
462 .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
463 When invoked within a work tree with less than two arguments, display
464 uncommitted changes in the work tree.
467 is specified, only show changes within this path.
469 If two arguments are provided, treat each argument as a reference, a tag
470 name, or an object ID SHA1 hash, and display differences between the
471 corresponding objects.
472 Both objects must be of the same type (blobs, trees, or commits).
473 An abbreviated hash argument will be expanded to a full SHA1 hash
474 automatically, provided the abbreviation is unique.
481 Set the number of context lines shown in the diff.
482 By default, 3 lines of context are shown.
483 .It Fl r Ar repository-path
484 Use the repository at the specified path.
485 If not specified, assume the repository is located at or above the current
487 If this directory is a
489 work tree, use the repository path associated with this work tree.
491 Show changes staged with
493 instead of showing local changes.
494 This option is only valid when
496 is invoked in a work tree.
498 Ignore whitespace-only changes.
503 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
504 Display line-by-line history of a file at the specified path.
511 Start traversing history at the specified
513 The expected argument is a commit ID SHA1 hash or an existing reference
514 or tag name which will be resolved to a commit ID.
515 An abbreviated hash argument will be expanded to a full SHA1 hash
516 automatically, provided the abbreviation is unique.
517 .It Fl r Ar repository-path
518 Use the repository at the specified path.
519 If not specified, assume the repository is located at or above the current
521 If this directory is a
523 work tree, use the repository path associated with this work tree.
528 .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
529 Display a listing of files and directories at the specified
530 directory path in the repository.
531 Entries shown in this listing may carry one of the following trailing
533 .Bl -column YXZ description
534 .It @ Ta entry is a symbolic link
535 .It / Ta entry is a directory
536 .It * Ta entry is an executable file
537 .It $ Ta entry is a Git submodule
542 is specified, list the repository path corresponding to the current
543 directory of the work tree, or the root directory of the repository
544 if there is no work tree.
551 List files and directories as they appear in the specified
553 The expected argument is a commit ID SHA1 hash or an existing reference
554 or tag name which will be resolved to a commit ID.
555 An abbreviated hash argument will be expanded to a full SHA1 hash
556 automatically, provided the abbreviation is unique.
557 .It Fl r Ar repository-path
558 Use the repository at the specified path.
559 If not specified, assume the repository is located at or above the current
561 If this directory is a
563 work tree, use the repository path associated with this work tree.
565 Show object IDs of files (blob objects) and directories (tree objects).
567 Recurse into sub-directories in the repository.
572 .It Cm ref Oo Fl r Ar repository-path Oc Oo Fl l Oc Oo Fl d Ar name Oc Oo Fl s Oc Op Ar name Ar target
573 Manage references in a repository.
575 If no options are passed, expect two arguments and attempt to create,
576 or update, the reference with the given
578 and make it point at the given
580 The name must be an absolute reference name, i.e. it must begin with
582 The target may be an object ID SHA1 hash or an existing reference which
583 will be resolved to an object ID.
584 An abbreviated hash argument will be expanded to a full SHA1 hash
585 automatically, provided the abbreviation is unique.
591 .It Fl r Ar repository-path
592 Use the repository at the specified path.
593 If not specified, assume the repository is located at or above the current
595 If this directory is a
597 work tree, use the repository path associated with this work tree.
599 List all existing references in the repository.
601 Delete the reference with the specified name from the repository.
603 Create a symbolic reference pointing at the specified
605 which must be an existing reference.
606 Care should be taken not to create loops between references when
609 .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
610 Create, list, or delete branches.
612 Branches are managed via references which live in the
617 command operates on references in this namespace only.
619 If invoked in a work tree without any arguments, print the name of the
620 work tree's current branch.
624 argument is passed, attempt to create a branch reference with the given name.
625 By default the new branch reference will point at the latest commit on the
626 work tree's current branch if invoked in a work tree, and otherwise to a commit
627 resolved via the repository's HEAD reference.
629 If invoked in a work tree, once the branch was created successfully
630 switch the work tree's head reference to the newly created branch and
631 update files across the entire work tree, just like
632 .Cm got update -b Ar name
634 Show the status of each affected file, using the following status codes:
635 .Bl -column YXZ description
636 .It U Ta file was updated and contained no local changes
637 .It G Ta file was updated and local changes were merged cleanly
638 .It C Ta file was updated and conflicts occurred during merge
639 .It D Ta file was deleted
640 .It A Ta new file was added
641 .It \(a~ Ta versioned file is obstructed by a non-regular file
642 .It ! Ta a missing versioned file was restored
650 Make a newly created branch reference point at the specified
654 argument is a commit ID SHA1 hash or an existing reference
655 or tag name which will be resolved to a commit ID.
656 .It Fl r Ar repository-path
657 Use the repository at the specified path.
658 If not specified, assume the repository is located at or above the current
660 If this directory is a
662 work tree, use the repository path associated with this work tree.
664 List all existing branches in the repository.
665 If invoked in a work tree, the work tree's current branch is shown
666 with one the following annotations:
667 .Bl -column YXZ description
668 .It * Ta work tree's base commit matches the branch tip
669 .It \(a~ Ta work tree's base commit is out-of-date
672 Delete the branch with the specified name from the repository.
673 Only the branch reference is deleted.
674 Any commit, tree, and blob objects belonging to the branch
675 remain in the repository and may be removed separately with
676 Git's garbage collector.
678 Do not switch and update the work tree after creating a new branch.
683 .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
684 Manage tags in a repository.
686 Tags are managed via references which live in the
691 command operates on references in this namespace only.
692 References in this namespace point at tag objects which contain a pointer
693 to another object, a tag message, as well as author and timestamp information.
695 Attempt to create a tag with the given
697 and make this tag point at the given
699 If no commit is specified, default to the latest commit on the work tree's
700 current branch if invoked in a work tree, and to a commit resolved via
701 the repository's HEAD reference otherwise.
708 Make the newly created tag reference point at the specified
712 argument is a commit ID SHA1 hash or an existing reference or tag name which
713 will be resolved to a commit ID.
714 An abbreviated hash argument will be expanded to a full SHA1 hash
715 automatically, provided the abbreviation is unique.
717 Use the specified tag message when creating the new tag.
722 opens a temporary file in an editor where a tag message can be written.
723 .It Fl r Ar repository-path
724 Use the repository at the specified path.
725 If not specified, assume the repository is located at or above the current
727 If this directory is a
729 work tree, use the repository path associated with this work tree.
731 List all existing tags in the repository instead of creating a new tag.
732 If this option is used, no other command-line arguments are allowed.
737 command will not delete tags or change existing tags.
738 If a tag must be deleted, the
740 command may be used to delete a tag's reference.
741 This should only be done if the tag has not already been copied to
743 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
744 Schedule unversioned files in a work tree for addition to the
745 repository in the next commit.
752 Permit recursion into directories.
753 If this option is not specified,
755 will refuse to run if a specified
759 With -R, add files even if they match a
763 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
764 Remove versioned files from a work tree and schedule them for deletion
765 from the repository in the next commit.
772 Perform the operation even if a file contains uncommitted modifications.
774 Keep affected files on disk.
776 Permit recursion into directories.
777 If this option is not specified,
779 will refuse to run if a specified
786 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
787 Revert any uncommitted changes in files at the specified paths.
788 File contents will be overwritten with those contained in the
789 work tree's base commit.
790 There is no way to bring discarded changes back after
793 If a file was added with
795 it will become an unversioned file again.
796 If a file was deleted with
805 Instead of reverting all changes in files, interactively select or reject
806 changes to revert based on
812 (quit reverting this file) responses.
813 If a file is in modified status, individual patches derived from the
814 modified file content can be reverted.
815 Files in added or deleted status may only be reverted in their entirety.
816 .It Fl F Ar response-script
824 responses line-by-line from the specified
826 file instead of prompting interactively.
828 Permit recursion into directories.
829 If this option is not specified,
831 will refuse to run if a specified
838 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
839 Create a new commit in the repository from changes in a work tree
840 and use this commit as the new base commit for the work tree.
843 is specified, commit all changes in the work tree.
844 Otherwise, commit changes at or within the specified paths.
846 If changes have been explicitly staged for commit with
848 only commit staged changes and reject any specified paths which
849 have not been staged.
851 Show the status of each affected file, using the following status codes:
852 .Bl -column YXZ description
853 .It M Ta modified file
854 .It D Ta file was deleted
855 .It A Ta new file was added
856 .It m Ta modified file modes (executable bit only)
859 Files which are not part of the new commit will retain their previously
860 recorded base commit.
863 commands may refuse to run while the work tree contains files from
864 multiple base commits.
865 The base commit of such a work tree can be made consistent by running
867 across the entire work tree.
873 environment variable to be set,
878 configuration settings can be
879 obtained from the repository's
881 file or from Git's global
890 Use the specified log message when creating the new commit.
895 opens a temporary file in an editor where a log message can be written.
899 will refuse to run if certain preconditions are not met.
900 If the work tree's current branch is not in the
902 reference namespace, new commits may not be created on this branch.
903 Local changes may only be committed if they are based on file content
904 found in the most recent commit on the work tree's branch.
905 If a path is found to be out of date,
907 must be used first in order to merge local changes with changes made
912 .It Cm cherrypick Ar commit
913 Merge changes from a single
918 must be on a different branch than the work tree's base commit.
919 The expected argument is a reference or a commit ID SHA1 hash.
920 An abbreviated hash argument will be expanded to a full SHA1 hash
921 automatically, provided the abbreviation is unique.
923 Show the status of each affected file, using the following status codes:
924 .Bl -column YXZ description
925 .It G Ta file was merged
926 .It C Ta file was merged and conflicts occurred during merge
927 .It ! Ta changes destined for a missing file were not merged
928 .It D Ta file was deleted
929 .It d Ta file's deletion was obstructed by local modifications
930 .It A Ta new file was added
931 .It \(a~ Ta changes destined for a non-regular file were not merged
934 The merged changes will appear as local changes in the work tree, which
937 amended manually or with further
942 or discarded again with
946 will refuse to run if certain preconditions are not met.
947 If the work tree contains multiple base commits it must first be updated
948 to a single base commit with
950 If the work tree already contains files with merge conflicts, these
951 conflicts must be resolved first.
955 .It Cm backout Ar commit
956 Reverse-merge changes from a single
961 must be on the same branch as the work tree's base commit.
962 The expected argument is a reference or a commit ID SHA1 hash.
963 An abbreviated hash argument will be expanded to a full SHA1 hash
964 automatically, provided the abbreviation is unique.
966 Show the status of each affected file, using the following status codes:
967 .Bl -column YXZ description
968 .It G Ta file was merged
969 .It C Ta file was merged and conflicts occurred during merge
970 .It ! Ta changes destined for a missing file were not merged
971 .It D Ta file was deleted
972 .It d Ta file's deletion was obstructed by local modifications
973 .It A Ta new file was added
974 .It \(a~ Ta changes destined for a non-regular file were not merged
977 The reverse-merged changes will appear as local changes in the work tree,
978 which may be viewed with
980 amended manually or with further
985 or discarded again with
989 will refuse to run if certain preconditions are not met.
990 If the work tree contains multiple base commits it must first be updated
991 to a single base commit with
993 If the work tree already contains files with merge conflicts, these
994 conflicts must be resolved first.
998 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
999 Rebase commits on the specified
1001 onto the tip of the current branch of the work tree.
1004 must share common ancestry with the work tree's current branch.
1005 Rebasing begins with the first descendant commit of the youngest
1006 common ancestor commit shared by the specified
1008 and the work tree's current branch, and stops once the tip commit
1015 is used as intended, the specified
1017 represents a local commit history and may already contain changes
1018 that are not yet visible in any other repositories.
1019 The work tree's current branch, which must be set with
1023 operation, represents a branch from a remote repository which shares
1024 a common history with the specified
1026 but has progressed, and perhaps diverged, due to commits added to the
1029 Rebased commits are accumulated on a temporary branch which the work tree
1030 will remain switched to throughout the entire rebase operation.
1031 Commits on this branch represent the same changes with the same log
1032 messages as their counterparts on the original
1034 but with different commit IDs.
1035 Once rebasing has completed successfully, the temporary branch becomes
1036 the new version of the specified
1038 and the work tree is automatically switched to it.
1040 While rebasing commits, show the status of each affected file,
1041 using the following status codes:
1042 .Bl -column YXZ description
1043 .It G Ta file was merged
1044 .It C Ta file was merged and conflicts occurred during merge
1045 .It ! Ta changes destined for a missing file were not merged
1046 .It D Ta file was deleted
1047 .It d Ta file's deletion was obstructed by local modifications
1048 .It A Ta new file was added
1049 .It \(a~ Ta changes destined for a non-regular file were not merged
1052 If merge conflicts occur the rebase operation is interrupted and may
1053 be continued once conflicts have been resolved.
1054 Alternatively, the rebase operation may be aborted which will leave
1056 unmodified and the work tree switched back to its original branch.
1058 If a merge conflict is resolved in a way which renders the merged
1059 change into a no-op change, the corresponding commit will be elided
1060 when the rebase operation continues.
1063 will refuse to run if certain preconditions are not met.
1064 If the work tree is not yet fully updated to the tip commit of its
1065 branch then the work tree must first be updated with
1067 If changes have been staged with
1069 these changes must first be committed with
1073 If the work tree contains local changes, these changes must first be
1080 contains changes to files outside of the work tree's path prefix,
1081 the work tree cannot be used to rebase this branch.
1087 commands will refuse to run while a rebase operation is in progress.
1088 Other commands which manipulate the work tree may be used for
1089 conflict resolution purposes.
1096 Abort an interrupted rebase operation.
1097 If this option is used, no other command-line arguments are allowed.
1099 Continue an interrupted rebase operation.
1100 If this option is used, no other command-line arguments are allowed.
1105 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1106 Edit commit history between the work tree's current base commit and
1107 the tip commit of the work tree's current branch.
1111 operation the work tree's current branch must be set with
1113 to the branch which should be edited, unless this branch is already the
1114 current branch of the work tree.
1115 The tip of this branch represents the upper bound (inclusive) of commits
1120 Furthermore, the work tree's base commit
1123 to a point in this branch's commit history where editing should begin.
1124 This commit represents the lower bound (non-inclusive) of commits touched
1129 Editing of commit history is controlled via a
1131 which can be written in an editor based on a template, passed on the
1132 command line, or generated with the
1134 option if only log messages need to be edited.
1136 The format of the histedit script is line-based.
1137 Each line in the script begins with a command name, followed by
1138 whitespace and an argument.
1139 For most commands, the expected argument is a commit ID SHA1 hash.
1140 Any remaining text on the line is ignored.
1141 Lines which begin with the
1143 character are ignored entirely.
1145 The available commands are as follows:
1146 .Bl -column YXZ pick-commit
1147 .It pick Ar commit Ta Use the specified commit as it is.
1148 .It edit Ar commit Ta Use the specified commit but once changes have been
1149 merged into the work tree interrupt the histedit operation for amending.
1150 .It fold Ar commit Ta Combine the specified commit with the next commit
1151 listed further below that will be used.
1152 .It drop Ar commit Ta Remove this commit from the edited history.
1153 .It mesg Ar log-message Ta Use the specified single-line log message for
1154 the commit on the previous line.
1155 If the log message argument is left empty, open an editor where a new
1156 log message can be written.
1159 Every commit in the history being edited must be mentioned in the script.
1160 Lines may be re-ordered to change the order of commits in the edited history.
1161 No commit may be listed more than once.
1163 Edited commits are accumulated on a temporary branch which the work tree
1164 will remain switched to throughout the entire histedit operation.
1165 Once history editing has completed successfully, the temporary branch becomes
1166 the new version of the work tree's branch and the work tree is automatically
1169 While merging commits, show the status of each affected file,
1170 using the following status codes:
1171 .Bl -column YXZ description
1172 .It G Ta file was merged
1173 .It C Ta file was merged and conflicts occurred during merge
1174 .It ! Ta changes destined for a missing file were not merged
1175 .It D Ta file was deleted
1176 .It d Ta file's deletion was obstructed by local modifications
1177 .It A Ta new file was added
1178 .It \(a~ Ta changes destined for a non-regular file were not merged
1181 If merge conflicts occur the histedit operation is interrupted and may
1182 be continued once conflicts have been resolved.
1183 Alternatively, the histedit operation may be aborted which will leave
1184 the work tree switched back to its original branch.
1186 If a merge conflict is resolved in a way which renders the merged
1187 change into a no-op change, the corresponding commit will be elided
1188 when the histedit operation continues.
1191 will refuse to run if certain preconditions are not met.
1192 If the work tree's current branch is not in the
1194 reference namespace, the history of the branch may not be edited.
1195 If the work tree contains multiple base commits it must first be updated
1196 to a single base commit with
1198 If changes have been staged with
1200 these changes must first be committed with
1204 If the work tree contains local changes, these changes must first be
1209 If the edited history contains changes to files outside of the work tree's
1210 path prefix, the work tree cannot be used to edit the history of this branch.
1217 commands will refuse to run while a histedit operation is in progress.
1218 Other commands which manipulate the work tree may be used, and the
1220 command may be used to commit arbitrary changes to the temporary branch
1221 while the histedit operation is interrupted.
1228 Abort an interrupted histedit operation.
1229 If this option is used, no other command-line arguments are allowed.
1231 Continue an interrupted histedit operation.
1232 If this option is used, no other command-line arguments are allowed.
1233 .It Fl F Ar histedit-script
1236 instead of opening a temporary file in an editor where a histedit script
1239 Edit log messages only.
1240 This option is a quick equivalent to a histedit script which edits
1241 only log messages but otherwise leaves every picked commit as-is.
1244 option can only be used when starting a new histedit operation.
1245 If this option is used, no other command-line arguments are allowed.
1250 .It Cm integrate Ar branch
1251 Integrate the specified
1253 into the work tree's current branch.
1254 Files in the work tree are updated to match the contents on the integrated
1256 and the reference of the work tree's branch is changed to point at the
1257 head commit of the integrated
1260 Both branches can be considered equivalent after integration since they
1261 will be pointing at the same commit.
1262 Both branches remain available for future work, if desired.
1263 In case the integrated
1265 is no longer needed it may be deleted with
1268 Show the status of each affected file, using the following status codes:
1269 .Bl -column YXZ description
1270 .It U Ta file was updated
1271 .It D Ta file was deleted
1272 .It A Ta new file was added
1273 .It \(a~ Ta versioned file is obstructed by a non-regular file
1274 .It ! Ta a missing versioned file was restored
1278 will refuse to run if certain preconditions are not met.
1279 Most importantly, the
1281 must have been rebased onto the work tree's current branch with
1283 before it can be integrated, in order to linearize commit history and
1284 resolve merge conflicts.
1285 If the work tree contains multiple base commits it must first be updated
1286 to a single base commit with
1288 If changes have been staged with
1290 these changes must first be committed with
1294 If the work tree contains local changes, these changes must first be
1302 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1303 Stage local changes for inclusion in the next commit.
1306 is specified, stage all changes in the work tree.
1307 Otherwise, stage changes at or within the specified paths.
1308 Paths may be staged if they are added, modified, or deleted according to
1311 Show the status of each affected file, using the following status codes:
1312 .Bl -column YXZ description
1313 .It A Ta file addition has been staged
1314 .It M Ta file modification has been staged
1315 .It D Ta file deletion has been staged
1318 Staged file contents are saved in newly created blob objects in the repository.
1319 These blobs will be referred to by tree objects once staged changes have been
1322 Staged changes affect the behaviour of
1327 While paths with staged changes exist, the
1329 command will refuse to commit any paths which do not have staged changes.
1330 Local changes created on top of staged changes can only be committed if
1331 the path is staged again, or if the staged changes are committed first.
1334 command will show both local changes and staged changes.
1337 command is able to display local changes relative to staged changes,
1338 and to display staged changes relative to the repository.
1341 command cannot revert staged changes but may be used to revert
1342 local changes created on top of staged changes.
1349 Instead of staging new changes, list paths which are already staged,
1350 along with the IDs of staged blob objects and stage status codes.
1351 If paths were provided in the command line show the staged paths
1352 among the specified paths.
1353 Otherwise, show all staged paths.
1355 Instead of staging the entire content of a changed file, interactively
1356 select or reject changes for staging based on
1360 (reject change), and
1362 (quit staging this file) responses.
1363 If a file is in modified status, individual patches derived from the
1364 modified file content can be staged.
1365 Files in added or deleted status may only be staged or rejected in
1367 .It Fl F Ar response-script
1375 responses line-by-line from the specified
1377 file instead of prompting interactively.
1381 will refuse to run if certain preconditions are not met.
1382 If a file contains merge conflicts, these conflicts must be resolved first.
1383 If a file is found to be out of date relative to the head commit on the
1384 work tree's current branch, the file must be updated with
1386 before it can be staged (however, this does not prevent the file from
1387 becoming out-of-date at some point after having been staged).
1394 commands will refuse to run while staged changes exist.
1395 If staged changes cannot be committed because a staged path
1396 is out of date, the path must be unstaged with
1398 before it can be updated with
1400 and may then be staged again if necessary.
1404 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1405 Merge staged changes back into the work tree and put affected paths
1406 back into non-staged status.
1409 is specified, unstage all staged changes across the entire work tree.
1410 Otherwise, unstage changes at or within the specified paths.
1412 Show the status of each affected file, using the following status codes:
1413 .Bl -column YXZ description
1414 .It G Ta file was unstaged
1415 .It C Ta file was unstaged and conflicts occurred during merge
1416 .It ! Ta changes destined for a missing file were not merged
1417 .It D Ta file was staged as deleted and still is deleted
1418 .It d Ta file's deletion was obstructed by local modifications
1419 .It \(a~ Ta changes destined for a non-regular file were not merged
1427 Instead of unstaging the entire content of a changed file, interactively
1428 select or reject changes for unstaging based on
1432 (keep change staged), and
1434 (quit unstaging this file) responses.
1435 If a file is staged in modified status, individual patches derived from the
1436 staged file content can be unstaged.
1437 Files staged in added or deleted status may only be unstaged in their entirety.
1438 .It Fl F Ar response-script
1446 responses line-by-line from the specified
1448 file instead of prompting interactively.
1453 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1454 Parse and print contents of objects to standard output in a line-based
1456 Content of commit, tree, and tag objects is printed in a way similar
1457 to the actual content stored in such objects.
1458 Blob object contents are printed as they would appear in files on disk.
1460 Attempt to interpret each argument as a reference, a tag name, or
1461 an object ID SHA1 hash.
1462 References will be resolved to an object ID.
1463 Tag names will resolved to a tag object.
1464 An abbreviated hash argument will be expanded to a full SHA1 hash
1465 automatically, provided the abbreviation is unique.
1467 If none of the above interpretations produce a valid result, or if the
1469 option is used, attempt to interpret the argument as a path which will
1470 be resolved to the ID of an object found at this path in the repository.
1477 Look up paths in the specified
1479 If this option is not used, paths are looked up in the commit resolved
1480 via the repository's HEAD reference.
1481 The expected argument is a commit ID SHA1 hash or an existing reference
1482 or tag name which will be resolved to a commit ID.
1483 An abbreviated hash argument will be expanded to a full SHA1 hash
1484 automatically, provided the abbreviation is unique.
1485 .It Fl r Ar repository-path
1486 Use the repository at the specified path.
1487 If not specified, assume the repository is located at or above the current
1489 If this directory is a
1491 work tree, use the repository path associated with this work tree.
1493 Interpret all arguments as paths only.
1494 This option can be used to resolve ambiguity in cases where paths
1495 look like tag names, reference names, or object IDs.
1499 .Bl -tag -width GOT_AUTHOR
1501 The author's name and email address for
1506 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1509 may fail to parse commits without an email address in author data,
1513 environment variables with a missing email address.
1519 configuration settings in the repository's
1521 file will override the value of
1527 configuration settings contained in Git's global
1529 configuration file will be used only if the
1531 environment variable is
1534 .It Ev VISUAL , EDITOR
1535 The editor spawned by
1540 .It Ev GOT_LOG_DEFAULT_LIMIT
1541 The default limit on the number of commits traversed by
1543 If set to zero, the limit is unbounded.
1544 This variable will be silently ignored if it is set to a non-numeric value.
1549 Clone an existing Git repository for use with
1553 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1555 Use of HTTP URLs currently requires
1559 .Dl $ git clone --bare https://github.com/openbsd/src.git
1561 Alternatively, for quick and dirty local testing of
1563 a new Git repository could be created and populated with files,
1564 e.g. from a temporary CVS checkout located at
1567 .Dl $ got init /var/git/src.git
1568 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1570 Check out a work tree from the Git repository to /usr/src:
1572 .Dl $ got checkout /var/git/src.git /usr/src
1574 View local changes in a work tree directory:
1577 .Dl $ got diff | less
1579 Interactively revert selected local changes in a work tree directory:
1581 .Dl $ got revert -p -R\ .
1583 In a work tree or a git repository directory, list all branch references:
1587 In a work tree or a git repository directory, create a new branch called
1588 .Dq unified-buffer-cache
1589 which is forked off the
1593 .Dl $ got branch unified-buffer-cache master
1595 Switch an existing work tree to the branch
1596 .Dq unified-buffer-cache .
1597 Local changes in the work tree will be preserved and merged if necessary:
1599 .Dl $ got update -b unified-buffer-cache
1601 Create a new commit from local changes in a work tree directory.
1602 This new commit will become the head commit of the work tree's current branch:
1606 In a work tree or a git repository directory, view changes committed in
1607 the 3 most recent commits to the work tree's branch, or the branch resolved
1608 via the repository's HEAD reference, respectively:
1610 .Dl $ got log -p -l 3
1612 In a work tree or a git repository directory, log the history of a subdirectory:
1614 .Dl $ got log sys/uvm
1616 While operating inside a work tree, paths are specified relative to the current
1617 working directory, so this command will log the subdirectory
1620 .Dl $ cd sys/uvm && got log '.'
1622 And this command has the same effect:
1624 .Dl $ cd sys/dev/usb && got log ../../uvm
1626 Add new files and remove obsolete files in a work tree directory:
1628 .Dl $ got add sys/uvm/uvm_ubc.c
1629 .Dl $ got remove sys/uvm/uvm_vnode.c
1631 Create a new commit from local changes in a work tree directory
1632 with a pre-defined log message.
1634 .Dl $ got commit -m 'unify the buffer cache'
1636 Update any work tree checked out from the
1637 .Dq unified-buffer-cache
1638 branch to the latest commit on this branch:
1642 Roll file content on the unified-buffer-cache branch back by one commit,
1643 and then fetch the rolled-back change into the work tree as a local change
1644 to be amended and perhaps committed again:
1646 .Dl $ got backout unified-buffer-cache
1647 .Dl $ got commit -m 'roll back previous'
1648 .Dl $ # now back out the previous backout :-)
1649 .Dl $ got backout unified-buffer-cache
1651 Fetch new upstream commits into the local repository's master branch.
1652 This step currently requires
1655 .Dl $ cd /var/git/src.git
1656 .Dl $ git fetch origin master:master
1659 .Dq unified-buffer-cache
1660 branch on top of the new head commit of the
1664 .Dl $ got update -b master
1665 .Dl $ got rebase unified-buffer-cache
1667 Create a patch from all changes on the unified-buffer-cache branch.
1668 The patch can be mailed out for review and applied to
1672 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1674 Edit the entire commit history of the
1675 .Dq unified-buffer-cache
1678 .Dl $ got update -b unified-buffer-cache
1679 .Dl $ got update -c master
1682 Additional steps are necessary if local changes need to be pushed back
1683 to the remote repository, which currently requires
1687 Before working against existing branches in a repository cloned with
1688 .Dq git clone --bare ,
1691 must be configured to map all references in the remote repository
1694 namespace of the local repository.
1695 This can achieved by setting Git's
1696 .Pa remote.origin.fetch
1697 configuration variable to the value
1698 .Dq +refs/heads/*:refs/remotes/origin/*
1703 .Dl $ cd /var/git/repo
1704 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1706 Alternatively, the following
1708 configuration item can be added manually to the Git repository's
1712 .Dl [remote "origin"]
1714 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
1716 This configuration leaves the local repository's
1718 namespace free for use by local branches checked out with
1720 and, if needed, created with
1725 namespace can be updated with incoming changes from the remote
1729 .Dl $ cd /var/git/repo
1732 To make changes fetched from the remote repository appear on the
1736 branch must be rebased onto the
1739 This will also merge local changes, if any, with the incoming changes:
1741 .Dl $ got update -b origin/master
1742 .Dl $ got rebase master
1746 branch, log messages for local changes can now be amended with
1748 by other developers and any other important new information:
1750 .Dl $ got update -c origin/master
1751 .Dl $ got histedit -m
1753 Local changes on the
1755 branch can then be pushed to the remote
1759 .Dl $ cd /var/git/repo
1760 .Dl $ git push origin master
1762 In order to merge changes committed to the
1763 .Dq unified-buffer-cache
1764 branch back into the
1767 .Dq unified-buffer-cache
1768 branch must first be rebased onto the
1772 .Dl $ got update -b master
1773 .Dl $ got rebase unified-buffer-cache
1776 .Dq unified-buffer-cache
1777 branch can now be made visible on the
1781 Because the rebase operation switched the work tree to the
1782 .Dq unified-buffer-cache
1783 branch, the work tree must be switched back to the
1786 .Dq unified-buffer-cache
1787 branch can be integrated into
1790 .Dl $ got update -b master
1791 .Dl $ got integrate unified-buffer-cache
1794 .Xr git-repository 5 ,
1797 .An Stefan Sperling Aq Mt stsp@openbsd.org
1798 .An Martin Pieuchot Aq Mt mpi@openbsd.org
1799 .An Joshua Stein Aq Mt jcs@openbsd.org
1800 .An Ori Bernstein Aq Mt ori@openbsd.org
1803 is a work-in-progress and many commands remain to be implemented.
1804 At present, the user has to fall back on
1806 to perform many tasks, in particular tasks related to repository
1807 administration and tasks which require a network connection.
