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 cloning 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
285 The references will be mapped into the cloned repository's
287 namespace, unless the
289 option is used to mirror references directly into the cloned repository's
294 will refuse to fetch references from the remote repository's
303 .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 Op Ar remote-repository
304 Fetch new changes from a remote repository.
306 .Ar remote-repository
310 The remote repository's URL is obtained from the corresponding entry in the
312 file of the local repository, as created by
315 New changes will be stored in a separate pack file downloaded from the server.
316 Optionally, separate pack files stored in the repository can be combined with
319 By default, branch references in the
321 reference namespace will be updated to point at the newly fetched commits.
324 command can then be used to make new changes visible on local branches in the
326 namespace, merging incoming changes with local changes as necessary.
328 If the repository was created as a mirror with
330 then all branches in the
332 namespace will be updated directly to match the corresponding branches in
333 the remote repository.
334 If those branches contained local commits, these commits will no longer be
335 reachable via a reference and will therefore be at risk of being discarded
336 by Git's garbage collector.
337 Maintaining local changes in a mirror repository is therefore discouraged.
339 In any case, references in the
341 namespace will always be fetched and mapped directly to local references
342 in the same namespace.
349 Fetch all branches from the remote repository's
352 If this option is not specified, a branch resolved via the remote
353 repository's HEAD reference will be fetched.
354 Cannot be used together with the
360 from the remote repository's
363 This option may be specified multiple times to build a list of branches
365 If this option is not specified, a branch resolved via the remote
366 repository's HEAD reference will be fetched.
367 Cannot be used together with the
371 Delete branches and tags from the local repository which are no longer
372 present in the remote repository.
373 Only references are deleted.
374 Any commit, tree, tag, and blob objects belonging to deleted branches or
375 tags remain in the repository and may be removed separately with
376 Git's garbage collector.
378 List branches and tags available for fetching from the remote repository
379 and exit immediately.
380 Cannot be used together with any of the other options except
385 Allow existing references in the
387 namespace to be updated if they have changed on the server.
388 If not specified, only new tag references will be created.
389 .It Fl r Ar repository-path
390 Use the repository at the specified path.
391 If not specified, assume the repository is located at or above the current
393 If this directory is a
395 work tree, use the repository path associated with this work tree.
397 Suppress progress reporting output.
398 The same option will be passed to
405 to print debugging messages to standard error output.
406 The same option will be passed to
409 Multiple -v options increase the verbosity.
411 .It Fl R Ar reference
412 In addition to the branches and tags that will be fetched, fetch an arbitrary
414 from the remote repository's
417 This option may be specified multiple times to build a list of additional
420 Each reference will be mapped into the local repository's
422 namespace, unless the local repository was created as a mirror with
424 Once a reference has been fetched, a local branch based on it can be
430 will refuse to fetch references from the remote repository's
439 .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
440 Copy files from a repository into a new work tree.
441 Show the status of each affected file, using the following status codes:
442 .Bl -column YXZ description
443 .It A Ta new file was added
444 .It E Ta file already exists in work tree's meta-data
449 is not specified, either use the last component of
450 .Ar repository path ,
453 was specified use the last component of
461 Proceed with the checkout operation even if the directory at
464 Existing files will be left intact.
466 Check out files from a commit on the specified
468 If this option is not specified, a branch resolved via the repository's HEAD
469 reference will be used.
471 Check out files from the specified
473 on the selected branch.
474 The expected argument is a commit ID SHA1 hash or an existing reference
475 or tag name which will be resolved to a commit ID.
476 An abbreviated hash argument will be expanded to a full SHA1 hash
477 automatically, provided the abbreviation is unique.
478 If this option is not specified, the most recent commit on the selected
483 is not contained in the selected branch, a different branch which contains
484 this commit must be specified with the
487 If no such branch is known a new branch must be created for this
493 Checking out work trees with an unknown branch is intentionally not supported.
494 .It Fl p Ar path-prefix
495 Restrict the work tree to a subset of the repository's tree hierarchy.
496 Only files beneath the specified
503 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
504 Update an existing work tree to a different commit.
505 Show the status of each affected file, using the following status codes:
506 .Bl -column YXZ description
507 .It U Ta file was updated and contained no local changes
508 .It G Ta file was updated and local changes were merged cleanly
509 .It C Ta file was updated and conflicts occurred during merge
510 .It D Ta file was deleted
511 .It A Ta new file was added
512 .It \(a~ Ta versioned file is obstructed by a non-regular file
513 .It ! Ta a missing versioned file was restored
518 is specified, update the entire work tree.
519 Otherwise, restrict the update operation to files at or within the
521 Each path is required to exist in the update operation's target commit.
522 Files in the work tree outside specified paths will remain unchanged and
523 will retain their previously recorded base commit.
526 commands may refuse to run while the work tree contains files from
527 multiple base commits.
528 The base commit of such a work tree can be made consistent by running
530 across the entire work tree.
533 is incompatible with the
538 cannot update paths with staged changes.
539 If changes have been staged with
541 these changes must first be committed with
551 Switch the work tree's branch reference to the specified
553 before updating the work tree.
554 This option requires that all paths in the work tree are updated.
556 Update the work tree to the specified
558 The expected argument is a commit ID SHA1 hash or an existing reference
559 or tag name which will be resolved to a commit ID.
560 An abbreviated hash argument will be expanded to a full SHA1 hash
561 automatically, provided the abbreviation is unique.
562 If this option is not specified, the most recent commit on the work tree's
568 .It Cm status Op Ar path ...
569 Show the current modification status of files in a work tree,
570 using the following status codes:
571 .Bl -column YXZ description
572 .It M Ta modified file
573 .It A Ta file scheduled for addition in next commit
574 .It D Ta file scheduled for deletion in next commit
575 .It C Ta modified or added file which contains merge conflicts
576 .It ! Ta versioned file was expected on disk but is missing
577 .It \(a~ Ta versioned file is obstructed by a non-regular file
578 .It ? Ta unversioned item not tracked by
580 .It m Ta modified file modes (executable bit only)
581 .It N Ta non-existent
583 specified on the command line
588 is specified, show modifications in the entire work tree.
589 Otherwise, show modifications at or within the specified paths.
591 If changes have been staged with
593 staged changes are shown in the second output column, using the following
595 .Bl -column YXZ description
596 .It M Ta file modification is staged
597 .It A Ta file addition is staged
598 .It D Ta file deletion is staged
601 Changes created on top of staged changes are indicated in the first column:
602 .Bl -column YXZ description
603 .It MM Ta file was modified after earlier changes have been staged
604 .It MA Ta file was modified after having been staged for addition
607 For compatibility with
618 files in each traversed directory and will not display unversioned files
619 which match these patterns.
624 supports consecutive asterisks,
626 which will match an arbitrary amount of directories.
630 only supports a single ignore pattern per line.
634 does not support negated ignore patterns prefixed with
636 and gives no special significance to the location of path component separators,
642 .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
643 Display history of a repository.
646 is specified, show only commits which modified this path.
647 If invoked in a work tree, the
649 is interpreted relative to the current working directory,
650 and the work tree's path prefix is implicitly prepended.
651 Otherwise, the path is interpreted relative to the repository root.
658 Display individual commits which were merged into the current branch
662 shows the linear history of the current branch only.
664 Start traversing history at the specified
666 The expected argument is a commit ID SHA1 hash or an existing reference
667 or tag name which will be resolved to a commit ID.
668 An abbreviated hash argument will be expanded to a full SHA1 hash
669 automatically, provided the abbreviation is unique.
670 If this option is not specified, default to the work tree's current branch
671 if invoked in a work tree, or to the repository's HEAD reference.
673 Set the number of context lines shown in diffs with
675 By default, 3 lines of context are shown.
677 Limit history traversal to a given number of commits.
678 If this option is not specified, a default limit value of zero is used,
679 which is treated as an unbounded limit.
681 .Ev GOT_LOG_DEFAULT_LIMIT
682 environment variable may be set to change this default value.
684 Display the patch of modifications made in each commit.
687 is specified, only show the patch of modifications at or within this path.
688 .It Fl s Ar search-pattern
689 If specified, show only commits with a log message matched by the extended
692 Regular expression syntax is documented in
694 .It Fl r Ar repository-path
695 Use the repository at the specified path.
696 If not specified, assume the repository is located at or above the current
698 If this directory is a
700 work tree, use the repository path associated with this work tree.
702 .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
703 When invoked within a work tree with less than two arguments, display
704 uncommitted changes in the work tree.
707 is specified, only show changes within this path.
709 If two arguments are provided, treat each argument as a reference, a tag
710 name, or an object ID SHA1 hash, and display differences between the
711 corresponding objects.
712 Both objects must be of the same type (blobs, trees, or commits).
713 An abbreviated hash argument will be expanded to a full SHA1 hash
714 automatically, provided the abbreviation is unique.
721 Set the number of context lines shown in the diff.
722 By default, 3 lines of context are shown.
723 .It Fl r Ar repository-path
724 Use the repository at the specified path.
725 If not specified, assume the repository is located at or above the current
727 If this directory is a
729 work tree, use the repository path associated with this work tree.
731 Show changes staged with
733 instead of showing local changes.
734 This option is only valid when
736 is invoked in a work tree.
738 Ignore whitespace-only changes.
743 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
744 Display line-by-line history of a file at the specified path.
751 Start traversing history at the specified
753 The expected argument is a commit ID SHA1 hash or an existing reference
754 or tag name which will be resolved to a commit ID.
755 An abbreviated hash argument will be expanded to a full SHA1 hash
756 automatically, provided the abbreviation is unique.
757 .It Fl r Ar repository-path
758 Use the repository at the specified path.
759 If not specified, assume the repository is located at or above the current
761 If this directory is a
763 work tree, use the repository path associated with this work tree.
768 .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
769 Display a listing of files and directories at the specified
770 directory path in the repository.
771 Entries shown in this listing may carry one of the following trailing
773 .Bl -column YXZ description
774 .It @ Ta entry is a symbolic link
775 .It / Ta entry is a directory
776 .It * Ta entry is an executable file
777 .It $ Ta entry is a Git submodule
782 is specified, list the repository path corresponding to the current
783 directory of the work tree, or the root directory of the repository
784 if there is no work tree.
791 List files and directories as they appear in the specified
793 The expected argument is a commit ID SHA1 hash or an existing reference
794 or tag name which will be resolved to a commit ID.
795 An abbreviated hash argument will be expanded to a full SHA1 hash
796 automatically, provided the abbreviation is unique.
797 .It Fl r Ar repository-path
798 Use the repository at the specified path.
799 If not specified, assume the repository is located at or above the current
801 If this directory is a
803 work tree, use the repository path associated with this work tree.
805 Show object IDs of files (blob objects) and directories (tree objects).
807 Recurse into sub-directories in the repository.
812 .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
813 Manage references in a repository.
815 If no options are passed, expect two arguments and attempt to create,
816 or update, the reference with the given
818 and make it point at the given
820 The name must be an absolute reference name, i.e. it must begin with
822 The target may be an object ID SHA1 hash or an existing reference which
823 will be resolved to an object ID.
824 An abbreviated hash argument will be expanded to a full SHA1 hash
825 automatically, provided the abbreviation is unique.
831 .It Fl r Ar repository-path
832 Use the repository at the specified path.
833 If not specified, assume the repository is located at or above the current
835 If this directory is a
837 work tree, use the repository path associated with this work tree.
839 List all existing references in the repository.
841 Delete the reference with the specified name from the repository.
843 Create a symbolic reference pointing at the specified
845 which must be an existing reference.
846 Care should be taken not to create loops between references when
849 .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
850 Create, list, or delete branches.
852 Branches are managed via references which live in the
857 command operates on references in this namespace only.
859 If invoked in a work tree without any arguments, print the name of the
860 work tree's current branch.
864 argument is passed, attempt to create a branch reference with the given name.
865 By default the new branch reference will point at the latest commit on the
866 work tree's current branch if invoked in a work tree, and otherwise to a commit
867 resolved via the repository's HEAD reference.
869 If invoked in a work tree, once the branch was created successfully
870 switch the work tree's head reference to the newly created branch and
871 update files across the entire work tree, just like
872 .Cm got update -b Ar name
874 Show the status of each affected file, using the following status codes:
875 .Bl -column YXZ description
876 .It U Ta file was updated and contained no local changes
877 .It G Ta file was updated and local changes were merged cleanly
878 .It C Ta file was updated and conflicts occurred during merge
879 .It D Ta file was deleted
880 .It A Ta new file was added
881 .It \(a~ Ta versioned file is obstructed by a non-regular file
882 .It ! Ta a missing versioned file was restored
890 Make a newly created branch reference point at the specified
894 argument is a commit ID SHA1 hash or an existing reference
895 or tag name which will be resolved to a commit ID.
896 .It Fl r Ar repository-path
897 Use the repository at the specified path.
898 If not specified, assume the repository is located at or above the current
900 If this directory is a
902 work tree, use the repository path associated with this work tree.
904 List all existing branches in the repository.
905 If invoked in a work tree, the work tree's current branch is shown
906 with one the following annotations:
907 .Bl -column YXZ description
908 .It * Ta work tree's base commit matches the branch tip
909 .It \(a~ Ta work tree's base commit is out-of-date
912 Delete the branch with the specified name from the repository.
913 Only the branch reference is deleted.
914 Any commit, tree, and blob objects belonging to the branch
915 remain in the repository and may be removed separately with
916 Git's garbage collector.
918 Do not switch and update the work tree after creating a new branch.
923 .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
924 Manage tags in a repository.
926 Tags are managed via references which live in the
931 command operates on references in this namespace only.
932 References in this namespace point at tag objects which contain a pointer
933 to another object, a tag message, as well as author and timestamp information.
935 Attempt to create a tag with the given
937 and make this tag point at the given
939 If no commit is specified, default to the latest commit on the work tree's
940 current branch if invoked in a work tree, and to a commit resolved via
941 the repository's HEAD reference otherwise.
948 Make the newly created tag reference point at the specified
952 argument is a commit ID SHA1 hash or an existing reference or tag name which
953 will be resolved to a commit ID.
954 An abbreviated hash argument will be expanded to a full SHA1 hash
955 automatically, provided the abbreviation is unique.
957 Use the specified tag message when creating the new tag.
962 opens a temporary file in an editor where a tag message can be written.
963 .It Fl r Ar repository-path
964 Use the repository at the specified path.
965 If not specified, assume the repository is located at or above the current
967 If this directory is a
969 work tree, use the repository path associated with this work tree.
971 List all existing tags in the repository instead of creating a new tag.
972 If this option is used, no other command-line arguments are allowed.
977 command will not delete tags or change existing tags.
978 If a tag must be deleted, the
980 command may be used to delete a tag's reference.
981 This should only be done if the tag has not already been copied to
983 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
984 Schedule unversioned files in a work tree for addition to the
985 repository in the next commit.
992 Permit recursion into directories.
993 If this option is not specified,
995 will refuse to run if a specified
999 With -R, add files even if they match a
1003 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
1004 Remove versioned files from a work tree and schedule them for deletion
1005 from the repository in the next commit.
1012 Perform the operation even if a file contains uncommitted modifications.
1014 Keep affected files on disk.
1016 Permit recursion into directories.
1017 If this option is not specified,
1019 will refuse to run if a specified
1026 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
1027 Revert any uncommitted changes in files at the specified paths.
1028 File contents will be overwritten with those contained in the
1029 work tree's base commit.
1030 There is no way to bring discarded changes back after
1033 If a file was added with
1035 it will become an unversioned file again.
1036 If a file was deleted with
1038 it will be restored.
1045 Instead of reverting all changes in files, interactively select or reject
1046 changes to revert based on
1052 (quit reverting this file) responses.
1053 If a file is in modified status, individual patches derived from the
1054 modified file content can be reverted.
1055 Files in added or deleted status may only be reverted in their entirety.
1056 .It Fl F Ar response-script
1064 responses line-by-line from the specified
1066 file instead of prompting interactively.
1068 Permit recursion into directories.
1069 If this option is not specified,
1071 will refuse to run if a specified
1078 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1079 Create a new commit in the repository from changes in a work tree
1080 and use this commit as the new base commit for the work tree.
1083 is specified, commit all changes in the work tree.
1084 Otherwise, commit changes at or within the specified paths.
1086 If changes have been explicitly staged for commit with
1088 only commit staged changes and reject any specified paths which
1089 have not been staged.
1091 Show the status of each affected file, using the following status codes:
1092 .Bl -column YXZ description
1093 .It M Ta modified file
1094 .It D Ta file was deleted
1095 .It A Ta new file was added
1096 .It m Ta modified file modes (executable bit only)
1099 Files which are not part of the new commit will retain their previously
1100 recorded base commit.
1103 commands may refuse to run while the work tree contains files from
1104 multiple base commits.
1105 The base commit of such a work tree can be made consistent by running
1107 across the entire work tree.
1111 command requires the
1113 environment variable to be set,
1118 configuration settings can be
1119 obtained from the repository's
1121 file or from Git's global
1130 Use the specified log message when creating the new commit.
1135 opens a temporary file in an editor where a log message can be written.
1139 will refuse to run if certain preconditions are not met.
1140 If the work tree's current branch is not in the
1142 reference namespace, new commits may not be created on this branch.
1143 Local changes may only be committed if they are based on file content
1144 found in the most recent commit on the work tree's branch.
1145 If a path is found to be out of date,
1147 must be used first in order to merge local changes with changes made
1152 .It Cm cherrypick Ar commit
1153 Merge changes from a single
1158 must be on a different branch than the work tree's base commit.
1159 The expected argument is a reference or a commit ID SHA1 hash.
1160 An abbreviated hash argument will be expanded to a full SHA1 hash
1161 automatically, provided the abbreviation is unique.
1163 Show the status of each affected file, using the following status codes:
1164 .Bl -column YXZ description
1165 .It G Ta file was merged
1166 .It C Ta file was merged and conflicts occurred during merge
1167 .It ! Ta changes destined for a missing file were not merged
1168 .It D Ta file was deleted
1169 .It d Ta file's deletion was obstructed by local modifications
1170 .It A Ta new file was added
1171 .It \(a~ Ta changes destined for a non-regular file were not merged
1174 The merged changes will appear as local changes in the work tree, which
1177 amended manually or with further
1182 or discarded again with
1186 will refuse to run if certain preconditions are not met.
1187 If the work tree contains multiple base commits it must first be updated
1188 to a single base commit with
1190 If the work tree already contains files with merge conflicts, these
1191 conflicts must be resolved first.
1195 .It Cm backout Ar commit
1196 Reverse-merge changes from a single
1201 must be on the same branch as the work tree's base commit.
1202 The expected argument is a reference or a commit ID SHA1 hash.
1203 An abbreviated hash argument will be expanded to a full SHA1 hash
1204 automatically, provided the abbreviation is unique.
1206 Show the status of each affected file, using the following status codes:
1207 .Bl -column YXZ description
1208 .It G Ta file was merged
1209 .It C Ta file was merged and conflicts occurred during merge
1210 .It ! Ta changes destined for a missing file were not merged
1211 .It D Ta file was deleted
1212 .It d Ta file's deletion was obstructed by local modifications
1213 .It A Ta new file was added
1214 .It \(a~ Ta changes destined for a non-regular file were not merged
1217 The reverse-merged changes will appear as local changes in the work tree,
1218 which may be viewed with
1220 amended manually or with further
1225 or discarded again with
1229 will refuse to run if certain preconditions are not met.
1230 If the work tree contains multiple base commits it must first be updated
1231 to a single base commit with
1233 If the work tree already contains files with merge conflicts, these
1234 conflicts must be resolved first.
1238 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1239 Rebase commits on the specified
1241 onto the tip of the current branch of the work tree.
1244 must share common ancestry with the work tree's current branch.
1245 Rebasing begins with the first descendant commit of the youngest
1246 common ancestor commit shared by the specified
1248 and the work tree's current branch, and stops once the tip commit
1255 is used as intended, the specified
1257 represents a local commit history and may already contain changes
1258 that are not yet visible in any other repositories.
1259 The work tree's current branch, which must be set with
1263 operation, represents a branch from a remote repository which shares
1264 a common history with the specified
1266 but has progressed, and perhaps diverged, due to commits added to the
1269 Rebased commits are accumulated on a temporary branch which the work tree
1270 will remain switched to throughout the entire rebase operation.
1271 Commits on this branch represent the same changes with the same log
1272 messages as their counterparts on the original
1274 but with different commit IDs.
1275 Once rebasing has completed successfully, the temporary branch becomes
1276 the new version of the specified
1278 and the work tree is automatically switched to it.
1280 While rebasing commits, show the status of each affected file,
1281 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 If merge conflicts occur the rebase operation is interrupted and may
1293 be continued once conflicts have been resolved.
1294 Alternatively, the rebase operation may be aborted which will leave
1296 unmodified and the work tree switched back to its original branch.
1298 If a merge conflict is resolved in a way which renders the merged
1299 change into a no-op change, the corresponding commit will be elided
1300 when the rebase operation continues.
1303 will refuse to run if certain preconditions are not met.
1304 If the work tree is not yet fully updated to the tip commit of its
1305 branch then the work tree must first be updated with
1307 If changes have been staged with
1309 these changes must first be committed with
1313 If the work tree contains local changes, these changes must first be
1320 contains changes to files outside of the work tree's path prefix,
1321 the work tree cannot be used to rebase this branch.
1327 commands will refuse to run while a rebase operation is in progress.
1328 Other commands which manipulate the work tree may be used for
1329 conflict resolution purposes.
1336 Abort an interrupted rebase operation.
1337 If this option is used, no other command-line arguments are allowed.
1339 Continue an interrupted rebase operation.
1340 If this option is used, no other command-line arguments are allowed.
1345 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1346 Edit commit history between the work tree's current base commit and
1347 the tip commit of the work tree's current branch.
1351 operation the work tree's current branch must be set with
1353 to the branch which should be edited, unless this branch is already the
1354 current branch of the work tree.
1355 The tip of this branch represents the upper bound (inclusive) of commits
1360 Furthermore, the work tree's base commit
1363 to a point in this branch's commit history where editing should begin.
1364 This commit represents the lower bound (non-inclusive) of commits touched
1369 Editing of commit history is controlled via a
1371 which can be written in an editor based on a template, passed on the
1372 command line, or generated with the
1374 option if only log messages need to be edited.
1376 The format of the histedit script is line-based.
1377 Each line in the script begins with a command name, followed by
1378 whitespace and an argument.
1379 For most commands, the expected argument is a commit ID SHA1 hash.
1380 Any remaining text on the line is ignored.
1381 Lines which begin with the
1383 character are ignored entirely.
1385 The available commands are as follows:
1386 .Bl -column YXZ pick-commit
1387 .It pick Ar commit Ta Use the specified commit as it is.
1388 .It edit Ar commit Ta Use the specified commit but once changes have been
1389 merged into the work tree interrupt the histedit operation for amending.
1390 .It fold Ar commit Ta Combine the specified commit with the next commit
1391 listed further below that will be used.
1392 .It drop Ar commit Ta Remove this commit from the edited history.
1393 .It mesg Ar log-message Ta Use the specified single-line log message for
1394 the commit on the previous line.
1395 If the log message argument is left empty, open an editor where a new
1396 log message can be written.
1399 Every commit in the history being edited must be mentioned in the script.
1400 Lines may be re-ordered to change the order of commits in the edited history.
1401 No commit may be listed more than once.
1403 Edited commits are accumulated on a temporary branch which the work tree
1404 will remain switched to throughout the entire histedit operation.
1405 Once history editing has completed successfully, the temporary branch becomes
1406 the new version of the work tree's branch and the work tree is automatically
1409 While merging commits, show the status of each affected file,
1410 using the following status codes:
1411 .Bl -column YXZ description
1412 .It G Ta file was merged
1413 .It C Ta file was merged and conflicts occurred during merge
1414 .It ! Ta changes destined for a missing file were not merged
1415 .It D Ta file was deleted
1416 .It d Ta file's deletion was obstructed by local modifications
1417 .It A Ta new file was added
1418 .It \(a~ Ta changes destined for a non-regular file were not merged
1421 If merge conflicts occur the histedit operation is interrupted and may
1422 be continued once conflicts have been resolved.
1423 Alternatively, the histedit operation may be aborted which will leave
1424 the work tree switched back to its original branch.
1426 If a merge conflict is resolved in a way which renders the merged
1427 change into a no-op change, the corresponding commit will be elided
1428 when the histedit operation continues.
1431 will refuse to run if certain preconditions are not met.
1432 If the work tree's current branch is not in the
1434 reference namespace, the history of the branch may not be edited.
1435 If the work tree contains multiple base commits it must first be updated
1436 to a single base commit with
1438 If changes have been staged with
1440 these changes must first be committed with
1444 If the work tree contains local changes, these changes must first be
1449 If the edited history contains changes to files outside of the work tree's
1450 path prefix, the work tree cannot be used to edit the history of this branch.
1457 commands will refuse to run while a histedit operation is in progress.
1458 Other commands which manipulate the work tree may be used, and the
1460 command may be used to commit arbitrary changes to the temporary branch
1461 while the histedit operation is interrupted.
1468 Abort an interrupted histedit operation.
1469 If this option is used, no other command-line arguments are allowed.
1471 Continue an interrupted histedit operation.
1472 If this option is used, no other command-line arguments are allowed.
1473 .It Fl F Ar histedit-script
1476 instead of opening a temporary file in an editor where a histedit script
1479 Edit log messages only.
1480 This option is a quick equivalent to a histedit script which edits
1481 only log messages but otherwise leaves every picked commit as-is.
1484 option can only be used when starting a new histedit operation.
1485 If this option is used, no other command-line arguments are allowed.
1490 .It Cm integrate Ar branch
1491 Integrate the specified
1493 into the work tree's current branch.
1494 Files in the work tree are updated to match the contents on the integrated
1496 and the reference of the work tree's branch is changed to point at the
1497 head commit of the integrated
1500 Both branches can be considered equivalent after integration since they
1501 will be pointing at the same commit.
1502 Both branches remain available for future work, if desired.
1503 In case the integrated
1505 is no longer needed it may be deleted with
1508 Show the status of each affected file, using the following status codes:
1509 .Bl -column YXZ description
1510 .It U Ta file was updated
1511 .It D Ta file was deleted
1512 .It A Ta new file was added
1513 .It \(a~ Ta versioned file is obstructed by a non-regular file
1514 .It ! Ta a missing versioned file was restored
1518 will refuse to run if certain preconditions are not met.
1519 Most importantly, the
1521 must have been rebased onto the work tree's current branch with
1523 before it can be integrated, in order to linearize commit history and
1524 resolve merge conflicts.
1525 If the work tree contains multiple base commits it must first be updated
1526 to a single base commit with
1528 If changes have been staged with
1530 these changes must first be committed with
1534 If the work tree contains local changes, these changes must first be
1542 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1543 Stage local changes for inclusion in the next commit.
1546 is specified, stage all changes in the work tree.
1547 Otherwise, stage changes at or within the specified paths.
1548 Paths may be staged if they are added, modified, or deleted according to
1551 Show the status of each affected file, using the following status codes:
1552 .Bl -column YXZ description
1553 .It A Ta file addition has been staged
1554 .It M Ta file modification has been staged
1555 .It D Ta file deletion has been staged
1558 Staged file contents are saved in newly created blob objects in the repository.
1559 These blobs will be referred to by tree objects once staged changes have been
1562 Staged changes affect the behaviour of
1567 While paths with staged changes exist, the
1569 command will refuse to commit any paths which do not have staged changes.
1570 Local changes created on top of staged changes can only be committed if
1571 the path is staged again, or if the staged changes are committed first.
1574 command will show both local changes and staged changes.
1577 command is able to display local changes relative to staged changes,
1578 and to display staged changes relative to the repository.
1581 command cannot revert staged changes but may be used to revert
1582 local changes created on top of staged changes.
1589 Instead of staging new changes, list paths which are already staged,
1590 along with the IDs of staged blob objects and stage status codes.
1591 If paths were provided in the command line show the staged paths
1592 among the specified paths.
1593 Otherwise, show all staged paths.
1595 Instead of staging the entire content of a changed file, interactively
1596 select or reject changes for staging based on
1600 (reject change), and
1602 (quit staging this file) responses.
1603 If a file is in modified status, individual patches derived from the
1604 modified file content can be staged.
1605 Files in added or deleted status may only be staged or rejected in
1607 .It Fl F Ar response-script
1615 responses line-by-line from the specified
1617 file instead of prompting interactively.
1621 will refuse to run if certain preconditions are not met.
1622 If a file contains merge conflicts, these conflicts must be resolved first.
1623 If a file is found to be out of date relative to the head commit on the
1624 work tree's current branch, the file must be updated with
1626 before it can be staged (however, this does not prevent the file from
1627 becoming out-of-date at some point after having been staged).
1634 commands will refuse to run while staged changes exist.
1635 If staged changes cannot be committed because a staged path
1636 is out of date, the path must be unstaged with
1638 before it can be updated with
1640 and may then be staged again if necessary.
1644 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1645 Merge staged changes back into the work tree and put affected paths
1646 back into non-staged status.
1649 is specified, unstage all staged changes across the entire work tree.
1650 Otherwise, unstage changes at or within the specified paths.
1652 Show the status of each affected file, using the following status codes:
1653 .Bl -column YXZ description
1654 .It G Ta file was unstaged
1655 .It C Ta file was unstaged and conflicts occurred during merge
1656 .It ! Ta changes destined for a missing file were not merged
1657 .It D Ta file was staged as deleted and still is deleted
1658 .It d Ta file's deletion was obstructed by local modifications
1659 .It \(a~ Ta changes destined for a non-regular file were not merged
1667 Instead of unstaging the entire content of a changed file, interactively
1668 select or reject changes for unstaging based on
1672 (keep change staged), and
1674 (quit unstaging this file) responses.
1675 If a file is staged in modified status, individual patches derived from the
1676 staged file content can be unstaged.
1677 Files staged in added or deleted status may only be unstaged in their entirety.
1678 .It Fl F Ar response-script
1686 responses line-by-line from the specified
1688 file instead of prompting interactively.
1693 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1694 Parse and print contents of objects to standard output in a line-based
1696 Content of commit, tree, and tag objects is printed in a way similar
1697 to the actual content stored in such objects.
1698 Blob object contents are printed as they would appear in files on disk.
1700 Attempt to interpret each argument as a reference, a tag name, or
1701 an object ID SHA1 hash.
1702 References will be resolved to an object ID.
1703 Tag names will resolved to a tag object.
1704 An abbreviated hash argument will be expanded to a full SHA1 hash
1705 automatically, provided the abbreviation is unique.
1707 If none of the above interpretations produce a valid result, or if the
1709 option is used, attempt to interpret the argument as a path which will
1710 be resolved to the ID of an object found at this path in the repository.
1717 Look up paths in the specified
1719 If this option is not used, paths are looked up in the commit resolved
1720 via the repository's HEAD reference.
1721 The expected argument is a commit ID SHA1 hash or an existing reference
1722 or tag name which will be resolved to a commit ID.
1723 An abbreviated hash argument will be expanded to a full SHA1 hash
1724 automatically, provided the abbreviation is unique.
1725 .It Fl r Ar repository-path
1726 Use the repository at the specified path.
1727 If not specified, assume the repository is located at or above the current
1729 If this directory is a
1731 work tree, use the repository path associated with this work tree.
1733 Interpret all arguments as paths only.
1734 This option can be used to resolve ambiguity in cases where paths
1735 look like tag names, reference names, or object IDs.
1739 .Bl -tag -width GOT_AUTHOR
1741 The author's name and email address for
1746 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1749 may fail to parse commits without an email address in author data,
1753 environment variables with a missing email address.
1759 configuration settings in the repository's
1761 file will override the value of
1767 configuration settings contained in Git's global
1769 configuration file will be used only if the
1771 environment variable is
1774 .It Ev VISUAL , EDITOR
1775 The editor spawned by
1780 .It Ev GOT_LOG_DEFAULT_LIMIT
1781 The default limit on the number of commits traversed by
1783 If set to zero, the limit is unbounded.
1784 This variable will be silently ignored if it is set to a non-numeric value.
1789 Clone an existing Git repository for use with
1793 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1795 Use of HTTP URLs currently requires
1799 .Dl $ git clone --bare https://github.com/openbsd/src.git
1801 Alternatively, for quick and dirty local testing of
1803 a new Git repository could be created and populated with files,
1804 e.g. from a temporary CVS checkout located at
1807 .Dl $ got init /var/git/src.git
1808 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1810 Check out a work tree from the Git repository to /usr/src:
1812 .Dl $ got checkout /var/git/src.git /usr/src
1814 View local changes in a work tree directory:
1817 .Dl $ got diff | less
1819 Interactively revert selected local changes in a work tree directory:
1821 .Dl $ got revert -p -R\ .
1823 In a work tree or a git repository directory, list all branch references:
1827 In a work tree or a git repository directory, create a new branch called
1828 .Dq unified-buffer-cache
1829 which is forked off the
1833 .Dl $ got branch unified-buffer-cache master
1835 Switch an existing work tree to the branch
1836 .Dq unified-buffer-cache .
1837 Local changes in the work tree will be preserved and merged if necessary:
1839 .Dl $ got update -b unified-buffer-cache
1841 Create a new commit from local changes in a work tree directory.
1842 This new commit will become the head commit of the work tree's current branch:
1846 In a work tree or a git repository directory, view changes committed in
1847 the 3 most recent commits to the work tree's branch, or the branch resolved
1848 via the repository's HEAD reference, respectively:
1850 .Dl $ got log -p -l 3
1852 In a work tree or a git repository directory, log the history of a subdirectory:
1854 .Dl $ got log sys/uvm
1856 While operating inside a work tree, paths are specified relative to the current
1857 working directory, so this command will log the subdirectory
1860 .Dl $ cd sys/uvm && got log '.'
1862 And this command has the same effect:
1864 .Dl $ cd sys/dev/usb && got log ../../uvm
1866 Add new files and remove obsolete files in a work tree directory:
1868 .Dl $ got add sys/uvm/uvm_ubc.c
1869 .Dl $ got remove sys/uvm/uvm_vnode.c
1871 Create a new commit from local changes in a work tree directory
1872 with a pre-defined log message.
1874 .Dl $ got commit -m 'unify the buffer cache'
1876 Update any work tree checked out from the
1877 .Dq unified-buffer-cache
1878 branch to the latest commit on this branch:
1882 Roll file content on the unified-buffer-cache branch back by one commit,
1883 and then fetch the rolled-back change into the work tree as a local change
1884 to be amended and perhaps committed again:
1886 .Dl $ got backout unified-buffer-cache
1887 .Dl $ got commit -m 'roll back previous'
1888 .Dl $ # now back out the previous backout :-)
1889 .Dl $ got backout unified-buffer-cache
1891 Fetch new upstream commits into the local repository's
1898 In a repository created with a HTTP URL and
1899 .Cm git clone --bare
1902 command must be used instead:
1904 .Dl $ cd /var/git/src.git
1905 .Dl $ git fetch origin master:refs/remotes/origin/master
1909 branch to merge the new changes that are now visible on the
1914 .Dl $ got update -b origin/master
1915 .Dl $ got rebase master
1918 .Dq unified-buffer-cache
1919 branch on top of the new head commit of the
1923 .Dl $ got update -b master
1924 .Dl $ got rebase unified-buffer-cache
1926 Create a patch from all changes on the unified-buffer-cache branch.
1927 The patch can be mailed out for review and applied to
1931 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1933 Edit the entire commit history of the
1934 .Dq unified-buffer-cache
1937 .Dl $ got update -b unified-buffer-cache
1938 .Dl $ got update -c master
1941 In order to merge changes committed to the
1942 .Dq unified-buffer-cache
1943 branch back into the
1946 .Dq unified-buffer-cache
1947 branch must first be rebased onto the
1951 .Dl $ got update -b master
1952 .Dl $ got rebase unified-buffer-cache
1955 .Dq unified-buffer-cache
1956 branch can now be made visible on the
1960 Because the rebase operation switched the work tree to the
1961 .Dq unified-buffer-cache
1962 branch, the work tree must be switched back to the
1965 .Dq unified-buffer-cache
1966 branch can be integrated into
1969 .Dl $ got update -b master
1970 .Dl $ got integrate unified-buffer-cache
1972 Additional steps may be necessary if local changes need to be pushed back
1973 to the remote repository, which currently requires
1975 Before working against existing branches in a repository cloned with
1976 .Cm git clone --bare
1981 must be configured to map all references in the remote repository
1984 namespace of the local repository.
1985 This can achieved by setting Git's
1986 .Pa remote.origin.fetch
1987 configuration variable to the value
1988 .Dq +refs/heads/*:refs/remotes/origin/*
1993 .Dl $ cd /var/git/repo
1994 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1997 option must be disabled:
1999 .Dl $ cd /var/git/repo
2000 .Dl $ git config remote.origin.mirror false
2002 Alternatively, the following
2004 configuration item can be added manually to the Git repository's
2008 .Dl [remote "origin"]
2010 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
2013 This configuration leaves the local repository's
2015 namespace free for use by local branches checked out with
2017 and, if needed, created with
2022 namespace can now be updated with incoming changes from the remote
2027 without extra command line arguments:
2029 .Dl $ cd /var/git/repo
2032 To make changes fetched from the remote repository appear on the
2036 branch must be rebased onto the
2039 This will also merge local changes, if any, with the incoming changes:
2041 .Dl $ got update -b origin/master
2042 .Dl $ got rebase master
2046 branch, log messages for local changes can now be amended with
2048 by other developers and any other important new information:
2050 .Dl $ got update -c origin/master
2051 .Dl $ got histedit -m
2053 Local changes on the
2055 branch can then be pushed to the remote
2059 .Dl $ cd /var/git/repo
2060 .Dl $ git push origin master
2063 .Xr git-repository 5 ,
2066 .An Stefan Sperling Aq Mt stsp@openbsd.org
2067 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2068 .An Joshua Stein Aq Mt jcs@openbsd.org
2069 .An Ori Bernstein Aq Mt ori@openbsd.org
2072 is a work-in-progress and many commands remain to be implemented.
2073 At present, the user has to fall back on
2075 to perform many tasks, in particular tasks related to repository
2076 administration and tasks which require a network connection.
