2 .\" Copyright (c) 2017 Martin Pieuchot
3 .\" Copyright (c) 2018, 2019, 2020 Stefan Sperling
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
30 is a version control system which stores the history of tracked files
31 in a Git repository, as used by the Git version control system.
32 This repository format is described in
33 .Xr git-repository 5 .
38 version control system because every copy of a repository is writeable.
39 Modifications made to files can be synchronized between repositories
44 must be checked out from the repository for modification.
45 Checked out files are stored in a
47 which can be placed at an arbitrary directory in the filesystem hierarchy.
48 The on-disk format of this work tree is described in
52 provides global and command-specific options.
53 Global options must precede the command name, and are as follows:
54 .Bl -tag -width tenletters
56 Display usage information and exit immediately.
58 Display program version and exit immediately.
64 .Bl -tag -width checkout
65 .It Cm init Ar repository-path
66 Create a new empty repository at the specified
73 command must be used to populate the empty repository before
79 .It Cm import Oo Fl b Ar branch Oc Oo Fl m Ar message Oc Oo Fl r Ar repository-path Oc Oo Fl I Ar pattern Oc Ar directory
80 Create an initial commit in a repository from the file hierarchy
83 The created commit will not have any parent commits, i.e. it will be a
85 Also create a new reference which provides a branch name for the newly
87 Show the path of each imported file to indicate progress.
93 environment variable to be set,
98 configuration settings can be obtained from the repository's
100 file or from Git's global
111 instead of creating the default branch
113 Use of this option is required if the
115 branch already exists.
117 Use the specified log message when creating the new commit.
122 opens a temporary file in an editor where a log message can be written.
123 .It Fl r Ar repository-path
124 Use the repository at the specified path.
125 If not specified, assume the repository is located at or above the current
128 Ignore files or directories with a name which matches the specified
130 This option may be specified multiple times to build a list of ignore patterns.
133 follows the globbing rules documented in
139 .It Cm clone Oo Fl a Oc Oo Fl b Ar branch Oc Oo Fl l Oc Oo Fl m Oc Oo Fl q Oc Oo Fl v Oc Oo Fl R Ar reference Oc Ar repository-URL Op Ar directory
140 Clone a Git repository at the specified
146 is specified the directory name will be derived from the name of the
149 will refuse to run if the
155 specifies a protocol scheme, a server hostname, an optional port number
156 separated from the hostname by a colon, and a path to the repository on
158 .Lk scheme://hostname:port/path/to/repository
160 The following protocol schemes are supported:
161 .Bl -tag -width git+ssh
163 The Git protocol as implemented by the
166 Use of this protocol is discouraged since it supports neither authentication
169 The Git protocol wrapped in an authenticated and encrypted
172 With this protocol the hostname may contain an embedded username for
177 Short alias for git+ssh.
180 Objects in the cloned repository are stored in a pack file which is downloaded
182 This pack file will then be indexed to facilitate access to the objects stored
184 If any objects in the pack file are stored in deltified form, all deltas will
185 be fully resolved in order to compute the ID of such objects.
186 This can take some time.
187 More details about the pack file format are documented in
188 .Xr git-repository 5 .
191 creates a remote repository entry in the
193 file of the cloned repository to store the
205 Fetch all branches from the remote repository's
208 If this option is not specified, a branch resolved via the remote
209 repository's HEAD reference will be fetched.
210 Cannot be used together with the
216 from the remote repository's
219 This option may be specified multiple times to build a list of branches
221 If the branch corresponding to the remote repository's HEAD reference is not
222 in this list, the cloned repository's HEAD reference will be set to the first
223 branch which was fetched.
224 If this option is not specified, a branch resolved via the remote
225 repository's HEAD reference will be fetched.
226 Cannot be used together with the
230 List branches and tags available for fetching from the remote repository
231 and exit immediately.
232 Cannot be used together with any of the other options except
235 Create the cloned repository as a mirror of the original repository.
236 This is useful if the cloned repository will not be used to store
237 local changes as created by
242 file will be set up with the
244 option enabled, such that
248 will write incoming changes directly to local branches in the
250 reference namespace, rather than to branches in the
253 This avoids the usual requirement of having to run
257 in order to make incoming changes appear on local branches.
258 But maintaining local changes in the cloned repository becomes difficult
259 since local changes will be at risk of being discarded whenever incoming
262 Suppress progress reporting output.
263 The same option will be passed to
270 to print debugging messages to standard error output.
271 This option will be passed to
274 Multiple -v options increase the verbosity.
276 .It Fl R Ar reference
277 In addition to the branches and tags that will be fetched, fetch an arbitrary
279 from the remote repository's
282 This option may be specified multiple times to build a list of additional
286 may either be a path to a specific reference, or a reference namespace
287 which will cause all references in this namespace to be fetched.
289 Each reference will be mapped into the cloned repository's
291 namespace, unless the
293 option is used to mirror references directly into the cloned repository's
298 will refuse to fetch references from the remote repository's
307 .It Cm fetch Oo Fl a Oc Oo Fl b Ar branch Oc Oo Fl d Oc Oo Fl l Oc Oo Fl r Ar repository-path Oc Oo Fl t Oc Oo Fl q Oc Oo Fl v Oc Oo Fl R Ar reference Oc Op Ar remote-repository
308 Fetch new changes from a remote repository.
310 .Ar remote-repository
314 The remote repository's URL is obtained from the corresponding entry in the
316 file of the local repository, as created by
319 New changes will be stored in a separate pack file downloaded from the server.
320 Optionally, separate pack files stored in the repository can be combined with
323 By default, branch references in the
325 reference namespace will be updated to point at the newly fetched commits.
328 command can then be used to make new changes visible on local branches in the
330 namespace, merging incoming changes with local changes as necessary.
332 If the repository was created as a mirror with
334 then all branches in the
336 namespace will be updated directly to match the corresponding branches in
337 the remote repository.
338 If those branches contained local commits, these commits will no longer be
339 reachable via a reference and will therefore be at risk of being discarded
340 by Git's garbage collector.
341 Maintaining local changes in a mirror repository is therefore discouraged.
343 In any case, references in the
345 namespace will always be fetched and mapped directly to local references
346 in the same namespace.
353 Fetch all branches from the remote repository's
356 If this option is not specified, a branch resolved via the remote
357 repository's HEAD reference will be fetched.
358 Cannot be used together with the
364 from the remote repository's
367 This option may be specified multiple times to build a list of branches
369 If this option is not specified, a branch resolved via the remote
370 repository's HEAD reference will be fetched.
371 Cannot be used together with the
375 Delete branches and tags from the local repository which are no longer
376 present in the remote repository.
377 Only references are deleted.
378 Any commit, tree, tag, and blob objects belonging to deleted branches or
379 tags remain in the repository and may be removed separately with
380 Git's garbage collector.
382 List branches and tags available for fetching from the remote repository
383 and exit immediately.
384 Cannot be used together with any of the other options except
389 Allow existing references in the
391 namespace to be updated if they have changed on the server.
392 If not specified, only new tag references will be created.
393 .It Fl r Ar repository-path
394 Use the repository at the specified path.
395 If not specified, assume the repository is located at or above the current
397 If this directory is a
399 work tree, use the repository path associated with this work tree.
401 Suppress progress reporting output.
402 The same option will be passed to
409 to print debugging messages to standard error output.
410 The same option will be passed to
413 Multiple -v options increase the verbosity.
415 .It Fl R Ar reference
416 In addition to the branches and tags that will be fetched, fetch an arbitrary
418 from the remote repository's
421 This option may be specified multiple times to build a list of additional
425 may either be a path to a specific reference, or a reference namespace
426 which will cause all references in this namespace to be fetched.
428 Each reference will be mapped into the local repository's
430 namespace, unless the local repository was created as a mirror with
432 in which case references will be mapped directly into the local repository's
436 Once a reference has been fetched, a local branch based on it can be
442 will refuse to fetch references from the remote repository's
451 .It Cm checkout Oo Fl E Oc Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Oo Fl p Ar path-prefix Oc Ar repository-path Op Ar work-tree-path
452 Copy files from a repository into a new work tree.
453 Show the status of each affected file, using the following status codes:
454 .Bl -column YXZ description
455 .It A Ta new file was added
456 .It E Ta file already exists in work tree's meta-data
461 is not specified, either use the last component of
462 .Ar repository path ,
465 was specified use the last component of
473 Proceed with the checkout operation even if the directory at
476 Existing files will be left intact.
478 Check out files from a commit on the specified
480 If this option is not specified, a branch resolved via the repository's HEAD
481 reference will be used.
483 Check out files from the specified
485 on the selected branch.
486 The expected argument is a commit ID SHA1 hash or an existing reference
487 or tag name which will be resolved to a commit ID.
488 An abbreviated hash argument will be expanded to a full SHA1 hash
489 automatically, provided the abbreviation is unique.
490 If this option is not specified, the most recent commit on the selected
495 is not contained in the selected branch, a different branch which contains
496 this commit must be specified with the
499 If no such branch is known a new branch must be created for this
505 Checking out work trees with an unknown branch is intentionally not supported.
506 .It Fl p Ar path-prefix
507 Restrict the work tree to a subset of the repository's tree hierarchy.
508 Only files beneath the specified
515 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
516 Update an existing work tree to a different
518 Change existing files in the work tree as necessary to match file contents
520 Preserve any local changes in the work tree and merge them with the
523 Files which already contain merge conflicts will not be updated to avoid
524 further complications.
525 Such files will be updated when
527 is run again after merge conflicts have been resolved.
528 If the conflicting changes are no longer needed affected files can be
535 Show the status of each affected file, using the following status codes:
536 .Bl -column YXZ description
537 .It U Ta file was updated and contained no local changes
538 .It G Ta file was updated and local changes were merged cleanly
539 .It C Ta file was updated and conflicts occurred during merge
540 .It D Ta file was deleted
541 .It A Ta new file was added
542 .It \(a~ Ta versioned file is obstructed by a non-regular file
543 .It ! Ta a missing versioned file was restored
544 .It # Ta file was not updated because it contains merge conflicts
549 is specified, update the entire work tree.
550 Otherwise, restrict the update operation to files at or within the
552 Each path is required to exist in the update operation's target commit.
553 Files in the work tree outside specified paths will remain unchanged and
554 will retain their previously recorded base commit.
557 commands may refuse to run while the work tree contains files from
558 multiple base commits.
559 The base commit of such a work tree can be made consistent by running
561 across the entire work tree.
564 is incompatible with the
569 cannot update paths with staged changes.
570 If changes have been staged with
572 these changes must first be committed with
582 Switch the work tree's branch reference to the specified
584 before updating the work tree.
585 This option requires that all paths in the work tree are updated.
587 As usual, any local changes in the work tree will be preserved.
588 This can be useful when switching to a newly created branch in order
589 to commit existing local changes to this branch.
591 Any local changes must be dealt with separately in order to obtain a
592 work tree with pristine file contents corresponding exactly to the specified
594 Such changes could first be committed to a different branch with
596 or could be discarded with
599 Update the work tree to the specified
601 The expected argument is a commit ID SHA1 hash or an existing reference
602 or tag name which will be resolved to a commit ID.
603 An abbreviated hash argument will be expanded to a full SHA1 hash
604 automatically, provided the abbreviation is unique.
605 If this option is not specified, the most recent commit on the work tree's
611 .It Cm status Op Ar path ...
612 Show the current modification status of files in a work tree,
613 using the following status codes:
614 .Bl -column YXZ description
615 .It M Ta modified file
616 .It A Ta file scheduled for addition in next commit
617 .It D Ta file scheduled for deletion in next commit
618 .It C Ta modified or added file which contains merge conflicts
619 .It ! Ta versioned file was expected on disk but is missing
620 .It \(a~ Ta versioned file is obstructed by a non-regular file
621 .It ? Ta unversioned item not tracked by
623 .It m Ta modified file modes (executable bit only)
624 .It N Ta non-existent
626 specified on the command line
631 is specified, show modifications in the entire work tree.
632 Otherwise, show modifications at or within the specified paths.
634 If changes have been staged with
636 staged changes are shown in the second output column, using the following
638 .Bl -column YXZ description
639 .It M Ta file modification is staged
640 .It A Ta file addition is staged
641 .It D Ta file deletion is staged
644 Changes created on top of staged changes are indicated in the first column:
645 .Bl -column YXZ description
646 .It MM Ta file was modified after earlier changes have been staged
647 .It MA Ta file was modified after having been staged for addition
650 For compatibility with
661 files in each traversed directory and will not display unversioned files
662 which match these patterns.
667 supports consecutive asterisks,
669 which will match an arbitrary amount of directories.
673 only supports a single ignore pattern per line.
677 does not support negated ignore patterns prefixed with
679 and gives no special significance to the location of path component separators,
685 .It Cm log Oo Fl b Oc Oo Fl c Ar commit Oc Oo Fl C Ar number Oc Oo Fl l Ar N Oc Oo Fl p Oc Oo Fl s Ar search-pattern Oc Oo Fl r Ar repository-path Oc Oo Fl x Ar commit Oc Op Ar path
686 Display history of a repository.
689 is specified, show only commits which modified this path.
690 If invoked in a work tree, the
692 is interpreted relative to the current working directory,
693 and the work tree's path prefix is implicitly prepended.
694 Otherwise, the path is interpreted relative to the repository root.
701 Display individual commits which were merged into the current branch
705 shows the linear history of the current branch only.
707 Start traversing history at the specified
709 The expected argument is a commit ID SHA1 hash or an existing reference
710 or tag name which will be resolved to a commit ID.
711 An abbreviated hash argument will be expanded to a full SHA1 hash
712 automatically, provided the abbreviation is unique.
713 If this option is not specified, default to the work tree's current branch
714 if invoked in a work tree, or to the repository's HEAD reference.
716 Set the number of context lines shown in diffs with
718 By default, 3 lines of context are shown.
720 Limit history traversal to a given number of commits.
721 If this option is not specified, a default limit value of zero is used,
722 which is treated as an unbounded limit.
724 .Ev GOT_LOG_DEFAULT_LIMIT
725 environment variable may be set to change this default value.
727 Display the patch of modifications made in each commit.
730 is specified, only show the patch of modifications at or within this path.
731 .It Fl s Ar search-pattern
732 If specified, show only commits with a log message matched by the extended
735 Regular expression syntax is documented in
737 .It Fl r Ar repository-path
738 Use the repository at the specified path.
739 If not specified, assume the repository is located at or above the current
741 If this directory is a
743 work tree, use the repository path associated with this work tree.
745 Stop traversing commit history as soon as the specified
748 This option has no effect if the specified
752 .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
753 When invoked within a work tree with less than two arguments, display
754 uncommitted changes in the work tree.
757 is specified, only show changes within this path.
759 If two arguments are provided, treat each argument as a reference, a tag
760 name, or an object ID SHA1 hash, and display differences between the
761 corresponding objects.
762 Both objects must be of the same type (blobs, trees, or commits).
763 An abbreviated hash argument will be expanded to a full SHA1 hash
764 automatically, provided the abbreviation is unique.
771 Set the number of context lines shown in the diff.
772 By default, 3 lines of context are shown.
773 .It Fl r Ar repository-path
774 Use the repository at the specified path.
775 If not specified, assume the repository is located at or above the current
777 If this directory is a
779 work tree, use the repository path associated with this work tree.
781 Show changes staged with
783 instead of showing local changes.
784 This option is only valid when
786 is invoked in a work tree.
788 Ignore whitespace-only changes.
793 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
794 Display line-by-line history of a file at the specified path.
801 Start traversing history at the specified
803 The expected argument is a commit ID SHA1 hash or an existing reference
804 or tag name which will be resolved to a commit ID.
805 An abbreviated hash argument will be expanded to a full SHA1 hash
806 automatically, provided the abbreviation is unique.
807 .It Fl r Ar repository-path
808 Use the repository at the specified path.
809 If not specified, assume the repository is located at or above the current
811 If this directory is a
813 work tree, use the repository path associated with this work tree.
818 .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
819 Display a listing of files and directories at the specified
820 directory path in the repository.
821 Entries shown in this listing may carry one of the following trailing
823 .Bl -column YXZ description
824 .It @ Ta entry is a symbolic link
825 .It / Ta entry is a directory
826 .It * Ta entry is an executable file
827 .It $ Ta entry is a Git submodule
832 is specified, list the repository path corresponding to the current
833 directory of the work tree, or the root directory of the repository
834 if there is no work tree.
841 List files and directories as they appear in the specified
843 The expected argument is a commit ID SHA1 hash or an existing reference
844 or tag name which will be resolved to a commit ID.
845 An abbreviated hash argument will be expanded to a full SHA1 hash
846 automatically, provided the abbreviation is unique.
847 .It Fl r Ar repository-path
848 Use the repository at the specified path.
849 If not specified, assume the repository is located at or above the current
851 If this directory is a
853 work tree, use the repository path associated with this work tree.
855 Show object IDs of files (blob objects) and directories (tree objects).
857 Recurse into sub-directories in the repository.
862 .It Cm ref Oo Fl r Ar repository-path Oc Oo Fl l Oc Oo Fl c Ar object Oc Oo Fl s Ar reference Oc Oo Fl d Oc Op Ar name
863 Manage references in a repository.
865 References may be listed, created, deleted, and changed.
866 When creating, deleting, or changing a reference the specified
868 must be an absolute reference name, i.e. it must begin with
875 .It Fl r Ar repository-path
876 Use the repository at the specified path.
877 If not specified, assume the repository is located at or above the current
879 If this directory is a
881 work tree, use the repository path associated with this work tree.
883 List references in the repository.
886 is specified, list all existing references in the repository.
889 is a reference namespace, list all references in this namespace.
890 Otherwise, show only the reference with the given
892 Cannot be used together with any other options except
895 Create a reference or change an existing reference.
896 The reference with the specified
898 will point at the specified
902 argument is a ID SHA1 hash or an existing reference or tag name which will
903 be resolved to the ID of a corresponding commit, tree, tag, or blob object.
904 Cannot be used together with any other options except
906 .It Fl s Ar reference
907 Create a symbolic reference, or change an existing symbolic reference.
908 The symbolic reference with the specified
910 will point at the specified
912 which must already exist in the repository.
913 Care should be taken not to create loops between references when
915 Cannot be used together with any other options except
918 Delete the reference with the specified
921 Cannot be used together with any other options except
924 .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
925 Create, list, or delete branches.
927 Branches are managed via references which live in the
932 command operates on references in this namespace only.
934 If invoked in a work tree without any arguments, print the name of the
935 work tree's current branch.
939 argument is passed, attempt to create a branch reference with the given name.
940 By default the new branch reference will point at the latest commit on the
941 work tree's current branch if invoked in a work tree, and otherwise to a commit
942 resolved via the repository's HEAD reference.
944 If invoked in a work tree, once the branch was created successfully
945 switch the work tree's head reference to the newly created branch and
946 update files across the entire work tree, just like
947 .Cm got update -b Ar name
949 Show the status of each affected file, using the following status codes:
950 .Bl -column YXZ description
951 .It U Ta file was updated and contained no local changes
952 .It G Ta file was updated and local changes were merged cleanly
953 .It C Ta file was updated and conflicts occurred during merge
954 .It D Ta file was deleted
955 .It A Ta new file was added
956 .It \(a~ Ta versioned file is obstructed by a non-regular file
957 .It ! Ta a missing versioned file was restored
965 Make a newly created branch reference point at the specified
969 argument is a commit ID SHA1 hash or an existing reference
970 or tag name which will be resolved to a commit ID.
971 .It Fl r Ar repository-path
972 Use the repository at the specified path.
973 If not specified, assume the repository is located at or above the current
975 If this directory is a
977 work tree, use the repository path associated with this work tree.
979 List all existing branches in the repository.
980 If invoked in a work tree, the work tree's current branch is shown
981 with one the following annotations:
982 .Bl -column YXZ description
983 .It * Ta work tree's base commit matches the branch tip
984 .It \(a~ Ta work tree's base commit is out-of-date
987 Delete the branch with the specified name from the repository.
988 Only the branch reference is deleted.
989 Any commit, tree, and blob objects belonging to the branch
990 remain in the repository and may be removed separately with
991 Git's garbage collector.
993 Do not switch and update the work tree after creating a new branch.
998 .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
999 Manage tags in a repository.
1001 Tags are managed via references which live in the
1003 reference namespace.
1006 command operates on references in this namespace only.
1007 References in this namespace point at tag objects which contain a pointer
1008 to another object, a tag message, as well as author and timestamp information.
1010 Attempt to create a tag with the given
1012 and make this tag point at the given
1014 If no commit is specified, default to the latest commit on the work tree's
1015 current branch if invoked in a work tree, and to a commit resolved via
1016 the repository's HEAD reference otherwise.
1023 Make the newly created tag reference point at the specified
1027 argument is a commit ID SHA1 hash or an existing reference or tag name which
1028 will be resolved to a commit ID.
1029 An abbreviated hash argument will be expanded to a full SHA1 hash
1030 automatically, provided the abbreviation is unique.
1032 Use the specified tag message when creating the new tag.
1037 opens a temporary file in an editor where a tag message can be written.
1038 .It Fl r Ar repository-path
1039 Use the repository at the specified path.
1040 If not specified, assume the repository is located at or above the current
1042 If this directory is a
1044 work tree, use the repository path associated with this work tree.
1046 List all existing tags in the repository instead of creating a new tag.
1047 If this option is used, no other command-line arguments are allowed.
1052 command will not delete tags or change existing tags.
1053 If a tag must be deleted, the
1055 command may be used to delete a tag's reference.
1056 This should only be done if the tag has not already been copied to
1058 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
1059 Schedule unversioned files in a work tree for addition to the
1060 repository in the next commit.
1067 Permit recursion into directories.
1068 If this option is not specified,
1070 will refuse to run if a specified
1074 With -R, add files even if they match a
1078 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
1079 Remove versioned files from a work tree and schedule them for deletion
1080 from the repository in the next commit.
1087 Perform the operation even if a file contains uncommitted modifications.
1089 Keep affected files on disk.
1091 Permit recursion into directories.
1092 If this option is not specified,
1094 will refuse to run if a specified
1101 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
1102 Revert any uncommitted changes in files at the specified paths.
1103 File contents will be overwritten with those contained in the
1104 work tree's base commit.
1105 There is no way to bring discarded changes back after
1108 If a file was added with
1110 it will become an unversioned file again.
1111 If a file was deleted with
1113 it will be restored.
1120 Instead of reverting all changes in files, interactively select or reject
1121 changes to revert based on
1127 (quit reverting this file) responses.
1128 If a file is in modified status, individual patches derived from the
1129 modified file content can be reverted.
1130 Files in added or deleted status may only be reverted in their entirety.
1131 .It Fl F Ar response-script
1139 responses line-by-line from the specified
1141 file instead of prompting interactively.
1143 Permit recursion into directories.
1144 If this option is not specified,
1146 will refuse to run if a specified
1153 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1154 Create a new commit in the repository from changes in a work tree
1155 and use this commit as the new base commit for the work tree.
1158 is specified, commit all changes in the work tree.
1159 Otherwise, commit changes at or within the specified paths.
1161 If changes have been explicitly staged for commit with
1163 only commit staged changes and reject any specified paths which
1164 have not been staged.
1166 Show the status of each affected file, using the following status codes:
1167 .Bl -column YXZ description
1168 .It M Ta modified file
1169 .It D Ta file was deleted
1170 .It A Ta new file was added
1171 .It m Ta modified file modes (executable bit only)
1174 Files which are not part of the new commit will retain their previously
1175 recorded base commit.
1178 commands may refuse to run while the work tree contains files from
1179 multiple base commits.
1180 The base commit of such a work tree can be made consistent by running
1182 across the entire work tree.
1186 command requires the
1188 environment variable to be set,
1193 configuration settings can be
1194 obtained from the repository's
1196 file or from Git's global
1205 Use the specified log message when creating the new commit.
1210 opens a temporary file in an editor where a log message can be written.
1214 will refuse to run if certain preconditions are not met.
1215 If the work tree's current branch is not in the
1217 reference namespace, new commits may not be created on this branch.
1218 Local changes may only be committed if they are based on file content
1219 found in the most recent commit on the work tree's branch.
1220 If a path is found to be out of date,
1222 must be used first in order to merge local changes with changes made
1227 .It Cm cherrypick Ar commit
1228 Merge changes from a single
1233 must be on a different branch than the work tree's base commit.
1234 The expected argument is a reference or a commit ID SHA1 hash.
1235 An abbreviated hash argument will be expanded to a full SHA1 hash
1236 automatically, provided the abbreviation is unique.
1238 Show the status of each affected file, using the following status codes:
1239 .Bl -column YXZ description
1240 .It G Ta file was merged
1241 .It C Ta file was merged and conflicts occurred during merge
1242 .It ! Ta changes destined for a missing file were not merged
1243 .It D Ta file was deleted
1244 .It d Ta file's deletion was obstructed by local modifications
1245 .It A Ta new file was added
1246 .It \(a~ Ta changes destined for a non-regular file were not merged
1249 The merged changes will appear as local changes in the work tree, which
1252 amended manually or with further
1257 or discarded again with
1261 will refuse to run if certain preconditions are not met.
1262 If the work tree contains multiple base commits it must first be updated
1263 to a single base commit with
1265 If the work tree already contains files with merge conflicts, these
1266 conflicts must be resolved first.
1270 .It Cm backout Ar commit
1271 Reverse-merge changes from a single
1276 must be on the same branch as the work tree's base commit.
1277 The expected argument is a reference or a commit ID SHA1 hash.
1278 An abbreviated hash argument will be expanded to a full SHA1 hash
1279 automatically, provided the abbreviation is unique.
1281 Show the status of each affected file, using the following status codes:
1282 .Bl -column YXZ description
1283 .It G Ta file was merged
1284 .It C Ta file was merged and conflicts occurred during merge
1285 .It ! Ta changes destined for a missing file were not merged
1286 .It D Ta file was deleted
1287 .It d Ta file's deletion was obstructed by local modifications
1288 .It A Ta new file was added
1289 .It \(a~ Ta changes destined for a non-regular file were not merged
1292 The reverse-merged changes will appear as local changes in the work tree,
1293 which may be viewed with
1295 amended manually or with further
1300 or discarded again with
1304 will refuse to run if certain preconditions are not met.
1305 If the work tree contains multiple base commits it must first be updated
1306 to a single base commit with
1308 If the work tree already contains files with merge conflicts, these
1309 conflicts must be resolved first.
1313 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1314 Rebase commits on the specified
1316 onto the tip of the current branch of the work tree.
1319 must share common ancestry with the work tree's current branch.
1320 Rebasing begins with the first descendant commit of the youngest
1321 common ancestor commit shared by the specified
1323 and the work tree's current branch, and stops once the tip commit
1330 is used as intended, the specified
1332 represents a local commit history and may already contain changes
1333 that are not yet visible in any other repositories.
1334 The work tree's current branch, which must be set with
1338 operation, represents a branch from a remote repository which shares
1339 a common history with the specified
1341 but has progressed, and perhaps diverged, due to commits added to the
1344 Rebased commits are accumulated on a temporary branch which the work tree
1345 will remain switched to throughout the entire rebase operation.
1346 Commits on this branch represent the same changes with the same log
1347 messages as their counterparts on the original
1349 but with different commit IDs.
1350 Once rebasing has completed successfully, the temporary branch becomes
1351 the new version of the specified
1353 and the work tree is automatically switched to it.
1355 While rebasing commits, show the status of each affected file,
1356 using the following status codes:
1357 .Bl -column YXZ description
1358 .It G Ta file was merged
1359 .It C Ta file was merged and conflicts occurred during merge
1360 .It ! Ta changes destined for a missing file were not merged
1361 .It D Ta file was deleted
1362 .It d Ta file's deletion was obstructed by local modifications
1363 .It A Ta new file was added
1364 .It \(a~ Ta changes destined for a non-regular file were not merged
1367 If merge conflicts occur the rebase operation is interrupted and may
1368 be continued once conflicts have been resolved.
1369 Alternatively, the rebase operation may be aborted which will leave
1371 unmodified and the work tree switched back to its original branch.
1373 If a merge conflict is resolved in a way which renders the merged
1374 change into a no-op change, the corresponding commit will be elided
1375 when the rebase operation continues.
1378 will refuse to run if certain preconditions are not met.
1379 If the work tree is not yet fully updated to the tip commit of its
1380 branch then the work tree must first be updated with
1382 If changes have been staged with
1384 these changes must first be committed with
1388 If the work tree contains local changes, these changes must first be
1395 contains changes to files outside of the work tree's path prefix,
1396 the work tree cannot be used to rebase this branch.
1402 commands will refuse to run while a rebase operation is in progress.
1403 Other commands which manipulate the work tree may be used for
1404 conflict resolution purposes.
1411 Abort an interrupted rebase operation.
1412 If this option is used, no other command-line arguments are allowed.
1414 Continue an interrupted rebase operation.
1415 If this option is used, no other command-line arguments are allowed.
1420 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1421 Edit commit history between the work tree's current base commit and
1422 the tip commit of the work tree's current branch.
1426 operation the work tree's current branch must be set with
1428 to the branch which should be edited, unless this branch is already the
1429 current branch of the work tree.
1430 The tip of this branch represents the upper bound (inclusive) of commits
1435 Furthermore, the work tree's base commit
1438 to a point in this branch's commit history where editing should begin.
1439 This commit represents the lower bound (non-inclusive) of commits touched
1444 Editing of commit history is controlled via a
1446 which can be written in an editor based on a template, passed on the
1447 command line, or generated with the
1449 option if only log messages need to be edited.
1451 The format of the histedit script is line-based.
1452 Each line in the script begins with a command name, followed by
1453 whitespace and an argument.
1454 For most commands, the expected argument is a commit ID SHA1 hash.
1455 Any remaining text on the line is ignored.
1456 Lines which begin with the
1458 character are ignored entirely.
1460 The available commands are as follows:
1461 .Bl -column YXZ pick-commit
1462 .It pick Ar commit Ta Use the specified commit as it is.
1463 .It edit Ar commit Ta Use the specified commit but once changes have been
1464 merged into the work tree interrupt the histedit operation for amending.
1465 .It fold Ar commit Ta Combine the specified commit with the next commit
1466 listed further below that will be used.
1467 .It drop Ar commit Ta Remove this commit from the edited history.
1468 .It mesg Ar log-message Ta Use the specified single-line log message for
1469 the commit on the previous line.
1470 If the log message argument is left empty, open an editor where a new
1471 log message can be written.
1474 Every commit in the history being edited must be mentioned in the script.
1475 Lines may be re-ordered to change the order of commits in the edited history.
1476 No commit may be listed more than once.
1478 Edited commits are accumulated on a temporary branch which the work tree
1479 will remain switched to throughout the entire histedit operation.
1480 Once history editing has completed successfully, the temporary branch becomes
1481 the new version of the work tree's branch and the work tree is automatically
1484 While merging commits, show the status of each affected file,
1485 using the following status codes:
1486 .Bl -column YXZ description
1487 .It G Ta file was merged
1488 .It C Ta file was merged and conflicts occurred during merge
1489 .It ! Ta changes destined for a missing file were not merged
1490 .It D Ta file was deleted
1491 .It d Ta file's deletion was obstructed by local modifications
1492 .It A Ta new file was added
1493 .It \(a~ Ta changes destined for a non-regular file were not merged
1496 If merge conflicts occur the histedit operation is interrupted and may
1497 be continued once conflicts have been resolved.
1498 Alternatively, the histedit operation may be aborted which will leave
1499 the work tree switched back to its original branch.
1501 If a merge conflict is resolved in a way which renders the merged
1502 change into a no-op change, the corresponding commit will be elided
1503 when the histedit operation continues.
1506 will refuse to run if certain preconditions are not met.
1507 If the work tree's current branch is not in the
1509 reference namespace, the history of the branch may not be edited.
1510 If the work tree contains multiple base commits it must first be updated
1511 to a single base commit with
1513 If changes have been staged with
1515 these changes must first be committed with
1519 If the work tree contains local changes, these changes must first be
1524 If the edited history contains changes to files outside of the work tree's
1525 path prefix, the work tree cannot be used to edit the history of this branch.
1532 commands will refuse to run while a histedit operation is in progress.
1533 Other commands which manipulate the work tree may be used, and the
1535 command may be used to commit arbitrary changes to the temporary branch
1536 while the histedit operation is interrupted.
1543 Abort an interrupted histedit operation.
1544 If this option is used, no other command-line arguments are allowed.
1546 Continue an interrupted histedit operation.
1547 If this option is used, no other command-line arguments are allowed.
1548 .It Fl F Ar histedit-script
1551 instead of opening a temporary file in an editor where a histedit script
1554 Edit log messages only.
1555 This option is a quick equivalent to a histedit script which edits
1556 only log messages but otherwise leaves every picked commit as-is.
1559 option can only be used when starting a new histedit operation.
1560 If this option is used, no other command-line arguments are allowed.
1565 .It Cm integrate Ar branch
1566 Integrate the specified
1568 into the work tree's current branch.
1569 Files in the work tree are updated to match the contents on the integrated
1571 and the reference of the work tree's branch is changed to point at the
1572 head commit of the integrated
1575 Both branches can be considered equivalent after integration since they
1576 will be pointing at the same commit.
1577 Both branches remain available for future work, if desired.
1578 In case the integrated
1580 is no longer needed it may be deleted with
1583 Show the status of each affected file, using the following status codes:
1584 .Bl -column YXZ description
1585 .It U Ta file was updated
1586 .It D Ta file was deleted
1587 .It A Ta new file was added
1588 .It \(a~ Ta versioned file is obstructed by a non-regular file
1589 .It ! Ta a missing versioned file was restored
1593 will refuse to run if certain preconditions are not met.
1594 Most importantly, the
1596 must have been rebased onto the work tree's current branch with
1598 before it can be integrated, in order to linearize commit history and
1599 resolve merge conflicts.
1600 If the work tree contains multiple base commits it must first be updated
1601 to a single base commit with
1603 If changes have been staged with
1605 these changes must first be committed with
1609 If the work tree contains local changes, these changes must first be
1617 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1618 Stage local changes for inclusion in the next commit.
1621 is specified, stage all changes in the work tree.
1622 Otherwise, stage changes at or within the specified paths.
1623 Paths may be staged if they are added, modified, or deleted according to
1626 Show the status of each affected file, using the following status codes:
1627 .Bl -column YXZ description
1628 .It A Ta file addition has been staged
1629 .It M Ta file modification has been staged
1630 .It D Ta file deletion has been staged
1633 Staged file contents are saved in newly created blob objects in the repository.
1634 These blobs will be referred to by tree objects once staged changes have been
1637 Staged changes affect the behaviour of
1642 While paths with staged changes exist, the
1644 command will refuse to commit any paths which do not have staged changes.
1645 Local changes created on top of staged changes can only be committed if
1646 the path is staged again, or if the staged changes are committed first.
1649 command will show both local changes and staged changes.
1652 command is able to display local changes relative to staged changes,
1653 and to display staged changes relative to the repository.
1656 command cannot revert staged changes but may be used to revert
1657 local changes created on top of staged changes.
1664 Instead of staging new changes, list paths which are already staged,
1665 along with the IDs of staged blob objects and stage status codes.
1666 If paths were provided in the command line show the staged paths
1667 among the specified paths.
1668 Otherwise, show all staged paths.
1670 Instead of staging the entire content of a changed file, interactively
1671 select or reject changes for staging based on
1675 (reject change), and
1677 (quit staging this file) responses.
1678 If a file is in modified status, individual patches derived from the
1679 modified file content can be staged.
1680 Files in added or deleted status may only be staged or rejected in
1682 .It Fl F Ar response-script
1690 responses line-by-line from the specified
1692 file instead of prompting interactively.
1696 will refuse to run if certain preconditions are not met.
1697 If a file contains merge conflicts, these conflicts must be resolved first.
1698 If a file is found to be out of date relative to the head commit on the
1699 work tree's current branch, the file must be updated with
1701 before it can be staged (however, this does not prevent the file from
1702 becoming out-of-date at some point after having been staged).
1709 commands will refuse to run while staged changes exist.
1710 If staged changes cannot be committed because a staged path
1711 is out of date, the path must be unstaged with
1713 before it can be updated with
1715 and may then be staged again if necessary.
1719 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1720 Merge staged changes back into the work tree and put affected paths
1721 back into non-staged status.
1724 is specified, unstage all staged changes across the entire work tree.
1725 Otherwise, unstage changes at or within the specified paths.
1727 Show the status of each affected file, using the following status codes:
1728 .Bl -column YXZ description
1729 .It G Ta file was unstaged
1730 .It C Ta file was unstaged and conflicts occurred during merge
1731 .It ! Ta changes destined for a missing file were not merged
1732 .It D Ta file was staged as deleted and still is deleted
1733 .It d Ta file's deletion was obstructed by local modifications
1734 .It \(a~ Ta changes destined for a non-regular file were not merged
1742 Instead of unstaging the entire content of a changed file, interactively
1743 select or reject changes for unstaging based on
1747 (keep change staged), and
1749 (quit unstaging this file) responses.
1750 If a file is staged in modified status, individual patches derived from the
1751 staged file content can be unstaged.
1752 Files staged in added or deleted status may only be unstaged in their entirety.
1753 .It Fl F Ar response-script
1761 responses line-by-line from the specified
1763 file instead of prompting interactively.
1768 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1769 Parse and print contents of objects to standard output in a line-based
1771 Content of commit, tree, and tag objects is printed in a way similar
1772 to the actual content stored in such objects.
1773 Blob object contents are printed as they would appear in files on disk.
1775 Attempt to interpret each argument as a reference, a tag name, or
1776 an object ID SHA1 hash.
1777 References will be resolved to an object ID.
1778 Tag names will resolved to a tag object.
1779 An abbreviated hash argument will be expanded to a full SHA1 hash
1780 automatically, provided the abbreviation is unique.
1782 If none of the above interpretations produce a valid result, or if the
1784 option is used, attempt to interpret the argument as a path which will
1785 be resolved to the ID of an object found at this path in the repository.
1792 Look up paths in the specified
1794 If this option is not used, paths are looked up in the commit resolved
1795 via the repository's HEAD reference.
1796 The expected argument is a commit ID SHA1 hash or an existing reference
1797 or tag name which will be resolved to a commit ID.
1798 An abbreviated hash argument will be expanded to a full SHA1 hash
1799 automatically, provided the abbreviation is unique.
1800 .It Fl r Ar repository-path
1801 Use the repository at the specified path.
1802 If not specified, assume the repository is located at or above the current
1804 If this directory is a
1806 work tree, use the repository path associated with this work tree.
1808 Interpret all arguments as paths only.
1809 This option can be used to resolve ambiguity in cases where paths
1810 look like tag names, reference names, or object IDs.
1814 .Bl -tag -width GOT_AUTHOR
1816 The author's name and email address for
1821 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1824 may fail to parse commits without an email address in author data,
1828 environment variables with a missing email address.
1834 configuration settings in the repository's
1836 file will override the value of
1842 configuration settings contained in Git's global
1844 configuration file will be used only if the
1846 environment variable is
1849 .It Ev VISUAL , EDITOR
1850 The editor spawned by
1855 .It Ev GOT_LOG_DEFAULT_LIMIT
1856 The default limit on the number of commits traversed by
1858 If set to zero, the limit is unbounded.
1859 This variable will be silently ignored if it is set to a non-numeric value.
1864 Clone an existing Git repository for use with
1868 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1870 Use of HTTP URLs currently requires
1874 .Dl $ git clone --bare https://github.com/openbsd/src.git
1876 Alternatively, for quick and dirty local testing of
1878 a new Git repository could be created and populated with files,
1879 e.g. from a temporary CVS checkout located at
1882 .Dl $ got init /var/git/src.git
1883 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1885 Check out a work tree from the Git repository to /usr/src:
1887 .Dl $ got checkout /var/git/src.git /usr/src
1889 View local changes in a work tree directory:
1892 .Dl $ got diff | less
1894 Interactively revert selected local changes in a work tree directory:
1896 .Dl $ got revert -p -R\ .
1898 In a work tree or a git repository directory, list all branch references:
1902 In a work tree or a git repository directory, create a new branch called
1903 .Dq unified-buffer-cache
1904 which is forked off the
1908 .Dl $ got branch unified-buffer-cache master
1910 Switch an existing work tree to the branch
1911 .Dq unified-buffer-cache .
1912 Local changes in the work tree will be preserved and merged if necessary:
1914 .Dl $ got update -b unified-buffer-cache
1916 Create a new commit from local changes in a work tree directory.
1917 This new commit will become the head commit of the work tree's current branch:
1921 In a work tree or a git repository directory, view changes committed in
1922 the 3 most recent commits to the work tree's branch, or the branch resolved
1923 via the repository's HEAD reference, respectively:
1925 .Dl $ got log -p -l 3
1927 In a work tree or a git repository directory, log the history of a subdirectory:
1929 .Dl $ got log sys/uvm
1931 While operating inside a work tree, paths are specified relative to the current
1932 working directory, so this command will log the subdirectory
1935 .Dl $ cd sys/uvm && got log '.'
1937 And this command has the same effect:
1939 .Dl $ cd sys/dev/usb && got log ../../uvm
1941 Add new files and remove obsolete files in a work tree directory:
1943 .Dl $ got add sys/uvm/uvm_ubc.c
1944 .Dl $ got remove sys/uvm/uvm_vnode.c
1946 Create a new commit from local changes in a work tree directory
1947 with a pre-defined log message.
1949 .Dl $ got commit -m 'unify the buffer cache'
1951 Update any work tree checked out from the
1952 .Dq unified-buffer-cache
1953 branch to the latest commit on this branch:
1957 Roll file content on the unified-buffer-cache branch back by one commit,
1958 and then fetch the rolled-back change into the work tree as a local change
1959 to be amended and perhaps committed again:
1961 .Dl $ got backout unified-buffer-cache
1962 .Dl $ got commit -m 'roll back previous'
1963 .Dl $ # now back out the previous backout :-)
1964 .Dl $ got backout unified-buffer-cache
1966 Fetch new upstream commits into the local repository's
1973 In a repository created with a HTTP URL and
1974 .Cm git clone --bare
1977 command must be used instead:
1979 .Dl $ cd /var/git/src.git
1980 .Dl $ git fetch origin master:refs/remotes/origin/master
1984 branch to merge the new changes that are now visible on the
1989 .Dl $ got update -b origin/master
1990 .Dl $ got rebase master
1993 .Dq unified-buffer-cache
1994 branch on top of the new head commit of the
1998 .Dl $ got update -b master
1999 .Dl $ got rebase unified-buffer-cache
2001 Create a patch from all changes on the unified-buffer-cache branch.
2002 The patch can be mailed out for review and applied to
2006 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
2008 Edit the entire commit history of the
2009 .Dq unified-buffer-cache
2012 .Dl $ got update -b unified-buffer-cache
2013 .Dl $ got update -c master
2016 In order to merge changes committed to the
2017 .Dq unified-buffer-cache
2018 branch back into the
2021 .Dq unified-buffer-cache
2022 branch must first be rebased onto the
2026 .Dl $ got update -b master
2027 .Dl $ got rebase unified-buffer-cache
2030 .Dq unified-buffer-cache
2031 branch can now be made visible on the
2035 Because the rebase operation switched the work tree to the
2036 .Dq unified-buffer-cache
2037 branch, the work tree must be switched back to the
2040 .Dq unified-buffer-cache
2041 branch can be integrated into
2044 .Dl $ got update -b master
2045 .Dl $ got integrate unified-buffer-cache
2047 Additional steps may be necessary if local changes need to be pushed back
2048 to the remote repository, which currently requires
2050 Before working against existing branches in a repository cloned with
2051 .Cm git clone --bare
2056 must be configured to map all references in the remote repository
2059 namespace of the local repository.
2060 This can achieved by setting Git's
2061 .Pa remote.origin.fetch
2062 configuration variable to the value
2063 .Dq +refs/heads/*:refs/remotes/origin/*
2068 .Dl $ cd /var/git/repo
2069 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
2073 option must be disabled:
2075 .Dl $ cd /var/git/repo
2076 .Dl $ git config remote.origin.mirror false
2078 Alternatively, the following
2080 configuration item can be added manually to the Git repository's
2084 .Dl [remote "origin"]
2086 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2089 This configuration leaves the local repository's
2091 namespace free for use by local branches checked out with
2093 and, if needed, created with
2098 namespace can now be updated with incoming changes from the remote
2103 without extra command line arguments:
2105 .Dl $ cd /var/git/repo
2108 To make changes fetched from the remote repository appear on the
2112 branch must be rebased onto the
2115 This will also merge local changes, if any, with the incoming changes:
2117 .Dl $ got update -b origin/master
2118 .Dl $ got rebase master
2122 branch, log messages for local changes can now be amended with
2124 by other developers and any other important new information:
2126 .Dl $ got update -c origin/master
2127 .Dl $ got histedit -m
2129 Local changes on the
2131 branch can then be pushed to the remote
2135 .Dl $ cd /var/git/repo
2136 .Dl $ git push origin master
2139 .Xr git-repository 5 ,
2142 .An Stefan Sperling Aq Mt stsp@openbsd.org
2143 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2144 .An Joshua Stein Aq Mt jcs@openbsd.org
2145 .An Ori Bernstein Aq Mt ori@openbsd.org
2148 is a work-in-progress and many commands remain to be implemented.
2149 At present, the user has to fall back on
2151 to perform many tasks, in particular tasks related to repository
2152 administration and tasks which require a network connection.
