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 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.
206 If this option is not specified, a branch resolved via the remote
207 repository's HEAD reference will be fetched.
208 Cannot be used together with the
214 from the remote repository.
215 This option may be specified multiple times to build a list of branches
217 If the branch corresponding to the remote repository's HEAD reference is not
218 in this list, the cloned repository's HEAD reference will be set to the first
219 branch which was fetched.
220 If this option is not specified, a branch resolved via the remote
221 repository's HEAD reference will be fetched.
222 Cannot be used together with the
226 List branches and tags available for cloning from the remote repository
227 and exit immediately.
228 Cannot be used together with any of the other options except
231 Create the cloned repository as a mirror of the original repository.
232 This is useful if the cloned repository will not be used to store
233 local changes as created by
238 file will be set up with the
240 option enabled, such that
244 will write incoming changes directly to branches in the
246 reference namespace, rather than to branches in the
249 This avoids the usual requirement of having to run
253 in order to make incoming changes appear on branches in the
256 But maintaining custom branches with local changes in the cloned
257 repository becomes difficult since local changes are at risk of
258 being discarded whenever incoming changes are fetched.
260 Suppress progress reporting output.
261 The same option will be passed to
265 Increase the verbosity of progress reporting output.
266 The same option will be passed to
269 Multiple -v options increase the verbosity.
275 .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 q Oc Oo Fl v Oc Op Ar remote-repository
276 Fetch new changes from a remote repository.
278 .Ar remote-repository
282 The remote repository's URL is obtained from the corresponding entry in the
284 file of the local repository, as created by
287 New changes will be stored in a separate pack file downloaded from the server.
288 Optionally, separate pack files stored in the repository can be combined with
291 Branch references in the
293 reference namespace will be updated to point at the newly fetched commits,
296 command can then be used to make new changes visible on branches in the
298 reference namespace, merging incoming changes with local changes as necessary.
300 However, if the repository is configured as a mirror then all references will
301 be updated as needed to match the corresponding references in the remote
302 repository, including branches in the
305 If those branches contained local commits, these commits will no longer be
306 reachable via a reference and will therefore be at risk of being discarded
307 by Git's garbage collector.
309 In any case, existing references in the
311 namespace will always be changed to match tags contained in the remote
319 Fetch all branches from the remote repository.
320 If this option is not specified, a branch resolved via the remote
321 repository's HEAD reference will be fetched.
322 Cannot be used together with the
328 from the remote repository.
329 This option may be specified multiple times to build a list of branches
331 If this option is not specified, a branch resolved via the remote
332 repository's HEAD reference will be fetched.
333 Cannot be used together with the
337 Delete branches and tags from the local repository which are no longer
338 present in the remote repository.
339 Only references are deleted.
340 Any commit, tree, and blob objects belonging to deleted branches or
341 tags remain in the repository and may be removed separately with
342 Git's garbage collector.
344 List branches and tags available for fetching from the remote repository
345 and exit immediately.
346 Cannot be used together with any of the other options except
350 .It Fl r Ar repository-path
351 Use the repository at the specified path.
352 If not specified, assume the repository is located at or above the current
354 If this directory is a
356 work tree, use the repository path associated with this work tree.
358 Suppress progress reporting output.
359 The same option will be passed to
363 Increase the verbosity of progress reporting output.
364 The same option will be passed to
367 Multiple -v options increase the verbosity.
373 .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
374 Copy files from a repository into a new work tree.
375 Show the status of each affected file, using the following status codes:
376 .Bl -column YXZ description
377 .It A Ta new file was added
378 .It E Ta file already exists in work tree's meta-data
383 is not specified, either use the last component of
384 .Ar repository path ,
387 was specified use the last component of
395 Proceed with the checkout operation even if the directory at
398 Existing files will be left intact.
400 Check out files from a commit on the specified
402 If this option is not specified, a branch resolved via the repository's HEAD
403 reference will be used.
405 Check out files from the specified
407 on the selected branch.
408 The expected argument is a commit ID SHA1 hash or an existing reference
409 or tag name which will be resolved to a commit ID.
410 An abbreviated hash argument will be expanded to a full SHA1 hash
411 automatically, provided the abbreviation is unique.
412 If this option is not specified, the most recent commit on the selected
417 is not contained in the selected branch, a different branch which contains
418 this commit must be specified with the
421 If no such branch is known a new branch must be created for this
427 Checking out work trees with an unknown branch is intentionally not supported.
428 .It Fl p Ar path-prefix
429 Restrict the work tree to a subset of the repository's tree hierarchy.
430 Only files beneath the specified
437 .It Cm update Oo Fl b Ar branch Oc Oo Fl c Ar commit Oc Op Ar path ...
438 Update an existing work tree to a different commit.
439 Show the status of each affected file, using the following status codes:
440 .Bl -column YXZ description
441 .It U Ta file was updated and contained no local changes
442 .It G Ta file was updated and local changes were merged cleanly
443 .It C Ta file was updated and conflicts occurred during merge
444 .It D Ta file was deleted
445 .It A Ta new file was added
446 .It \(a~ Ta versioned file is obstructed by a non-regular file
447 .It ! Ta a missing versioned file was restored
452 is specified, update the entire work tree.
453 Otherwise, restrict the update operation to files at or within the
455 Each path is required to exist in the update operation's target commit.
456 Files in the work tree outside specified paths will remain unchanged and
457 will retain their previously recorded base commit.
460 commands may refuse to run while the work tree contains files from
461 multiple base commits.
462 The base commit of such a work tree can be made consistent by running
464 across the entire work tree.
467 is incompatible with the
472 cannot update paths with staged changes.
473 If changes have been staged with
475 these changes must first be committed with
485 Switch the work tree's branch reference to the specified
487 before updating the work tree.
488 This option requires that all paths in the work tree are updated.
490 Update the work tree to the specified
492 The expected argument is a commit ID SHA1 hash or an existing reference
493 or tag name which will be resolved to a commit ID.
494 An abbreviated hash argument will be expanded to a full SHA1 hash
495 automatically, provided the abbreviation is unique.
496 If this option is not specified, the most recent commit on the work tree's
502 .It Cm status Op Ar path ...
503 Show the current modification status of files in a work tree,
504 using the following status codes:
505 .Bl -column YXZ description
506 .It M Ta modified file
507 .It A Ta file scheduled for addition in next commit
508 .It D Ta file scheduled for deletion in next commit
509 .It C Ta modified or added file which contains merge conflicts
510 .It ! Ta versioned file was expected on disk but is missing
511 .It \(a~ Ta versioned file is obstructed by a non-regular file
512 .It ? Ta unversioned item not tracked by
514 .It m Ta modified file modes (executable bit only)
515 .It N Ta non-existent
517 specified on the command line
522 is specified, show modifications in the entire work tree.
523 Otherwise, show modifications at or within the specified paths.
525 If changes have been staged with
527 staged changes are shown in the second output column, using the following
529 .Bl -column YXZ description
530 .It M Ta file modification is staged
531 .It A Ta file addition is staged
532 .It D Ta file deletion is staged
535 Changes created on top of staged changes are indicated in the first column:
536 .Bl -column YXZ description
537 .It MM Ta file was modified after earlier changes have been staged
538 .It MA Ta file was modified after having been staged for addition
541 For compatibility with
552 files in each traversed directory and will not display unversioned files
553 which match these patterns.
558 supports consecutive asterisks,
560 which will match an arbitrary amount of directories.
564 only supports a single ignore pattern per line.
568 does not support negated ignore patterns prefixed with
570 and gives no special significance to the location of path component separators,
576 .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
577 Display history of a repository.
580 is specified, show only commits which modified this path.
581 If invoked in a work tree, the
583 is interpreted relative to the current working directory,
584 and the work tree's path prefix is implicitly prepended.
585 Otherwise, the path is interpreted relative to the repository root.
592 Display individual commits which were merged into the current branch
596 shows the linear history of the current branch only.
598 Start traversing history at the specified
600 The expected argument is a commit ID SHA1 hash or an existing reference
601 or tag name which will be resolved to a commit ID.
602 An abbreviated hash argument will be expanded to a full SHA1 hash
603 automatically, provided the abbreviation is unique.
604 If this option is not specified, default to the work tree's current branch
605 if invoked in a work tree, or to the repository's HEAD reference.
607 Set the number of context lines shown in diffs with
609 By default, 3 lines of context are shown.
611 Limit history traversal to a given number of commits.
612 If this option is not specified, a default limit value of zero is used,
613 which is treated as an unbounded limit.
615 .Ev GOT_LOG_DEFAULT_LIMIT
616 environment variable may be set to change this default value.
618 Display the patch of modifications made in each commit.
621 is specified, only show the patch of modifications at or within this path.
622 .It Fl s Ar search-pattern
623 If specified, show only commits with a log message matched by the extended
626 Regular expression syntax is documented in
628 .It Fl r Ar repository-path
629 Use the repository at the specified path.
630 If not specified, assume the repository is located at or above the current
632 If this directory is a
634 work tree, use the repository path associated with this work tree.
636 .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
637 When invoked within a work tree with less than two arguments, display
638 uncommitted changes in the work tree.
641 is specified, only show changes within this path.
643 If two arguments are provided, treat each argument as a reference, a tag
644 name, or an object ID SHA1 hash, and display differences between the
645 corresponding objects.
646 Both objects must be of the same type (blobs, trees, or commits).
647 An abbreviated hash argument will be expanded to a full SHA1 hash
648 automatically, provided the abbreviation is unique.
655 Set the number of context lines shown in the diff.
656 By default, 3 lines of context are shown.
657 .It Fl r Ar repository-path
658 Use the repository at the specified path.
659 If not specified, assume the repository is located at or above the current
661 If this directory is a
663 work tree, use the repository path associated with this work tree.
665 Show changes staged with
667 instead of showing local changes.
668 This option is only valid when
670 is invoked in a work tree.
672 Ignore whitespace-only changes.
677 .It Cm blame Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Ar path
678 Display line-by-line history of a file at the specified path.
685 Start traversing history at the specified
687 The expected argument is a commit ID SHA1 hash or an existing reference
688 or tag name which will be resolved to a commit ID.
689 An abbreviated hash argument will be expanded to a full SHA1 hash
690 automatically, provided the abbreviation is unique.
691 .It Fl r Ar repository-path
692 Use the repository at the specified path.
693 If not specified, assume the repository is located at or above the current
695 If this directory is a
697 work tree, use the repository path associated with this work tree.
702 .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
703 Display a listing of files and directories at the specified
704 directory path in the repository.
705 Entries shown in this listing may carry one of the following trailing
707 .Bl -column YXZ description
708 .It @ Ta entry is a symbolic link
709 .It / Ta entry is a directory
710 .It * Ta entry is an executable file
711 .It $ Ta entry is a Git submodule
716 is specified, list the repository path corresponding to the current
717 directory of the work tree, or the root directory of the repository
718 if there is no work tree.
725 List files and directories as they appear in the specified
727 The expected argument is a commit ID SHA1 hash or an existing reference
728 or tag name which will be resolved to a commit ID.
729 An abbreviated hash argument will be expanded to a full SHA1 hash
730 automatically, provided the abbreviation is unique.
731 .It Fl r Ar repository-path
732 Use the repository at the specified path.
733 If not specified, assume the repository is located at or above the current
735 If this directory is a
737 work tree, use the repository path associated with this work tree.
739 Show object IDs of files (blob objects) and directories (tree objects).
741 Recurse into sub-directories in the repository.
746 .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
747 Manage references in a repository.
749 If no options are passed, expect two arguments and attempt to create,
750 or update, the reference with the given
752 and make it point at the given
754 The name must be an absolute reference name, i.e. it must begin with
756 The target may be an object ID SHA1 hash or an existing reference which
757 will be resolved to an object ID.
758 An abbreviated hash argument will be expanded to a full SHA1 hash
759 automatically, provided the abbreviation is unique.
765 .It Fl r Ar repository-path
766 Use the repository at the specified path.
767 If not specified, assume the repository is located at or above the current
769 If this directory is a
771 work tree, use the repository path associated with this work tree.
773 List all existing references in the repository.
775 Delete the reference with the specified name from the repository.
777 Create a symbolic reference pointing at the specified
779 which must be an existing reference.
780 Care should be taken not to create loops between references when
783 .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
784 Create, list, or delete branches.
786 Branches are managed via references which live in the
791 command operates on references in this namespace only.
793 If invoked in a work tree without any arguments, print the name of the
794 work tree's current branch.
798 argument is passed, attempt to create a branch reference with the given name.
799 By default the new branch reference will point at the latest commit on the
800 work tree's current branch if invoked in a work tree, and otherwise to a commit
801 resolved via the repository's HEAD reference.
803 If invoked in a work tree, once the branch was created successfully
804 switch the work tree's head reference to the newly created branch and
805 update files across the entire work tree, just like
806 .Cm got update -b Ar name
808 Show the status of each affected file, using the following status codes:
809 .Bl -column YXZ description
810 .It U Ta file was updated and contained no local changes
811 .It G Ta file was updated and local changes were merged cleanly
812 .It C Ta file was updated and conflicts occurred during merge
813 .It D Ta file was deleted
814 .It A Ta new file was added
815 .It \(a~ Ta versioned file is obstructed by a non-regular file
816 .It ! Ta a missing versioned file was restored
824 Make a newly created branch reference point at the specified
828 argument is a commit ID SHA1 hash or an existing reference
829 or tag name which will be resolved to a commit ID.
830 .It Fl r Ar repository-path
831 Use the repository at the specified path.
832 If not specified, assume the repository is located at or above the current
834 If this directory is a
836 work tree, use the repository path associated with this work tree.
838 List all existing branches in the repository.
839 If invoked in a work tree, the work tree's current branch is shown
840 with one the following annotations:
841 .Bl -column YXZ description
842 .It * Ta work tree's base commit matches the branch tip
843 .It \(a~ Ta work tree's base commit is out-of-date
846 Delete the branch with the specified name from the repository.
847 Only the branch reference is deleted.
848 Any commit, tree, and blob objects belonging to the branch
849 remain in the repository and may be removed separately with
850 Git's garbage collector.
852 Do not switch and update the work tree after creating a new branch.
857 .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
858 Manage tags in a repository.
860 Tags are managed via references which live in the
865 command operates on references in this namespace only.
866 References in this namespace point at tag objects which contain a pointer
867 to another object, a tag message, as well as author and timestamp information.
869 Attempt to create a tag with the given
871 and make this tag point at the given
873 If no commit is specified, default to the latest commit on the work tree's
874 current branch if invoked in a work tree, and to a commit resolved via
875 the repository's HEAD reference otherwise.
882 Make the newly created tag reference point at the specified
886 argument is a commit ID SHA1 hash or an existing reference or tag name which
887 will be resolved to a commit ID.
888 An abbreviated hash argument will be expanded to a full SHA1 hash
889 automatically, provided the abbreviation is unique.
891 Use the specified tag message when creating the new tag.
896 opens a temporary file in an editor where a tag message can be written.
897 .It Fl r Ar repository-path
898 Use the repository at the specified path.
899 If not specified, assume the repository is located at or above the current
901 If this directory is a
903 work tree, use the repository path associated with this work tree.
905 List all existing tags in the repository instead of creating a new tag.
906 If this option is used, no other command-line arguments are allowed.
911 command will not delete tags or change existing tags.
912 If a tag must be deleted, the
914 command may be used to delete a tag's reference.
915 This should only be done if the tag has not already been copied to
917 .It Cm add Oo Fl R Oc Oo Fl I Oc Ar path ...
918 Schedule unversioned files in a work tree for addition to the
919 repository in the next commit.
926 Permit recursion into directories.
927 If this option is not specified,
929 will refuse to run if a specified
933 With -R, add files even if they match a
937 .It Cm remove Oo Fl f Oc Oo Fl k Oc Oo Fl R Oc Ar path ...
938 Remove versioned files from a work tree and schedule them for deletion
939 from the repository in the next commit.
946 Perform the operation even if a file contains uncommitted modifications.
948 Keep affected files on disk.
950 Permit recursion into directories.
951 If this option is not specified,
953 will refuse to run if a specified
960 .It Cm revert Oo Fl p Oc Oo Fl F Ar response-script Oc Oo Fl R Oc Ar path ...
961 Revert any uncommitted changes in files at the specified paths.
962 File contents will be overwritten with those contained in the
963 work tree's base commit.
964 There is no way to bring discarded changes back after
967 If a file was added with
969 it will become an unversioned file again.
970 If a file was deleted with
979 Instead of reverting all changes in files, interactively select or reject
980 changes to revert based on
986 (quit reverting this file) responses.
987 If a file is in modified status, individual patches derived from the
988 modified file content can be reverted.
989 Files in added or deleted status may only be reverted in their entirety.
990 .It Fl F Ar response-script
998 responses line-by-line from the specified
1000 file instead of prompting interactively.
1002 Permit recursion into directories.
1003 If this option is not specified,
1005 will refuse to run if a specified
1012 .It Cm commit Oo Fl m Ar message Oc Op Ar path ...
1013 Create a new commit in the repository from changes in a work tree
1014 and use this commit as the new base commit for the work tree.
1017 is specified, commit all changes in the work tree.
1018 Otherwise, commit changes at or within the specified paths.
1020 If changes have been explicitly staged for commit with
1022 only commit staged changes and reject any specified paths which
1023 have not been staged.
1025 Show the status of each affected file, using the following status codes:
1026 .Bl -column YXZ description
1027 .It M Ta modified file
1028 .It D Ta file was deleted
1029 .It A Ta new file was added
1030 .It m Ta modified file modes (executable bit only)
1033 Files which are not part of the new commit will retain their previously
1034 recorded base commit.
1037 commands may refuse to run while the work tree contains files from
1038 multiple base commits.
1039 The base commit of such a work tree can be made consistent by running
1041 across the entire work tree.
1045 command requires the
1047 environment variable to be set,
1052 configuration settings can be
1053 obtained from the repository's
1055 file or from Git's global
1064 Use the specified log message when creating the new commit.
1069 opens a temporary file in an editor where a log message can be written.
1073 will refuse to run if certain preconditions are not met.
1074 If the work tree's current branch is not in the
1076 reference namespace, new commits may not be created on this branch.
1077 Local changes may only be committed if they are based on file content
1078 found in the most recent commit on the work tree's branch.
1079 If a path is found to be out of date,
1081 must be used first in order to merge local changes with changes made
1086 .It Cm cherrypick Ar commit
1087 Merge changes from a single
1092 must be on a different branch than the work tree's base commit.
1093 The expected argument is a reference or a commit ID SHA1 hash.
1094 An abbreviated hash argument will be expanded to a full SHA1 hash
1095 automatically, provided the abbreviation is unique.
1097 Show the status of each affected file, using the following status codes:
1098 .Bl -column YXZ description
1099 .It G Ta file was merged
1100 .It C Ta file was merged and conflicts occurred during merge
1101 .It ! Ta changes destined for a missing file were not merged
1102 .It D Ta file was deleted
1103 .It d Ta file's deletion was obstructed by local modifications
1104 .It A Ta new file was added
1105 .It \(a~ Ta changes destined for a non-regular file were not merged
1108 The merged changes will appear as local changes in the work tree, which
1111 amended manually or with further
1116 or discarded again with
1120 will refuse to run if certain preconditions are not met.
1121 If the work tree contains multiple base commits it must first be updated
1122 to a single base commit with
1124 If the work tree already contains files with merge conflicts, these
1125 conflicts must be resolved first.
1129 .It Cm backout Ar commit
1130 Reverse-merge changes from a single
1135 must be on the same branch as the work tree's base commit.
1136 The expected argument is a reference or a commit ID SHA1 hash.
1137 An abbreviated hash argument will be expanded to a full SHA1 hash
1138 automatically, provided the abbreviation is unique.
1140 Show the status of each affected file, using the following status codes:
1141 .Bl -column YXZ description
1142 .It G Ta file was merged
1143 .It C Ta file was merged and conflicts occurred during merge
1144 .It ! Ta changes destined for a missing file were not merged
1145 .It D Ta file was deleted
1146 .It d Ta file's deletion was obstructed by local modifications
1147 .It A Ta new file was added
1148 .It \(a~ Ta changes destined for a non-regular file were not merged
1151 The reverse-merged changes will appear as local changes in the work tree,
1152 which may be viewed with
1154 amended manually or with further
1159 or discarded again with
1163 will refuse to run if certain preconditions are not met.
1164 If the work tree contains multiple base commits it must first be updated
1165 to a single base commit with
1167 If the work tree already contains files with merge conflicts, these
1168 conflicts must be resolved first.
1172 .It Cm rebase Oo Fl a Oc Oo Fl c Oc Op Ar branch
1173 Rebase commits on the specified
1175 onto the tip of the current branch of the work tree.
1178 must share common ancestry with the work tree's current branch.
1179 Rebasing begins with the first descendant commit of the youngest
1180 common ancestor commit shared by the specified
1182 and the work tree's current branch, and stops once the tip commit
1189 is used as intended, the specified
1191 represents a local commit history and may already contain changes
1192 that are not yet visible in any other repositories.
1193 The work tree's current branch, which must be set with
1197 operation, represents a branch from a remote repository which shares
1198 a common history with the specified
1200 but has progressed, and perhaps diverged, due to commits added to the
1203 Rebased commits are accumulated on a temporary branch which the work tree
1204 will remain switched to throughout the entire rebase operation.
1205 Commits on this branch represent the same changes with the same log
1206 messages as their counterparts on the original
1208 but with different commit IDs.
1209 Once rebasing has completed successfully, the temporary branch becomes
1210 the new version of the specified
1212 and the work tree is automatically switched to it.
1214 While rebasing commits, show the status of each affected file,
1215 using the following status codes:
1216 .Bl -column YXZ description
1217 .It G Ta file was merged
1218 .It C Ta file was merged and conflicts occurred during merge
1219 .It ! Ta changes destined for a missing file were not merged
1220 .It D Ta file was deleted
1221 .It d Ta file's deletion was obstructed by local modifications
1222 .It A Ta new file was added
1223 .It \(a~ Ta changes destined for a non-regular file were not merged
1226 If merge conflicts occur the rebase operation is interrupted and may
1227 be continued once conflicts have been resolved.
1228 Alternatively, the rebase operation may be aborted which will leave
1230 unmodified and the work tree switched back to its original branch.
1232 If a merge conflict is resolved in a way which renders the merged
1233 change into a no-op change, the corresponding commit will be elided
1234 when the rebase operation continues.
1237 will refuse to run if certain preconditions are not met.
1238 If the work tree is not yet fully updated to the tip commit of its
1239 branch then the work tree must first be updated with
1241 If changes have been staged with
1243 these changes must first be committed with
1247 If the work tree contains local changes, these changes must first be
1254 contains changes to files outside of the work tree's path prefix,
1255 the work tree cannot be used to rebase this branch.
1261 commands will refuse to run while a rebase operation is in progress.
1262 Other commands which manipulate the work tree may be used for
1263 conflict resolution purposes.
1270 Abort an interrupted rebase operation.
1271 If this option is used, no other command-line arguments are allowed.
1273 Continue an interrupted rebase operation.
1274 If this option is used, no other command-line arguments are allowed.
1279 .It Cm histedit Oo Fl a Oc Oo Fl c Oc Oo Fl F Ar histedit-script Oc Oo Fl m Oc
1280 Edit commit history between the work tree's current base commit and
1281 the tip commit of the work tree's current branch.
1285 operation the work tree's current branch must be set with
1287 to the branch which should be edited, unless this branch is already the
1288 current branch of the work tree.
1289 The tip of this branch represents the upper bound (inclusive) of commits
1294 Furthermore, the work tree's base commit
1297 to a point in this branch's commit history where editing should begin.
1298 This commit represents the lower bound (non-inclusive) of commits touched
1303 Editing of commit history is controlled via a
1305 which can be written in an editor based on a template, passed on the
1306 command line, or generated with the
1308 option if only log messages need to be edited.
1310 The format of the histedit script is line-based.
1311 Each line in the script begins with a command name, followed by
1312 whitespace and an argument.
1313 For most commands, the expected argument is a commit ID SHA1 hash.
1314 Any remaining text on the line is ignored.
1315 Lines which begin with the
1317 character are ignored entirely.
1319 The available commands are as follows:
1320 .Bl -column YXZ pick-commit
1321 .It pick Ar commit Ta Use the specified commit as it is.
1322 .It edit Ar commit Ta Use the specified commit but once changes have been
1323 merged into the work tree interrupt the histedit operation for amending.
1324 .It fold Ar commit Ta Combine the specified commit with the next commit
1325 listed further below that will be used.
1326 .It drop Ar commit Ta Remove this commit from the edited history.
1327 .It mesg Ar log-message Ta Use the specified single-line log message for
1328 the commit on the previous line.
1329 If the log message argument is left empty, open an editor where a new
1330 log message can be written.
1333 Every commit in the history being edited must be mentioned in the script.
1334 Lines may be re-ordered to change the order of commits in the edited history.
1335 No commit may be listed more than once.
1337 Edited commits are accumulated on a temporary branch which the work tree
1338 will remain switched to throughout the entire histedit operation.
1339 Once history editing has completed successfully, the temporary branch becomes
1340 the new version of the work tree's branch and the work tree is automatically
1343 While merging commits, show the status of each affected file,
1344 using the following status codes:
1345 .Bl -column YXZ description
1346 .It G Ta file was merged
1347 .It C Ta file was merged and conflicts occurred during merge
1348 .It ! Ta changes destined for a missing file were not merged
1349 .It D Ta file was deleted
1350 .It d Ta file's deletion was obstructed by local modifications
1351 .It A Ta new file was added
1352 .It \(a~ Ta changes destined for a non-regular file were not merged
1355 If merge conflicts occur the histedit operation is interrupted and may
1356 be continued once conflicts have been resolved.
1357 Alternatively, the histedit operation may be aborted which will leave
1358 the work tree switched back to its original branch.
1360 If a merge conflict is resolved in a way which renders the merged
1361 change into a no-op change, the corresponding commit will be elided
1362 when the histedit operation continues.
1365 will refuse to run if certain preconditions are not met.
1366 If the work tree's current branch is not in the
1368 reference namespace, the history of the branch may not be edited.
1369 If the work tree contains multiple base commits it must first be updated
1370 to a single base commit with
1372 If changes have been staged with
1374 these changes must first be committed with
1378 If the work tree contains local changes, these changes must first be
1383 If the edited history contains changes to files outside of the work tree's
1384 path prefix, the work tree cannot be used to edit the history of this branch.
1391 commands will refuse to run while a histedit operation is in progress.
1392 Other commands which manipulate the work tree may be used, and the
1394 command may be used to commit arbitrary changes to the temporary branch
1395 while the histedit operation is interrupted.
1402 Abort an interrupted histedit operation.
1403 If this option is used, no other command-line arguments are allowed.
1405 Continue an interrupted histedit operation.
1406 If this option is used, no other command-line arguments are allowed.
1407 .It Fl F Ar histedit-script
1410 instead of opening a temporary file in an editor where a histedit script
1413 Edit log messages only.
1414 This option is a quick equivalent to a histedit script which edits
1415 only log messages but otherwise leaves every picked commit as-is.
1418 option can only be used when starting a new histedit operation.
1419 If this option is used, no other command-line arguments are allowed.
1424 .It Cm integrate Ar branch
1425 Integrate the specified
1427 into the work tree's current branch.
1428 Files in the work tree are updated to match the contents on the integrated
1430 and the reference of the work tree's branch is changed to point at the
1431 head commit of the integrated
1434 Both branches can be considered equivalent after integration since they
1435 will be pointing at the same commit.
1436 Both branches remain available for future work, if desired.
1437 In case the integrated
1439 is no longer needed it may be deleted with
1442 Show the status of each affected file, using the following status codes:
1443 .Bl -column YXZ description
1444 .It U Ta file was updated
1445 .It D Ta file was deleted
1446 .It A Ta new file was added
1447 .It \(a~ Ta versioned file is obstructed by a non-regular file
1448 .It ! Ta a missing versioned file was restored
1452 will refuse to run if certain preconditions are not met.
1453 Most importantly, the
1455 must have been rebased onto the work tree's current branch with
1457 before it can be integrated, in order to linearize commit history and
1458 resolve merge conflicts.
1459 If the work tree contains multiple base commits it must first be updated
1460 to a single base commit with
1462 If changes have been staged with
1464 these changes must first be committed with
1468 If the work tree contains local changes, these changes must first be
1476 .It Cm stage Oo Fl l Oc Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1477 Stage local changes for inclusion in the next commit.
1480 is specified, stage all changes in the work tree.
1481 Otherwise, stage changes at or within the specified paths.
1482 Paths may be staged if they are added, modified, or deleted according to
1485 Show the status of each affected file, using the following status codes:
1486 .Bl -column YXZ description
1487 .It A Ta file addition has been staged
1488 .It M Ta file modification has been staged
1489 .It D Ta file deletion has been staged
1492 Staged file contents are saved in newly created blob objects in the repository.
1493 These blobs will be referred to by tree objects once staged changes have been
1496 Staged changes affect the behaviour of
1501 While paths with staged changes exist, the
1503 command will refuse to commit any paths which do not have staged changes.
1504 Local changes created on top of staged changes can only be committed if
1505 the path is staged again, or if the staged changes are committed first.
1508 command will show both local changes and staged changes.
1511 command is able to display local changes relative to staged changes,
1512 and to display staged changes relative to the repository.
1515 command cannot revert staged changes but may be used to revert
1516 local changes created on top of staged changes.
1523 Instead of staging new changes, list paths which are already staged,
1524 along with the IDs of staged blob objects and stage status codes.
1525 If paths were provided in the command line show the staged paths
1526 among the specified paths.
1527 Otherwise, show all staged paths.
1529 Instead of staging the entire content of a changed file, interactively
1530 select or reject changes for staging based on
1534 (reject change), and
1536 (quit staging this file) responses.
1537 If a file is in modified status, individual patches derived from the
1538 modified file content can be staged.
1539 Files in added or deleted status may only be staged or rejected in
1541 .It Fl F Ar response-script
1549 responses line-by-line from the specified
1551 file instead of prompting interactively.
1555 will refuse to run if certain preconditions are not met.
1556 If a file contains merge conflicts, these conflicts must be resolved first.
1557 If a file is found to be out of date relative to the head commit on the
1558 work tree's current branch, the file must be updated with
1560 before it can be staged (however, this does not prevent the file from
1561 becoming out-of-date at some point after having been staged).
1568 commands will refuse to run while staged changes exist.
1569 If staged changes cannot be committed because a staged path
1570 is out of date, the path must be unstaged with
1572 before it can be updated with
1574 and may then be staged again if necessary.
1578 .It Cm unstage Oo Fl p Oc Oo Fl F Ar response-script Oc Op Ar path ...
1579 Merge staged changes back into the work tree and put affected paths
1580 back into non-staged status.
1583 is specified, unstage all staged changes across the entire work tree.
1584 Otherwise, unstage changes at or within the specified paths.
1586 Show the status of each affected file, using the following status codes:
1587 .Bl -column YXZ description
1588 .It G Ta file was unstaged
1589 .It C Ta file was unstaged and conflicts occurred during merge
1590 .It ! Ta changes destined for a missing file were not merged
1591 .It D Ta file was staged as deleted and still is deleted
1592 .It d Ta file's deletion was obstructed by local modifications
1593 .It \(a~ Ta changes destined for a non-regular file were not merged
1601 Instead of unstaging the entire content of a changed file, interactively
1602 select or reject changes for unstaging based on
1606 (keep change staged), and
1608 (quit unstaging this file) responses.
1609 If a file is staged in modified status, individual patches derived from the
1610 staged file content can be unstaged.
1611 Files staged in added or deleted status may only be unstaged in their entirety.
1612 .It Fl F Ar response-script
1620 responses line-by-line from the specified
1622 file instead of prompting interactively.
1627 .It Cm cat Oo Fl c Ar commit Oc Oo Fl r Ar repository-path Oc Oo Fl P Oc Ar arg ...
1628 Parse and print contents of objects to standard output in a line-based
1630 Content of commit, tree, and tag objects is printed in a way similar
1631 to the actual content stored in such objects.
1632 Blob object contents are printed as they would appear in files on disk.
1634 Attempt to interpret each argument as a reference, a tag name, or
1635 an object ID SHA1 hash.
1636 References will be resolved to an object ID.
1637 Tag names will resolved to a tag object.
1638 An abbreviated hash argument will be expanded to a full SHA1 hash
1639 automatically, provided the abbreviation is unique.
1641 If none of the above interpretations produce a valid result, or if the
1643 option is used, attempt to interpret the argument as a path which will
1644 be resolved to the ID of an object found at this path in the repository.
1651 Look up paths in the specified
1653 If this option is not used, paths are looked up in the commit resolved
1654 via the repository's HEAD reference.
1655 The expected argument is a commit ID SHA1 hash or an existing reference
1656 or tag name which will be resolved to a commit ID.
1657 An abbreviated hash argument will be expanded to a full SHA1 hash
1658 automatically, provided the abbreviation is unique.
1659 .It Fl r Ar repository-path
1660 Use the repository at the specified path.
1661 If not specified, assume the repository is located at or above the current
1663 If this directory is a
1665 work tree, use the repository path associated with this work tree.
1667 Interpret all arguments as paths only.
1668 This option can be used to resolve ambiguity in cases where paths
1669 look like tag names, reference names, or object IDs.
1673 .Bl -tag -width GOT_AUTHOR
1675 The author's name and email address for
1680 .Dq An Flan Hacker Aq Mt flan_hacker@openbsd.org .
1683 may fail to parse commits without an email address in author data,
1687 environment variables with a missing email address.
1693 configuration settings in the repository's
1695 file will override the value of
1701 configuration settings contained in Git's global
1703 configuration file will be used only if the
1705 environment variable is
1708 .It Ev VISUAL , EDITOR
1709 The editor spawned by
1714 .It Ev GOT_LOG_DEFAULT_LIMIT
1715 The default limit on the number of commits traversed by
1717 If set to zero, the limit is unbounded.
1718 This variable will be silently ignored if it is set to a non-numeric value.
1719 .It Ev GOT_FETCH_DEBUG
1720 Enables protocol tracing on standard error output during
1728 Clone an existing Git repository for use with
1732 .Dl $ got clone ssh://git@github.com/openbsd/src.git
1734 Use of HTTP URLs currently requires
1738 .Dl $ git clone --bare https://github.com/openbsd/src.git
1740 Alternatively, for quick and dirty local testing of
1742 a new Git repository could be created and populated with files,
1743 e.g. from a temporary CVS checkout located at
1746 .Dl $ got init /var/git/src.git
1747 .Dl $ got import -r /var/git/src.git -I CVS -I obj /tmp/src
1749 Check out a work tree from the Git repository to /usr/src:
1751 .Dl $ got checkout /var/git/src.git /usr/src
1753 View local changes in a work tree directory:
1756 .Dl $ got diff | less
1758 Interactively revert selected local changes in a work tree directory:
1760 .Dl $ got revert -p -R\ .
1762 In a work tree or a git repository directory, list all branch references:
1766 In a work tree or a git repository directory, create a new branch called
1767 .Dq unified-buffer-cache
1768 which is forked off the
1772 .Dl $ got branch unified-buffer-cache master
1774 Switch an existing work tree to the branch
1775 .Dq unified-buffer-cache .
1776 Local changes in the work tree will be preserved and merged if necessary:
1778 .Dl $ got update -b unified-buffer-cache
1780 Create a new commit from local changes in a work tree directory.
1781 This new commit will become the head commit of the work tree's current branch:
1785 In a work tree or a git repository directory, view changes committed in
1786 the 3 most recent commits to the work tree's branch, or the branch resolved
1787 via the repository's HEAD reference, respectively:
1789 .Dl $ got log -p -l 3
1791 In a work tree or a git repository directory, log the history of a subdirectory:
1793 .Dl $ got log sys/uvm
1795 While operating inside a work tree, paths are specified relative to the current
1796 working directory, so this command will log the subdirectory
1799 .Dl $ cd sys/uvm && got log '.'
1801 And this command has the same effect:
1803 .Dl $ cd sys/dev/usb && got log ../../uvm
1805 Add new files and remove obsolete files in a work tree directory:
1807 .Dl $ got add sys/uvm/uvm_ubc.c
1808 .Dl $ got remove sys/uvm/uvm_vnode.c
1810 Create a new commit from local changes in a work tree directory
1811 with a pre-defined log message.
1813 .Dl $ got commit -m 'unify the buffer cache'
1815 Update any work tree checked out from the
1816 .Dq unified-buffer-cache
1817 branch to the latest commit on this branch:
1821 Roll file content on the unified-buffer-cache branch back by one commit,
1822 and then fetch the rolled-back change into the work tree as a local change
1823 to be amended and perhaps committed again:
1825 .Dl $ got backout unified-buffer-cache
1826 .Dl $ got commit -m 'roll back previous'
1827 .Dl $ # now back out the previous backout :-)
1828 .Dl $ got backout unified-buffer-cache
1830 Fetch new upstream commits into the local repository's
1837 In a repository created with a HTTP URL and
1838 .Cm git clone --bare
1841 command must be used instead:
1843 .Dl $ cd /var/git/src.git
1844 .Dl $ git fetch origin master:refs/remotes/origin/master
1848 branch to merge the new changes that are now visible on the
1853 .Dl $ got update -b origin/master
1854 .Dl $ got rebase master
1857 .Dq unified-buffer-cache
1858 branch on top of the new head commit of the
1862 .Dl $ got update -b master
1863 .Dl $ got rebase unified-buffer-cache
1865 Create a patch from all changes on the unified-buffer-cache branch.
1866 The patch can be mailed out for review and applied to
1870 .Dl $ got diff master unified-buffer-cache > /tmp/ubc.diff
1872 Edit the entire commit history of the
1873 .Dq unified-buffer-cache
1876 .Dl $ got update -b unified-buffer-cache
1877 .Dl $ got update -c master
1880 In order to merge changes committed to the
1881 .Dq unified-buffer-cache
1882 branch back into the
1885 .Dq unified-buffer-cache
1886 branch must first be rebased onto the
1890 .Dl $ got update -b master
1891 .Dl $ got rebase unified-buffer-cache
1894 .Dq unified-buffer-cache
1895 branch can now be made visible on the
1899 Because the rebase operation switched the work tree to the
1900 .Dq unified-buffer-cache
1901 branch, the work tree must be switched back to the
1904 .Dq unified-buffer-cache
1905 branch can be integrated into
1908 .Dl $ got update -b master
1909 .Dl $ got integrate unified-buffer-cache
1911 Additional steps may be necessary if local changes need to be pushed back
1912 to the remote repository, which currently requires
1914 Before working against existing branches in a repository cloned with
1915 .Cm git clone --bare
1920 must be configured to map all references in the remote repository
1923 namespace of the local repository.
1924 This can achieved by setting Git's
1925 .Pa remote.origin.fetch
1926 configuration variable to the value
1927 .Dq +refs/heads/*:refs/remotes/origin/*
1932 .Dl $ cd /var/git/repo
1933 .Dl $ git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
1936 option must be disabled:
1938 .Dl $ cd /var/git/repo
1939 .Dl $ git config remote.origin.mirror false
1941 Alternatively, the following
1943 configuration item can be added manually to the Git repository's
1947 .Dl [remote "origin"]
1949 .Dl fetch = +refs/heads/*:refs/remotes/origin/*
1952 This configuration leaves the local repository's
1954 namespace free for use by local branches checked out with
1956 and, if needed, created with
1961 namespace can now be updated with incoming changes from the remote
1966 without extra command line arguments:
1968 .Dl $ cd /var/git/repo
1971 To make changes fetched from the remote repository appear on the
1975 branch must be rebased onto the
1978 This will also merge local changes, if any, with the incoming changes:
1980 .Dl $ got update -b origin/master
1981 .Dl $ got rebase master
1985 branch, log messages for local changes can now be amended with
1987 by other developers and any other important new information:
1989 .Dl $ got update -c origin/master
1990 .Dl $ got histedit -m
1992 Local changes on the
1994 branch can then be pushed to the remote
1998 .Dl $ cd /var/git/repo
1999 .Dl $ git push origin master
2002 .Xr git-repository 5 ,
2005 .An Stefan Sperling Aq Mt stsp@openbsd.org
2006 .An Martin Pieuchot Aq Mt mpi@openbsd.org
2007 .An Joshua Stein Aq Mt jcs@openbsd.org
2008 .An Ori Bernstein Aq Mt ori@openbsd.org
2011 is a work-in-progress and many commands remain to be implemented.
2012 At present, the user has to fall back on
2014 to perform many tasks, in particular tasks related to repository
2015 administration and tasks which require a network connection.
