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.
180 creates a remote repository entry in the
182 file of the cloned repository to store the
194 Suppress progress reporting output.
195 The same option will be passed to
199 Increase the verbosity of progress reporting output.
200 The same option will be passed to
203 Multiple -v options increase the verbosity.
209 .It Cm fetch Oo Fl r Ar repository-path Oc Oo Fl q Oc Oo Fl v Oc Op Ar remote-repository-name
210 Fetch new changes from a remote repository.
212 .Ar remote-repository-name
213 is specified the name
216 The remote repository's URL is obtained from the corresponding entry in the
218 file of the repository, as created by
221 Branch references in the
223 reference namespace will be updated to point at the newly fetched commits.
226 command can then be used to make new changes visible on branches in the
230 Existing references in the
232 namespace will be changed to match tags contained in the remote repository.
238 .It Fl r Ar repository-path
239 Use the repository at the specified path.
240 If not specified, assume the repository is located at or above the current
242 If this directory is a
244 work tree, use the repository path associated with this work tree.
246 Suppress progress reporting output.
247 The same option will be passed to
251 Increase the verbosity of progress reporting output.
252 The same option will be passed to
255 Multiple -v options increase the verbosity.
261 .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
262 Copy files from a repository into a new work tree.
263 Show the status of each affected file, using the following status codes:
264 .Bl -column YXZ description
265 .It A Ta new file was added
266 .It E Ta file already exists in work tree's meta-data
271 is not specified, either use the last component of
272 .Ar repository path ,
275 was specified use the last component of
283 Proceed with the checkout operation even if the directory at
286 Existing files will be left intact.
288 Check out files from a commit on the specified
290 If this option is not specified, a branch resolved via the repository's HEAD
291 reference will be used.
293 Check out files from the specified
295 on the selected branch.
296 The expected argument is a commit ID SHA1 hash or an existing reference
297 or tag name which will be resolved to a commit ID.
298 An abbreviated hash argument will be expanded to a full SHA1 hash
299 automatically, provided the abbreviation is unique.
300 If this option is not specified, the most recent commit on the selected
305 is not contained in the selected branch, a different branch which contains
306 this commit must be specified with the
309 If no such branch is known a new branch must be created for this
315 Checking out work trees with an unknown branch is intentionally not supported.
316 .It Fl p Ar path-prefix
317 Restrict the work tree to a subset of the repository's tree hierarchy.
318 Only files beneath the specified
325 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
326 Update an existing work tree to a different commit.
327 Show the status of each affected file, using the following status codes:
328 .Bl -column YXZ description
329 .It U Ta file was updated and contained no local changes
330 .It G Ta file was updated and local changes were merged cleanly
331 .It C Ta file was updated and conflicts occurred during merge
332 .It D Ta file was deleted
333 .It A Ta new file was added
334 .It \(a~ Ta versioned file is obstructed by a non-regular file
335 .It ! Ta a missing versioned file was restored
340 is specified, update the entire work tree.
341 Otherwise, restrict the update operation to files at or within the
343 Each path is required to exist in the update operation's target commit.
344 Files in the work tree outside specified paths will remain unchanged and
345 will retain their previously recorded base commit.
348 commands may refuse to run while the work tree contains files from
349 multiple base commits.
350 The base commit of such a work tree can be made consistent by running
352 across the entire work tree.
355 is incompatible with the
360 cannot update paths with staged changes.
361 If changes have been staged with
363 these changes must first be committed with
373 Switch the work tree's branch reference to the specified
375 before updating the work tree.
376 This option requires that all paths in the work tree are updated.
378 Update the work tree to the specified
380 The expected argument is a commit ID SHA1 hash or an existing reference
381 or tag name which will be resolved to a commit ID.
382 An abbreviated hash argument will be expanded to a full SHA1 hash
383 automatically, provided the abbreviation is unique.
384 If this option is not specified, the most recent commit on the work tree's
390 .It Cm status Op Ar path ...
391 Show the current modification status of files in a work tree,
392 using the following status codes:
393 .Bl -column YXZ description
394 .It M Ta modified file
395 .It A Ta file scheduled for addition in next commit
396 .It D Ta file scheduled for deletion in next commit
397 .It C Ta modified or added file which contains merge conflicts
398 .It ! Ta versioned file was expected on disk but is missing
399 .It \(a~ Ta versioned file is obstructed by a non-regular file
400 .It ? Ta unversioned item not tracked by
402 .It m Ta modified file modes (executable bit only)
403 .It N Ta non-existent
405 specified on the command line
410 is specified, show modifications in the entire work tree.
411 Otherwise, show modifications at or within the specified paths.
413 If changes have been staged with
415 staged changes are shown in the second output column, using the following
417 .Bl -column YXZ description
418 .It M Ta file modification is staged
419 .It A Ta file addition is staged
420 .It D Ta file deletion is staged
423 Changes created on top of staged changes are indicated in the first column:
424 .Bl -column YXZ description
425 .It MM Ta file was modified after earlier changes have been staged
426 .It MA Ta file was modified after having been staged for addition
429 For compatibility with
440 files in each traversed directory and will not display unversioned files
441 which match these patterns.
446 supports consecutive asterisks,
448 which will match an arbitrary amount of directories.
452 only supports a single ignore pattern per line.
456 does not support negated ignore patterns prefixed with
458 and gives no special significance to the location of path component separators,
464 .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
465 Display history of a repository.
468 is specified, show only commits which modified this path.
469 If invoked in a work tree, the
471 is interpreted relative to the current working directory,
472 and the work tree's path prefix is implicitly prepended.
473 Otherwise, the path is interpreted relative to the repository root.
480 Display individual commits which were merged into the current branch
484 shows the linear history of the current branch only.
486 Start traversing history at the specified
488 The expected argument is a commit ID SHA1 hash or an existing reference
489 or tag name which will be resolved to a commit ID.
490 An abbreviated hash argument will be expanded to a full SHA1 hash
491 automatically, provided the abbreviation is unique.
492 If this option is not specified, default to the work tree's current branch
493 if invoked in a work tree, or to the repository's HEAD reference.
495 Set the number of context lines shown in diffs with
497 By default, 3 lines of context are shown.
499 Limit history traversal to a given number of commits.
500 If this option is not specified, a default limit value of zero is used,
501 which is treated as an unbounded limit.
503 .Ev GOT_LOG_DEFAULT_LIMIT
504 environment variable may be set to change this default value.
506 Display the patch of modifications made in each commit.
509 is specified, only show the patch of modifications at or within this path.
510 .It Fl s Ar search-pattern
511 If specified, show only commits with a log message matched by the extended
514 Regular expression syntax is documented in
516 .It Fl r Ar repository-path
517 Use the repository at the specified path.
518 If not specified, assume the repository is located at or above the current
520 If this directory is a
522 work tree, use the repository path associated with this work tree.
524 .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
525 When invoked within a work tree with less than two arguments, display
526 uncommitted changes in the work tree.
529 is specified, only show changes within this path.
531 If two arguments are provided, treat each argument as a reference, a tag
532 name, or an object ID SHA1 hash, and display differences between the
533 corresponding objects.
534 Both objects must be of the same type (blobs, trees, or commits).
535 An abbreviated hash argument will be expanded to a full SHA1 hash
536 automatically, provided the abbreviation is unique.
543 Set the number of context lines shown in the diff.
544 By default, 3 lines of context are shown.
545 .It Fl r Ar repository-path
546 Use the repository at the specified path.
547 If not specified, assume the repository is located at or above the current
549 If this directory is a
551 work tree, use the repository path associated with this work tree.
553 Show changes staged with
555 instead of showing local changes.
556 This option is only valid when
558 is invoked in a work tree.
560 Ignore whitespace-only changes.
565 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
566 Display line-by-line history of a file at the specified path.
573 Start traversing history at the specified
575 The expected argument is a commit ID SHA1 hash or an existing reference
576 or tag name which will be resolved to a commit ID.
577 An abbreviated hash argument will be expanded to a full SHA1 hash
578 automatically, provided the abbreviation is unique.
579 .It Fl r Ar repository-path
580 Use the repository at the specified path.
581 If not specified, assume the repository is located at or above the current
583 If this directory is a
585 work tree, use the repository path associated with this work tree.
590 .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
591 Display a listing of files and directories at the specified
592 directory path in the repository.
593 Entries shown in this listing may carry one of the following trailing
595 .Bl -column YXZ description
596 .It @ Ta entry is a symbolic link
597 .It / Ta entry is a directory
598 .It * Ta entry is an executable file
599 .It $ Ta entry is a Git submodule
604 is specified, list the repository path corresponding to the current
605 directory of the work tree, or the root directory of the repository
606 if there is no work tree.
613 List files and directories as they appear in the specified
615 The expected argument is a commit ID SHA1 hash or an existing reference
616 or tag name which will be resolved to a commit ID.
617 An abbreviated hash argument will be expanded to a full SHA1 hash
618 automatically, provided the abbreviation is unique.
619 .It Fl r Ar repository-path
620 Use the repository at the specified path.
621 If not specified, assume the repository is located at or above the current
623 If this directory is a
625 work tree, use the repository path associated with this work tree.
627 Show object IDs of files (blob objects) and directories (tree objects).
629 Recurse into sub-directories in the repository.
634 .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
635 Manage references in a repository.
637 If no options are passed, expect two arguments and attempt to create,
638 or update, the reference with the given
640 and make it point at the given
642 The name must be an absolute reference name, i.e. it must begin with
644 The target may be an object ID SHA1 hash or an existing reference which
645 will be resolved to an object ID.
646 An abbreviated hash argument will be expanded to a full SHA1 hash
647 automatically, provided the abbreviation is unique.
653 .It Fl r Ar repository-path
654 Use the repository at the specified path.
655 If not specified, assume the repository is located at or above the current
657 If this directory is a
659 work tree, use the repository path associated with this work tree.
661 List all existing references in the repository.
663 Delete the reference with the specified name from the repository.
665 Create a symbolic reference pointing at the specified
667 which must be an existing reference.
668 Care should be taken not to create loops between references when
671 .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
672 Create, list, or delete branches.
674 Branches are managed via references which live in the
679 command operates on references in this namespace only.
681 If invoked in a work tree without any arguments, print the name of the
682 work tree's current branch.
686 argument is passed, attempt to create a branch reference with the given name.
687 By default the new branch reference will point at the latest commit on the
688 work tree's current branch if invoked in a work tree, and otherwise to a commit
689 resolved via the repository's HEAD reference.
691 If invoked in a work tree, once the branch was created successfully
692 switch the work tree's head reference to the newly created branch and
693 update files across the entire work tree, just like
694 .Cm got update -b Ar name
696 Show the status of each affected file, using the following status codes:
697 .Bl -column YXZ description
698 .It U Ta file was updated and contained no local changes
699 .It G Ta file was updated and local changes were merged cleanly
700 .It C Ta file was updated and conflicts occurred during merge
701 .It D Ta file was deleted
702 .It A Ta new file was added
703 .It \(a~ Ta versioned file is obstructed by a non-regular file
704 .It ! Ta a missing versioned file was restored
712 Make a newly created branch reference point at the specified
716 argument is a commit ID SHA1 hash or an existing reference
717 or tag name which will be resolved to a commit ID.
718 .It Fl r Ar repository-path
719 Use the repository at the specified path.
720 If not specified, assume the repository is located at or above the current
722 If this directory is a
724 work tree, use the repository path associated with this work tree.
726 List all existing branches in the repository.
727 If invoked in a work tree, the work tree's current branch is shown
728 with one the following annotations:
729 .Bl -column YXZ description
730 .It * Ta work tree's base commit matches the branch tip
731 .It \(a~ Ta work tree's base commit is out-of-date
734 Delete the branch with the specified name from the repository.
735 Only the branch reference is deleted.
736 Any commit, tree, and blob objects belonging to the branch
737 remain in the repository and may be removed separately with
738 Git's garbage collector.
740 Do not switch and update the work tree after creating a new branch.
745 .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
746 Manage tags in a repository.
748 Tags are managed via references which live in the
753 command operates on references in this namespace only.
754 References in this namespace point at tag objects which contain a pointer
755 to another object, a tag message, as well as author and timestamp information.
757 Attempt to create a tag with the given
759 and make this tag point at the given
761 If no commit is specified, default to the latest commit on the work tree's
762 current branch if invoked in a work tree, and to a commit resolved via
763 the repository's HEAD reference otherwise.
770 Make the newly created tag reference point at the specified
774 argument is a commit ID SHA1 hash or an existing reference or tag name which
775 will be resolved to a commit ID.
776 An abbreviated hash argument will be expanded to a full SHA1 hash
777 automatically, provided the abbreviation is unique.
779 Use the specified tag message when creating the new tag.
784 opens a temporary file in an editor where a tag message can be written.
785 .It Fl r Ar repository-path
786 Use the repository at the specified path.
787 If not specified, assume the repository is located at or above the current
789 If this directory is a
791 work tree, use the repository path associated with this work tree.
793 List all existing tags in the repository instead of creating a new tag.
794 If this option is used, no other command-line arguments are allowed.
799 command will not delete tags or change existing tags.
800 If a tag must be deleted, the
802 command may be used to delete a tag's reference.
803 This should only be done if the tag has not already been copied to
805 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
806 Schedule unversioned files in a work tree for addition to the
807 repository in the next commit.
814 Permit recursion into directories.
815 If this option is not specified,
817 will refuse to run if a specified
821 With -R, add files even if they match a
825 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
826 Remove versioned files from a work tree and schedule them for deletion
827 from the repository in the next commit.
834 Perform the operation even if a file contains uncommitted modifications.
836 Keep affected files on disk.
838 Permit recursion into directories.
839 If this option is not specified,
841 will refuse to run if a specified
848 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
849 Revert any uncommitted changes in files at the specified paths.
850 File contents will be overwritten with those contained in the
851 work tree's base commit.
852 There is no way to bring discarded changes back after
855 If a file was added with
857 it will become an unversioned file again.
858 If a file was deleted with
867 Instead of reverting all changes in files, interactively select or reject
868 changes to revert based on
874 (quit reverting this file) responses.
875 If a file is in modified status, individual patches derived from the
876 modified file content can be reverted.
877 Files in added or deleted status may only be reverted in their entirety.
878 .It Fl F Ar response-script
886 responses line-by-line from the specified
888 file instead of prompting interactively.
890 Permit recursion into directories.
891 If this option is not specified,
893 will refuse to run if a specified
900 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
901 Create a new commit in the repository from changes in a work tree
902 and use this commit as the new base commit for the work tree.
905 is specified, commit all changes in the work tree.
906 Otherwise, commit changes at or within the specified paths.
908 If changes have been explicitly staged for commit with
910 only commit staged changes and reject any specified paths which
911 have not been staged.
913 Show the status of each affected file, using the following status codes:
914 .Bl -column YXZ description
915 .It M Ta modified file
916 .It D Ta file was deleted
917 .It A Ta new file was added
918 .It m Ta modified file modes (executable bit only)
921 Files which are not part of the new commit will retain their previously
922 recorded base commit.
925 commands may refuse to run while the work tree contains files from
926 multiple base commits.
927 The base commit of such a work tree can be made consistent by running
929 across the entire work tree.
935 environment variable to be set,
940 configuration settings can be
941 obtained from the repository's
943 file or from Git's global
952 Use the specified log message when creating the new commit.
957 opens a temporary file in an editor where a log message can be written.
961 will refuse to run if certain preconditions are not met.
962 If the work tree's current branch is not in the
964 reference namespace, new commits may not be created on this branch.
965 Local changes may only be committed if they are based on file content
966 found in the most recent commit on the work tree's branch.
967 If a path is found to be out of date,
969 must be used first in order to merge local changes with changes made
974 .It Cm cherrypick Ar commit
975 Merge changes from a single
980 must be on a different branch than the work tree's base commit.
981 The expected argument is a reference or a commit ID SHA1 hash.
982 An abbreviated hash argument will be expanded to a full SHA1 hash
983 automatically, provided the abbreviation is unique.
985 Show the status of each affected file, using the following status codes:
986 .Bl -column YXZ description
987 .It G Ta file was merged
988 .It C Ta file was merged and conflicts occurred during merge
989 .It ! Ta changes destined for a missing file were not merged
990 .It D Ta file was deleted
991 .It d Ta file's deletion was obstructed by local modifications
992 .It A Ta new file was added
993 .It \(a~ Ta changes destined for a non-regular file were not merged
996 The merged changes will appear as local changes in the work tree, which
999 amended manually or with further
1004 or discarded again with
1008 will refuse to run if certain preconditions are not met.
1009 If the work tree contains multiple base commits it must first be updated
1010 to a single base commit with
1012 If the work tree already contains files with merge conflicts, these
1013 conflicts must be resolved first.
1017 .It Cm backout Ar commit
1018 Reverse-merge changes from a single
1023 must be on the same branch as the work tree's base commit.
1024 The expected argument is a reference or a commit ID SHA1 hash.
1025 An abbreviated hash argument will be expanded to a full SHA1 hash
1026 automatically, provided the abbreviation is unique.
1028 Show the status of each affected file, using the following status codes:
1029 .Bl -column YXZ description
1030 .It G Ta file was merged
1031 .It C Ta file was merged and conflicts occurred during merge
1032 .It ! Ta changes destined for a missing file were not merged
1033 .It D Ta file was deleted
1034 .It d Ta file's deletion was obstructed by local modifications
1035 .It A Ta new file was added
1036 .It \(a~ Ta changes destined for a non-regular file were not merged
1039 The reverse-merged changes will appear as local changes in the work tree,
1040 which may be viewed with
1042 amended manually or with further
1047 or discarded again with
1051 will refuse to run if certain preconditions are not met.
1052 If the work tree contains multiple base commits it must first be updated
1053 to a single base commit with
1055 If the work tree already contains files with merge conflicts, these
1056 conflicts must be resolved first.
1060 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1061 Rebase commits on the specified
1063 onto the tip of the current branch of the work tree.
1066 must share common ancestry with the work tree's current branch.
1067 Rebasing begins with the first descendant commit of the youngest
1068 common ancestor commit shared by the specified
1070 and the work tree's current branch, and stops once the tip commit
1077 is used as intended, the specified
1079 represents a local commit history and may already contain changes
1080 that are not yet visible in any other repositories.
1081 The work tree's current branch, which must be set with
1085 operation, represents a branch from a remote repository which shares
1086 a common history with the specified
1088 but has progressed, and perhaps diverged, due to commits added to the
1091 Rebased commits are accumulated on a temporary branch which the work tree
1092 will remain switched to throughout the entire rebase operation.
1093 Commits on this branch represent the same changes with the same log
1094 messages as their counterparts on the original
1096 but with different commit IDs.
1097 Once rebasing has completed successfully, the temporary branch becomes
1098 the new version of the specified
1100 and the work tree is automatically switched to it.
1102 While rebasing commits, show the status of each affected file,
1103 using the following status codes:
1104 .Bl -column YXZ description
1105 .It G Ta file was merged
1106 .It C Ta file was merged and conflicts occurred during merge
1107 .It ! Ta changes destined for a missing file were not merged
1108 .It D Ta file was deleted
1109 .It d Ta file's deletion was obstructed by local modifications
1110 .It A Ta new file was added
1111 .It \(a~ Ta changes destined for a non-regular file were not merged
1114 If merge conflicts occur the rebase operation is interrupted and may
1115 be continued once conflicts have been resolved.
1116 Alternatively, the rebase operation may be aborted which will leave
1118 unmodified and the work tree switched back to its original branch.
1120 If a merge conflict is resolved in a way which renders the merged
1121 change into a no-op change, the corresponding commit will be elided
1122 when the rebase operation continues.
1125 will refuse to run if certain preconditions are not met.
1126 If the work tree is not yet fully updated to the tip commit of its
1127 branch then the work tree must first be updated with
1129 If changes have been staged with
1131 these changes must first be committed with
1135 If the work tree contains local changes, these changes must first be
1142 contains changes to files outside of the work tree's path prefix,
1143 the work tree cannot be used to rebase this branch.
1149 commands will refuse to run while a rebase operation is in progress.
1150 Other commands which manipulate the work tree may be used for
1151 conflict resolution purposes.
1158 Abort an interrupted rebase operation.
1159 If this option is used, no other command-line arguments are allowed.
1161 Continue an interrupted rebase operation.
1162 If this option is used, no other command-line arguments are allowed.
1167 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1168 Edit commit history between the work tree's current base commit and
1169 the tip commit of the work tree's current branch.
1173 operation the work tree's current branch must be set with
1175 to the branch which should be edited, unless this branch is already the
1176 current branch of the work tree.
1177 The tip of this branch represents the upper bound (inclusive) of commits
1182 Furthermore, the work tree's base commit
1185 to a point in this branch's commit history where editing should begin.
1186 This commit represents the lower bound (non-inclusive) of commits touched
1191 Editing of commit history is controlled via a
1193 which can be written in an editor based on a template, passed on the
1194 command line, or generated with the
1196 option if only log messages need to be edited.
1198 The format of the histedit script is line-based.
1199 Each line in the script begins with a command name, followed by
1200 whitespace and an argument.
1201 For most commands, the expected argument is a commit ID SHA1 hash.
1202 Any remaining text on the line is ignored.
1203 Lines which begin with the
1205 character are ignored entirely.
1207 The available commands are as follows:
1208 .Bl -column YXZ pick-commit
1209 .It pick Ar commit Ta Use the specified commit as it is.
1210 .It edit Ar commit Ta Use the specified commit but once changes have been
1211 merged into the work tree interrupt the histedit operation for amending.
1212 .It fold Ar commit Ta Combine the specified commit with the next commit
1213 listed further below that will be used.
1214 .It drop Ar commit Ta Remove this commit from the edited history.
1215 .It mesg Ar log-message Ta Use the specified single-line log message for
1216 the commit on the previous line.
1217 If the log message argument is left empty, open an editor where a new
1218 log message can be written.
1221 Every commit in the history being edited must be mentioned in the script.
1222 Lines may be re-ordered to change the order of commits in the edited history.
1223 No commit may be listed more than once.
1225 Edited commits are accumulated on a temporary branch which the work tree
1226 will remain switched to throughout the entire histedit operation.
1227 Once history editing has completed successfully, the temporary branch becomes
1228 the new version of the work tree's branch and the work tree is automatically
1231 While merging commits, show the status of each affected file,
1232 using the following status codes:
1233 .Bl -column YXZ description
1234 .It G Ta file was merged
1235 .It C Ta file was merged and conflicts occurred during merge
1236 .It ! Ta changes destined for a missing file were not merged
1237 .It D Ta file was deleted
1238 .It d Ta file's deletion was obstructed by local modifications
1239 .It A Ta new file was added
1240 .It \(a~ Ta changes destined for a non-regular file were not merged
1243 If merge conflicts occur the histedit operation is interrupted and may
1244 be continued once conflicts have been resolved.
1245 Alternatively, the histedit operation may be aborted which will leave
1246 the work tree switched back to its original branch.
1248 If a merge conflict is resolved in a way which renders the merged
1249 change into a no-op change, the corresponding commit will be elided
1250 when the histedit operation continues.
1253 will refuse to run if certain preconditions are not met.
1254 If the work tree's current branch is not in the
1256 reference namespace, the history of the branch may not be edited.
1257 If the work tree contains multiple base commits it must first be updated
1258 to a single base commit with
1260 If changes have been staged with
1262 these changes must first be committed with
1266 If the work tree contains local changes, these changes must first be
1271 If the edited history contains changes to files outside of the work tree's
1272 path prefix, the work tree cannot be used to edit the history of this branch.
1279 commands will refuse to run while a histedit operation is in progress.
1280 Other commands which manipulate the work tree may be used, and the
1282 command may be used to commit arbitrary changes to the temporary branch
1283 while the histedit operation is interrupted.
1290 Abort an interrupted histedit operation.
1291 If this option is used, no other command-line arguments are allowed.
1293 Continue an interrupted histedit operation.
1294 If this option is used, no other command-line arguments are allowed.
1295 .It Fl F Ar histedit-script
1298 instead of opening a temporary file in an editor where a histedit script
1301 Edit log messages only.
1302 This option is a quick equivalent to a histedit script which edits
1303 only log messages but otherwise leaves every picked commit as-is.
1306 option can only be used when starting a new histedit operation.
1307 If this option is used, no other command-line arguments are allowed.
1312 .It Cm integrate Ar branch
1313 Integrate the specified
1315 into the work tree's current branch.
1316 Files in the work tree are updated to match the contents on the integrated
1318 and the reference of the work tree's branch is changed to point at the
1319 head commit of the integrated
1322 Both branches can be considered equivalent after integration since they
1323 will be pointing at the same commit.
1324 Both branches remain available for future work, if desired.
1325 In case the integrated
1327 is no longer needed it may be deleted with
1330 Show the status of each affected file, using the following status codes:
1331 .Bl -column YXZ description
1332 .It U Ta file was updated
1333 .It D Ta file was deleted
1334 .It A Ta new file was added
1335 .It \(a~ Ta versioned file is obstructed by a non-regular file
1336 .It ! Ta a missing versioned file was restored
1340 will refuse to run if certain preconditions are not met.
1341 Most importantly, the
1343 must have been rebased onto the work tree's current branch with
1345 before it can be integrated, in order to linearize commit history and
1346 resolve merge conflicts.
1347 If the work tree contains multiple base commits it must first be updated
1348 to a single base commit with
1350 If changes have been staged with
1352 these changes must first be committed with
1356 If the work tree contains local changes, these changes must first be
1364 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1365 Stage local changes for inclusion in the next commit.
1368 is specified, stage all changes in the work tree.
1369 Otherwise, stage changes at or within the specified paths.
1370 Paths may be staged if they are added, modified, or deleted according to
1373 Show the status of each affected file, using the following status codes:
1374 .Bl -column YXZ description
1375 .It A Ta file addition has been staged
1376 .It M Ta file modification has been staged
1377 .It D Ta file deletion has been staged
1380 Staged file contents are saved in newly created blob objects in the repository.
1381 These blobs will be referred to by tree objects once staged changes have been
1384 Staged changes affect the behaviour of
1389 While paths with staged changes exist, the
1391 command will refuse to commit any paths which do not have staged changes.
1392 Local changes created on top of staged changes can only be committed if
1393 the path is staged again, or if the staged changes are committed first.
1396 command will show both local changes and staged changes.
1399 command is able to display local changes relative to staged changes,
1400 and to display staged changes relative to the repository.
1403 command cannot revert staged changes but may be used to revert
1404 local changes created on top of staged changes.
1411 Instead of staging new changes, list paths which are already staged,
1412 along with the IDs of staged blob objects and stage status codes.
1413 If paths were provided in the command line show the staged paths
1414 among the specified paths.
1415 Otherwise, show all staged paths.
1417 Instead of staging the entire content of a changed file, interactively
1418 select or reject changes for staging based on
1422 (reject change), and
1424 (quit staging this file) responses.
1425 If a file is in modified status, individual patches derived from the
1426 modified file content can be staged.
1427 Files in added or deleted status may only be staged or rejected in
1429 .It Fl F Ar response-script
1437 responses line-by-line from the specified
1439 file instead of prompting interactively.
1443 will refuse to run if certain preconditions are not met.
1444 If a file contains merge conflicts, these conflicts must be resolved first.
1445 If a file is found to be out of date relative to the head commit on the
1446 work tree's current branch, the file must be updated with
1448 before it can be staged (however, this does not prevent the file from
1449 becoming out-of-date at some point after having been staged).
1456 commands will refuse to run while staged changes exist.
1457 If staged changes cannot be committed because a staged path
1458 is out of date, the path must be unstaged with
1460 before it can be updated with
1462 and may then be staged again if necessary.
1466 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1467 Merge staged changes back into the work tree and put affected paths
1468 back into non-staged status.
1471 is specified, unstage all staged changes across the entire work tree.
1472 Otherwise, unstage changes at or within the specified paths.
1474 Show the status of each affected file, using the following status codes:
1475 .Bl -column YXZ description
1476 .It G Ta file was unstaged
1477 .It C Ta file was unstaged and conflicts occurred during merge
1478 .It ! Ta changes destined for a missing file were not merged
1479 .It D Ta file was staged as deleted and still is deleted
1480 .It d Ta file's deletion was obstructed by local modifications
1481 .It \(a~ Ta changes destined for a non-regular file were not merged
1489 Instead of unstaging the entire content of a changed file, interactively
1490 select or reject changes for unstaging based on
1494 (keep change staged), and
1496 (quit unstaging this file) responses.
1497 If a file is staged in modified status, individual patches derived from the
1498 staged file content can be unstaged.
1499 Files staged in added or deleted status may only be unstaged in their entirety.
1500 .It Fl F Ar response-script
1508 responses line-by-line from the specified
1510 file instead of prompting interactively.
1515 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1516 Parse and print contents of objects to standard output in a line-based
1518 Content of commit, tree, and tag objects is printed in a way similar
1519 to the actual content stored in such objects.
1520 Blob object contents are printed as they would appear in files on disk.
1522 Attempt to interpret each argument as a reference, a tag name, or
1523 an object ID SHA1 hash.
1524 References will be resolved to an object ID.
1525 Tag names will resolved to a tag object.
1526 An abbreviated hash argument will be expanded to a full SHA1 hash
1527 automatically, provided the abbreviation is unique.
1529 If none of the above interpretations produce a valid result, or if the
1531 option is used, attempt to interpret the argument as a path which will
1532 be resolved to the ID of an object found at this path in the repository.
1539 Look up paths in the specified
1541 If this option is not used, paths are looked up in the commit resolved
1542 via the repository's HEAD reference.
1543 The expected argument is a commit ID SHA1 hash or an existing reference
1544 or tag name which will be resolved to a commit ID.
1545 An abbreviated hash argument will be expanded to a full SHA1 hash
1546 automatically, provided the abbreviation is unique.
1547 .It Fl r Ar repository-path
1548 Use the repository at the specified path.
1549 If not specified, assume the repository is located at or above the current
1551 If this directory is a
1553 work tree, use the repository path associated with this work tree.
1555 Interpret all arguments as paths only.
1556 This option can be used to resolve ambiguity in cases where paths
1557 look like tag names, reference names, or object IDs.
1561 .Bl -tag -width GOT_AUTHOR
1563 The author's name and email address for
1568 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1571 may fail to parse commits without an email address in author data,
1575 environment variables with a missing email address.
1581 configuration settings in the repository's
1583 file will override the value of
1589 configuration settings contained in Git's global
1591 configuration file will be used only if the
1593 environment variable is
1596 .It Ev VISUAL , EDITOR
1597 The editor spawned by
1602 .It Ev GOT_LOG_DEFAULT_LIMIT
1603 The default limit on the number of commits traversed by
1605 If set to zero, the limit is unbounded.
1606 This variable will be silently ignored if it is set to a non-numeric value.
1611 Clone an existing Git repository for use with
1615 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1617 Use of HTTP URLs currently requires
1621 .Dl $ git clone --bare https://github.com/openbsd/src.git
1623 Alternatively, for quick and dirty local testing of
1625 a new Git repository could be created and populated with files,
1626 e.g. from a temporary CVS checkout located at
1629 .Dl $ got init /var/git/src.git
1630 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1632 Check out a work tree from the Git repository to /usr/src:
1634 .Dl $ got checkout /var/git/src.git /usr/src
1636 View local changes in a work tree directory:
1639 .Dl $ got diff | less
1641 Interactively revert selected local changes in a work tree directory:
1643 .Dl $ got revert -p -R\ .
1645 In a work tree or a git repository directory, list all branch references:
1649 In a work tree or a git repository directory, create a new branch called
1650 .Dq unified-buffer-cache
1651 which is forked off the
1655 .Dl $ got branch unified-buffer-cache master
1657 Switch an existing work tree to the branch
1658 .Dq unified-buffer-cache .
1659 Local changes in the work tree will be preserved and merged if necessary:
1661 .Dl $ got update -b unified-buffer-cache
1663 Create a new commit from local changes in a work tree directory.
1664 This new commit will become the head commit of the work tree's current branch:
1668 In a work tree or a git repository directory, view changes committed in
1669 the 3 most recent commits to the work tree's branch, or the branch resolved
1670 via the repository's HEAD reference, respectively:
1672 .Dl $ got log -p -l 3
1674 In a work tree or a git repository directory, log the history of a subdirectory:
1676 .Dl $ got log sys/uvm
1678 While operating inside a work tree, paths are specified relative to the current
1679 working directory, so this command will log the subdirectory
1682 .Dl $ cd sys/uvm && got log '.'
1684 And this command has the same effect:
1686 .Dl $ cd sys/dev/usb && got log ../../uvm
1688 Add new files and remove obsolete files in a work tree directory:
1690 .Dl $ got add sys/uvm/uvm_ubc.c
1691 .Dl $ got remove sys/uvm/uvm_vnode.c
1693 Create a new commit from local changes in a work tree directory
1694 with a pre-defined log message.
1696 .Dl $ got commit -m 'unify the buffer cache'
1698 Update any work tree checked out from the
1699 .Dq unified-buffer-cache
1700 branch to the latest commit on this branch:
1704 Roll file content on the unified-buffer-cache branch back by one commit,
1705 and then fetch the rolled-back change into the work tree as a local change
1706 to be amended and perhaps committed again:
1708 .Dl $ got backout unified-buffer-cache
1709 .Dl $ got commit -m 'roll back previous'
1710 .Dl $ # now back out the previous backout :-)
1711 .Dl $ got backout unified-buffer-cache
1713 Fetch new upstream commits into the local repository's master branch.
1714 This step currently requires
1717 .Dl $ cd /var/git/src.git
1718 .Dl $ git fetch origin master:master
1721 .Dq unified-buffer-cache
1722 branch on top of the new head commit of the
1726 .Dl $ got update -b master
1727 .Dl $ got rebase unified-buffer-cache
1729 Create a patch from all changes on the unified-buffer-cache branch.
1730 The patch can be mailed out for review and applied to
1734 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1736 Edit the entire commit history of the
1737 .Dq unified-buffer-cache
1740 .Dl $ got update -b unified-buffer-cache
1741 .Dl $ got update -c master
1744 Additional steps are necessary if local changes need to be pushed back
1745 to the remote repository, which currently requires
1747 Before working against existing branches in a repository cloned with
1748 .Dq git clone --bare
1753 must be configured to map all references in the remote repository
1756 namespace of the local repository.
1757 This can achieved by setting Git's
1758 .Pa remote.origin.fetch
1759 configuration variable to the value
1760 .Dq +refs/heads/*:refs/remotes/origin/*
1765 .Dl $ cd /var/git/repo
1766 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1768 Alternatively, the following
1770 configuration item can be added manually to the Git repository's
1774 .Dl [remote "origin"]
1776 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
1778 This configuration leaves the local repository's
1780 namespace free for use by local branches checked out with
1782 and, if needed, created with
1787 namespace can be updated with incoming changes from the remote
1791 .Dl $ cd /var/git/repo
1794 To make changes fetched from the remote repository appear on the
1798 branch must be rebased onto the
1801 This will also merge local changes, if any, with the incoming changes:
1803 .Dl $ got update -b origin/master
1804 .Dl $ got rebase master
1808 branch, log messages for local changes can now be amended with
1810 by other developers and any other important new information:
1812 .Dl $ got update -c origin/master
1813 .Dl $ got histedit -m
1815 Local changes on the
1817 branch can then be pushed to the remote
1821 .Dl $ cd /var/git/repo
1822 .Dl $ git push origin master
1824 In order to merge changes committed to the
1825 .Dq unified-buffer-cache
1826 branch back into the
1829 .Dq unified-buffer-cache
1830 branch must first be rebased onto the
1834 .Dl $ got update -b master
1835 .Dl $ got rebase unified-buffer-cache
1838 .Dq unified-buffer-cache
1839 branch can now be made visible on the
1843 Because the rebase operation switched the work tree to the
1844 .Dq unified-buffer-cache
1845 branch, the work tree must be switched back to the
1848 .Dq unified-buffer-cache
1849 branch can be integrated into
1852 .Dl $ got update -b master
1853 .Dl $ got integrate unified-buffer-cache
1856 .Xr git-repository 5 ,
1859 .An Stefan Sperling Aq Mt stsp@openbsd.org
1860 .An Martin Pieuchot Aq Mt mpi@openbsd.org
1861 .An Joshua Stein Aq Mt jcs@openbsd.org
1862 .An Ori Bernstein Aq Mt ori@openbsd.org
1865 is a work-in-progress and many commands remain to be implemented.
1866 At present, the user has to fall back on
1868 to perform many tasks, in particular tasks related to repository
1869 administration and tasks which require a network connection.
