commit - 705cce7454a397f5c9eaa7a44ef383e0659d1242
commit + 21002b1b278e14573f85a3ec87c2aa5b8da47f49
blob - 119d3bd5d96ed7dd1e9875f0a41f1662f5fffd38
blob + 4c1cec0823d60146457085b972328049ac986934
--- cvg/cvg.1
+++ cvg/cvg.1
Multiple -v options increase the verbosity.
The maximum is 3.
.El
-.Tg fe
-.It Xo
-.Cm fetch
-.Op Fl adlqtvX
-.Op Fl b Ar branch
-.Op Fl R Ar reference
-.Op Fl r Ar repository-path
-.Op Ar remote-repository
-.Xc
-.Dl Pq alias: Cm fe
-Fetch new changes from a remote repository.
-If no
-.Ar remote-repository
-is specified,
-.Dq origin
-will be used.
-The remote repository's URL is obtained from the corresponding entry in
-.Xr got.conf 5
-or Git's
-.Pa config
-file of the local repository, as created by
-.Cm got clone .
-.Pp
-By default, any branches configured in
-.Xr got.conf 5
-for the
-.Ar remote-repository
-will be fetched.
-If
-.Cm got fetch
-is invoked in a work tree then this work tree's current branch will be
-fetched, too, provided it is present on the server.
-If no branches to fetch can be found in
-.Xr got.conf 5
-or via a work tree, or said branches are not found on the server, a branch
-resolved via the remote repository's HEAD reference will be fetched.
-Likewise, if a HEAD reference for the
-.Ar remote-repository
-exists but its target no longer matches the remote HEAD, then
-the new target branch will be fetched.
-This default behaviour can be overridden with the
-.Fl a
-and
-.Fl b
-options.
-.Pp
-New changes will be stored in a separate pack file downloaded from the server.
-Optionally, separate pack files stored in the repository can be combined with
-.Xr git-repack 1 .
-.Pp
-By default, branch references in the
-.Dq refs/remotes/
-reference namespace will be updated to point at the newly fetched commits.
-The
-.Cm got rebase
-or
-.Cm got merge
-command can then be used to make new changes visible on branches in the
-.Dq refs/heads/
-namespace, merging incoming changes with the changes on those branches
-as necessary.
-.Pp
-If the repository was created as a mirror with
-.Cm got clone -m ,
-then all branches in the
-.Dq refs/heads/
-namespace will be updated directly to match the corresponding branches in
-the remote repository.
-If those branches contained local commits, these commits will no longer be
-reachable via a reference and will therefore be at risk of being discarded
-by Git's garbage collector or
-.Cm gotadmin cleanup .
-Maintaining custom changes in a mirror repository is therefore discouraged.
-.Pp
-In any case, references in the
-.Dq refs/tags/
-namespace will always be fetched and mapped directly to local references
-in the same namespace.
-.Pp
-The options for
-.Cm got fetch
-are as follows:
-.Bl -tag -width Ds
-.It Fl a
-Fetch all branches from the remote repository's
-.Dq refs/heads/
-reference namespace.
-This option can be enabled by default for specific repositories in
-.Xr got.conf 5 .
-Cannot be used together with the
-.Fl b
-option.
-.It Fl b Ar branch
-Fetch the specified
-.Ar branch
-from the remote repository's
-.Dq refs/heads/
-reference namespace.
-This option may be specified multiple times to build a list of branches
-to fetch.
-Cannot be used together with the
-.Fl a
-option.
-.It Fl d
-Delete branches and tags from the local repository which are no longer
-present in the remote repository.
-Only references are deleted.
-Any commit, tree, tag, and blob objects belonging to deleted branches or
-tags remain in the repository and may be removed separately with
-Git's garbage collector or
-.Cm gotadmin cleanup .
-.It Fl l
-List branches and tags available for fetching from the remote repository
-and exit immediately.
-Cannot be used together with any of the other options except
-.Fl v ,
-.Fl q ,
-and
-.Fl r .
-.It Fl q
-Suppress progress reporting output.
-The same option will be passed to
-.Xr ssh 1
-if applicable.
-.It Fl R Ar reference
-In addition to the branches and tags that will be fetched, fetch an arbitrary
-.Ar reference
-from the remote repository's
-.Dq refs/
-namespace.
-This option may be specified multiple times to build a list of additional
-references to fetch.
-The specified
-.Ar reference
-may either be a path to a specific reference, or a reference namespace
-which will cause all references in this namespace to be fetched.
-.Pp
-Each reference will be mapped into the local repository's
-.Dq refs/remotes/
-namespace, unless the local repository was created as a mirror with
-.Cm got clone -m
-in which case references will be mapped directly into the local repository's
-.Dq refs/
-namespace.
-.Pp
-Once a reference has been fetched, a branch based on it can be created with
-.Cm got branch
-if needed.
-.Pp
-.Cm got fetch
-will refuse to fetch references from the remote repository's
-.Dq refs/remotes/
-or
-.Dq refs/got/
-namespace.
-.It Fl r Ar repository-path
-Use the repository at the specified path.
-If not specified, assume the repository is located at or above the current
-working directory.
-If this directory is a
-.Nm
-work tree, use the repository path associated with this work tree.
-.It Fl t
-Allow existing references in the
-.Dq refs/tags
-namespace to be updated if they have changed on the server.
-If not specified, only new tag references will be created.
-.It Fl v
-Verbose mode.
-Causes
-.Cm got fetch
-to print debugging messages to standard error output.
-The same option will be passed to
-.Xr ssh 1
-if applicable.
-Multiple -v options increase the verbosity.
-The maximum is 3.
-.It Fl X
-Delete all references which correspond to a particular
-.Ar remote-repository
-instead of fetching new changes.
-This can be useful when a remote repository is being removed from
-.Xr got.conf 5 .
-.Pp
-With
-.Fl X ,
-the
-.Ar remote-repository
-argument is mandatory and no other options except
-.Fl r ,
-.Fl v ,
-and
-.Fl q
-are allowed.
-.Pp
-Only references are deleted.
-Any commit, tree, tag, and blob objects fetched from a remote repository
-will generally be stored in pack files and may be removed separately with
-.Xr git-repack 1
-and Git's garbage collector.
-.El
.Tg co
.It Xo
.Cm checkout
Show object IDs of files (blob objects) and directories (tree objects).
.It Fl R
Recurse into sub-directories in the repository.
-.It Fl r Ar repository-path
-Use the repository at the specified path.
-If not specified, assume the repository is located at or above the current
-working directory.
-If this directory is a
-.Nm
-work tree, use the repository path associated with this work tree.
-.El
-.It Xo
-.Cm ref
-.Op Fl dlt
-.Op Fl c Ar object
-.Op Fl r Ar repository-path
-.Op Fl s Ar reference
-.Op Ar name
-.Xc
-Manage references in a repository.
-.Pp
-References may be listed, created, deleted, and changed.
-When creating, deleting, or changing a reference the specified
-.Ar name
-must be an absolute reference name, i.e. it must begin with
-.Dq refs/ .
-.Pp
-The options for
-.Cm got ref
-are as follows:
-.Bl -tag -width Ds
-.It Fl c Ar object
-Create a reference or change an existing reference.
-The reference with the specified
-.Ar name
-will point at the specified
-.Ar object .
-The expected
-.Ar object
-argument is a ID SHA1 hash or an existing reference or tag name which will
-be resolved to the ID of a corresponding commit, tree, tag, or blob object.
-Cannot be used together with any other options except
-.Fl r .
-.It Fl d
-Delete the reference with the specified
-.Ar name
-from the repository.
-Any commit, tree, tag, and blob objects belonging to deleted references
-remain in the repository and may be removed separately with
-Git's garbage collector or
-.Cm gotadmin cleanup .
-Cannot be used together with any other options except
-.Fl r .
-.It Fl l
-List references in the repository.
-If no
-.Ar name
-is specified, list all existing references in the repository.
-If
-.Ar name
-is a reference namespace, list all references in this namespace.
-Otherwise, show only the reference with the given
-.Ar name .
-Cannot be used together with any other options except
-.Fl r
-and
-.Fl t .
.It Fl r Ar repository-path
Use the repository at the specified path.
If not specified, assume the repository is located at or above the current
If this directory is a
.Nm
work tree, use the repository path associated with this work tree.
-.It Fl s Ar reference
-Create a symbolic reference, or change an existing symbolic reference.
-The symbolic reference with the specified
-.Ar name
-will point at the specified
-.Ar reference
-which must already exist in the repository.
-Care should be taken not to create loops between references when
-this option is used.
-Cannot be used together with any other options except
-.Fl r .
-.It Fl t
-Sort listed references by modification time (most recently modified first)
-instead of sorting by lexicographical order.
-Use of this option requires the
-.Fl l
-option to be used as well.
.El
-.Tg br
-.It Xo
-.Cm branch
-.Op Fl lnt
-.Op Fl c Ar commit
-.Op Fl d Ar name
-.Op Fl r Ar repository-path
-.Op Ar name
-.Xc
-.Dl Pq alias: Cm br
-Create, list, or delete branches.
-.Pp
-Local branches are managed via references which live in the
-.Dq refs/heads/
-reference namespace.
-The
-.Cm got branch
-command creates references in this namespace only.
-.Pp
-When deleting branches, the specified
-.Ar name
-is searched in the
-.Dq refs/heads
-reference namespace first.
-If no corresponding branch is found, the
-.Dq refs/remotes
-namespace will be searched next.
-.Pp
-If invoked in a work tree without any arguments, print the name of the
-work tree's current branch.
-.Pp
-If a
-.Ar name
-argument is passed, attempt to create a branch reference with the given name.
-By default the new branch reference will point at the latest commit on the
-work tree's current branch if invoked in a work tree, and otherwise to a commit
-resolved via the repository's HEAD reference.
-.Pp
-If invoked in a work tree, once the branch was created successfully
-switch the work tree's head reference to the newly created branch and
-update files across the entire work tree, just like
-.Cm got update -b Ar name
-would do.
-Show the status of each affected file, using the following status codes:
-.Bl -column YXZ description
-.It U Ta file was updated and contained no local changes
-.It G Ta file was updated and local changes were merged cleanly
-.It C Ta file was updated and conflicts occurred during merge
-.It D Ta file was deleted
-.It A Ta new file was added
-.It \(a~ Ta versioned file is obstructed by a non-regular file
-.It ! Ta a missing versioned file was restored
-.El
-.Pp
-The options for
-.Cm got branch
-are as follows:
-.Bl -tag -width Ds
-.It Fl c Ar commit
-Make a newly created branch reference point at the specified
-.Ar commit .
-The expected
-.Ar commit
-argument is a commit ID SHA1 hash or an existing reference
-or tag name which will be resolved to a commit ID.
-.It Fl d Ar name
-Delete the branch with the specified
-.Ar name
-from the
-.Dq refs/heads
-or
-.Dq refs/remotes
-reference namespace.
-.Pp
-Only the branch reference is deleted.
-Any commit, tree, and blob objects belonging to the branch
-remain in the repository and may be removed separately with
-Git's garbage collector or
-.Cm gotadmin cleanup .
-.It Fl l
-List all existing branches in the repository, including copies of remote
-repositories' branches in the
-.Dq refs/remotes/
-reference namespace.
-.Pp
-If invoked in a work tree, the work tree's current branch is shown
-with one of the following annotations:
-.Bl -column YXZ description
-.It * Ta work tree's base commit matches the branch tip
-.It \(a~ Ta work tree's base commit is out-of-date
-.El
-.It Fl n
-Do not switch and update the work tree after creating a new branch.
-.It Fl r Ar repository-path
-Use the repository at the specified path.
-If not specified, assume the repository is located at or above the current
-working directory.
-If this directory is a
-.Nm
-work tree, use the repository path associated with this work tree.
-.It Fl t
-Sort listed branches by modification time (most recently modified first)
-instead of sorting by lexicographical order.
-Branches in the
-.Dq refs/heads/
-reference namespace are listed before branches in
-.Dq refs/remotes/
-regardless.
-Use of this option requires the
-.Fl l
-option to be used as well.
-.El
-.It Xo
-.Cm tag
-.Op Fl lVv
-.Op Fl c Ar commit
-.Op Fl m Ar message
-.Op Fl r Ar repository-path
-.Op Fl s Ar signer-id
-.Ar name
-.Xc
-Manage tags in a repository.
-.Pp
-Tags are managed via references which live in the
-.Dq refs/tags/
-reference namespace.
-The
-.Cm got tag
-command operates on references in this namespace only.
-References in this namespace point at tag objects which contain a pointer
-to another object, a tag message, as well as author and timestamp information.
-.Pp
-Attempt to create a tag with the given
-.Ar name ,
-and make this tag point at the given
-.Ar commit .
-If no commit is specified, default to the latest commit on the work tree's
-current branch if invoked in a work tree, and to a commit resolved via
-the repository's HEAD reference otherwise.
-.Pp
-The options for
-.Cm got tag
-are as follows:
-.Bl -tag -width Ds
-.It Fl c Ar commit
-Make the newly created tag reference point at the specified
-.Ar commit .
-The expected
-.Ar commit
-argument is a commit ID SHA1 hash or an existing reference or tag name which
-will be resolved to a commit ID.
-An abbreviated hash argument will be expanded to a full SHA1 hash
-automatically, provided the abbreviation is unique.
-.It Fl l
-List all existing tags in the repository instead of creating a new tag.
-If a
-.Ar name
-argument is passed, show only the tag with the given
-.Ar name .
-.It Fl m Ar message
-Use the specified tag message when creating the new tag.
-Without the
-.Fl m
-option,
-.Cm got tag
-opens a temporary file in an editor where a tag message can be written.
-.It Fl r Ar repository-path
-Use the repository at the specified path.
-If not specified, assume the repository is located at or above the current
-working directory.
-If this directory is a
-.Nm
-work tree, use the repository path associated with this work tree.
-.It Fl s Ar signer-id
-While creating a new tag, sign this tag with the identity given in
-.Ar signer-id .
-.Pp
-For SSH-based signatures,
-.Ar signer-id
-is the path to a file which may refer to either a private SSH key,
-or a public SSH key with the private half available via
-.Xr ssh-agent 1 .
-.Cm got tag
-will sign the tag object by invoking
-.Xr ssh-keygen 1
-with the
-.Fl Y Cm sign
-command, using the signature namespace
-.Dq git
-for compatibility with
-.Xr git 1 .
-.It Fl V
-Verify tag object signatures.
-If a
-.Ar name
-is specified, show and verify the tag object with the provided name.
-Otherwise, list all tag objects and verify signatures where present.
-.Pp
-.Cm got tag
-verifies SSH-based signatures by invoking
-.Xr ssh-keygen 1
-with the options
-.Fl Y Cm verify Fl f Ar allowed_signers .
-A path to the
-.Ar allowed_signers
-file must be set in
-.Xr got.conf 5 ,
-otherwise verification is impossible.
-.It Fl v
-Verbose mode.
-During SSH signature creation and verification this option will be passed to
-.Xr ssh-keygen 1 .
-Multiple -v options increase the verbosity.
-The maximum is 3.
-.El
-.Pp
-By design, the
-.Cm got tag
-command will not delete tags or change existing tags.
-If a tag must be deleted, the
-.Cm got ref
-command may be used to delete a tag's reference.
-This should only be done if the tag has not already been copied to
-another repository.
-.It Xo
-.Cm add
-.Op Fl IR
-.Ar path ...
-.Xc
-Schedule unversioned files in a work tree for addition to the
-repository in the next commit.
-By default, files which match a
-.Cm got status
-ignore pattern will not be added.
-.Pp
-If a
-.Ar path
-mentioned in the command line is not an unversioned file then
-.Cm got add
-may raise an error.
-To avoid unnecessary errors from paths picked up by file globbing patterns
-in the shell, paths in the argument list will be silently ignored if they
-are not reported by
-.Cm got status
-at all, or if they are reported with one of the following status codes
-and do not have changes staged via
-.Cm got stage :
-.Bl -column YXZ description
-.It M Ta modified file
-.It A Ta file scheduled for addition in next commit
-.It C Ta modified or added file which contains merge conflicts
-.It m Ta modified file modes (executable bit only)
-.El
-.Pp
-The options for
-.Cm got add
-are as follows:
-.Bl -tag -width Ds
-.It Fl I
-Add files even if they match a
-.Cm got status
-ignore pattern.
-.It Fl R
-Permit recursion into directories.
-If this option is not specified,
-.Cm got add
-will refuse to run if a specified
-.Ar path
-is a directory.
-.El
.Tg rm
.It Xo
.Cm remove
.Cm got update
must be used first in order to merge local changes with changes made
in the repository.
-.Tg se
-.It Xo
-.Cm send
-.Op Fl afqTv
-.Op Fl b Ar branch
-.Op Fl d Ar branch
-.Op Fl r Ar repository-path
-.Op Fl t Ar tag
-.Op Ar remote-repository
-.Xc
-.Dl Pq alias: Cm se
-Send new changes to a remote repository.
-If no
-.Ar remote-repository
-is specified,
-.Dq origin
-will be used.
-The remote repository's URL is obtained from the corresponding entry in
-.Xr got.conf 5
-or Git's
-.Pa config
-file of the local repository, as created by
-.Cm got clone .
-.Pp
-All objects corresponding to new changes will be written to a temporary
-pack file which is then uploaded to the server.
-Upon success, references in the
-.Dq refs/remotes/
-reference namespace of the local repository will be updated to point at
-the commits which have been sent.
-.Pp
-By default, changes will only be sent if they are based on up-to-date
-copies of relevant branches in the remote repository.
-If any changes to be sent are based on out-of-date copies or would
-otherwise break linear history of existing branches, new changes must
-be fetched from the server with
-.Cm got fetch
-and local branches must be rebased with
-.Cm got rebase
-before
-.Cm got send
-can succeed.
-The
-.Fl f
-option can be used to make exceptions to these requirements.
-.Pp
-The options for
-.Cm got send
-are as follows:
-.Bl -tag -width Ds
-.It Fl a
-Send all branches from the local repository's
-.Dq refs/heads/
-reference namespace.
-The
-.Fl a
-option is equivalent to listing all branches with multiple
-.Fl b
-options.
-Cannot be used together with the
-.Fl b
-option.
-.It Fl b Ar branch
-Send the specified
-.Ar branch
-from the local repository's
-.Dq refs/heads/
-reference namespace.
-This option may be specified multiple times to build a list of branches
-to send.
-If this option is not specified, default to the work tree's current branch
-if invoked in a work tree, or to the repository's HEAD reference.
-Cannot be used together with the
-.Fl a
-option.
-.It Fl d Ar branch
-Delete the specified
-.Ar branch
-from the remote repository's
-.Dq refs/heads/
-reference namespace.
-This option may be specified multiple times to build a list of branches
-to delete.
-.Pp
-Only references are deleted.
-Any commit, tree, tag, and blob objects belonging to deleted branches
-may become subject to deletion by Git's garbage collector running on
-the server.
-.Pp
-Requesting deletion of branches results in an error if the server
-does not support this feature or disallows the deletion of branches
-based on its configuration.
-.It Fl f
-Attempt to force the server to overwrite existing branches or tags
-in the remote repository, even when
-.Cm got fetch
-followed by
-.Cm got rebase
-or
-.Cm got merge
-would usually be required before changes can be sent.
-The server may reject forced requests regardless, depending on its
-configuration.
-.Pp
-Any commit, tree, tag, and blob objects belonging to overwritten branches
-or tags may become subject to deletion by Git's garbage collector running
-on the server.
-.Pp
-The
-.Dq refs/tags
-reference namespace is globally shared between all repositories.
-Use of the
-.Fl f
-option to overwrite tags is discouraged because it can lead to
-inconsistencies between the tags present in different repositories.
-In general, creating a new tag with a different name is recommended
-instead of overwriting an existing tag.
-.Pp
-Use of the
-.Fl f
-option is particularly discouraged if changes being sent are based
-on an out-of-date copy of a branch in the remote repository.
-Instead of using the
-.Fl f
-option, new changes should
-be fetched with
-.Cm got fetch
-and local branches should be rebased with
-.Cm got rebase
-or merged with
-.Cm got merge ,
-followed by another attempt to send the changes.
-.Pp
-The
-.Fl f
-option should only be needed in situations where the remote repository's
-copy of a branch or tag is known to be out-of-date and is considered
-disposable.
-The risks of creating inconsistencies between different repositories
-should also be taken into account.
-.It Fl q
-Suppress progress reporting output.
-The same option will be passed to
-.Xr ssh 1
-if applicable.
-.It Fl r Ar repository-path
-Use the repository at the specified path.
-If not specified, assume the repository is located at or above the current
-working directory.
-If this directory is a
-.Nm
-work tree, use the repository path associated with this work tree.
-.It Fl T
-Attempt to send all tags from the local repository's
-.Dq refs/tags/
-reference namespace.
-The
-.Fl T
-option is equivalent to listing all tags with multiple
-.Fl t
-options.
-Cannot be used together with the
-.Fl t
-option.
-.It Fl t Ar tag
-Send the specified
-.Ar tag
-from the local repository's
-.Dq refs/tags/
-reference namespace, in addition to any branches that are being sent.
-The
-.Fl t
-option may be specified multiple times to build a list of tags to send.
-No tags will be sent if the
-.Fl t
-option is not used.
-.Pp
-Raise an error if the specified
-.Ar tag
-already exists in the remote repository, unless the
-.Fl f
-option is used to overwrite the server's copy of the tag.
-In general, creating a new tag with a different name is recommended
-instead of overwriting an existing tag.
-.Pp
-Cannot be used together with the
-.Fl T
-option.
-.It Fl v
-Verbose mode.
-Causes
-.Cm got send
-to print debugging messages to standard error output.
-The same option will be passed to
-.Xr ssh 1
-if applicable.
-Multiple -v options increase the verbosity.
-The maximum is 3.
-.El
.Tg cy
.It Xo
.Cm cherrypick
.Fl l .
.El
.Pp
-.Tg rb
.It Xo
-.Cm rebase
-.Op Fl aCclX
-.Op Ar branch
-.Xc
-.Dl Pq alias: Cm rb
-Rebase commits on the specified
-.Ar branch
-onto the tip of the current branch of the work tree.
-The
-.Ar branch
-must share common ancestry with the work tree's current branch.
-Rebasing begins with the first descendant commit of the youngest
-common ancestor commit shared by the specified
-.Ar branch
-and the work tree's current branch, and stops once the tip commit
-of the specified
-.Ar branch
-has been rebased.
-.Pp
-When
-.Cm got rebase
-is used as intended, the specified
-.Ar branch
-represents a local commit history and may already contain changes
-that are not yet visible in any other repositories.
-The work tree's current branch, which must be set with
-.Cm got update -b
-before starting the
-.Cm rebase
-operation, represents a branch from a remote repository which shares
-a common history with the specified
-.Ar branch
-but has progressed, and perhaps diverged, due to commits added to the
-remote repository.
-.Pp
-Rebased commits are accumulated on a temporary branch which the work tree
-will remain switched to throughout the entire rebase operation.
-Commits on this branch represent the same changes with the same log
-messages as their counterparts on the original
-.Ar branch ,
-but with different commit IDs.
-Once rebasing has completed successfully, the temporary branch becomes
-the new version of the specified
-.Ar branch
-and the work tree is automatically switched to it.
-If author information is available via the
-.Ev GOT_AUTHOR
-environment variable,
-.Xr got.conf 5
-or Git's
-.Dv user.name
-and
-.Dv user.email
-configuration settings, this author information will be used to identify
-the
-.Dq committer
-of rebased commits.
-.Pp
-Old commits in their pre-rebase state are automatically backed up in the
-.Dq refs/got/backup/rebase
-reference namespace.
-As long as these references are not removed older versions of rebased
-commits will remain in the repository and can be viewed with the
-.Cm got rebase -l
-command.
-Removal of these references makes objects which become unreachable via
-any reference subject to removal by Git's garbage collector or
-.Cm gotadmin cleanup .
-.Pp
-While rebasing commits, show the status of each affected file,
-using the following status codes:
-.Bl -column YXZ description
-.It G Ta file was merged
-.It C Ta file was merged and conflicts occurred during merge
-.It ! Ta changes destined for a missing file were not merged
-.It D Ta file was deleted
-.It d Ta file's deletion was prevented by local modifications
-.It A Ta new file was added
-.It \(a~ Ta changes destined for a non-regular file were not merged
-.It ? Ta changes destined for an unversioned file were not merged
-.El
-.Pp
-If merge conflicts occur, the rebase operation is interrupted and may
-be continued once conflicts have been resolved.
-If any files with destined changes are found to be missing or unversioned,
-or if files could not be deleted due to differences in deleted content,
-the rebase operation will be interrupted to prevent potentially incomplete
-changes from being committed to the repository without user intervention.
-The work tree may be modified as desired and the rebase operation can be
-continued once the changes present in the work tree are considered complete.
-Alternatively, the rebase operation may be aborted which will leave
-.Ar branch
-unmodified and the work tree switched back to its original branch.
-.Pp
-If a merge conflict is resolved in a way which renders the merged
-change into a no-op change, the corresponding commit will be elided
-when the rebase operation continues.
-.Pp
-.Cm got rebase
-will refuse to run if certain preconditions are not met.
-If the
-.Ar branch
-is not in the
-.Dq refs/heads/
-reference namespace, the branch may not be rebased.
-If the work tree is not yet fully updated to the tip commit of its
-branch, then the work tree must first be updated with
-.Cm got update .
-If changes have been staged with
-.Cm got stage ,
-these changes must first be committed with
-.Cm got commit
-or unstaged with
-.Cm got unstage .
-If the work tree contains local changes, these changes must first be
-committed with
-.Cm got commit
-or reverted with
-.Cm got revert .
-If the
-.Ar branch
-contains changes to files outside of the work tree's path prefix,
-the work tree cannot be used to rebase this branch.
-.Pp
-The
-.Cm got update ,
-.Cm got integrate ,
-.Cm got merge ,
-.Cm got commit ,
-and
-.Cm got histedit
-commands will refuse to run while a rebase operation is in progress.
-Other commands which manipulate the work tree may be used for
-conflict resolution purposes.
-.Pp
-If the specified
-.Ar branch
-is already based on the work tree's current branch, then no commits
-need to be rebased and
-.Cm got rebase
-will simply switch the work tree to the specified
-.Ar branch
-and update files in the work tree accordingly.
-.Pp
-The options for
-.Cm got rebase
-are as follows:
-.Bl -tag -width Ds
-.It Fl a
-Abort an interrupted rebase operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl C
-Allow a rebase operation to continue with files in conflicted status.
-This option should generally be avoided, and can only be used with the
-.Fl c
-option.
-.It Fl c
-Continue an interrupted rebase operation.
-If this option is used, no other command-line arguments are allowed except
-.Fl C .
-.It Fl l
-Show a list of past rebase operations, represented by references in the
-.Dq refs/got/backup/rebase
-reference namespace.
-.Pp
-Display the author, date, and log message of each backed up commit,
-the object ID of the corresponding post-rebase commit, and
-the object ID of their common ancestor commit.
-Given these object IDs,
-the
-.Cm got log
-command with the
-.Fl c
-and
-.Fl x
-options can be used to examine the history of either version of the branch,
-and the
-.Cm got branch
-command with the
-.Fl c
-option can be used to create a new branch from a pre-rebase state if desired.
-.Pp
-If a
-.Ar branch
-is specified, only show commits which at some point in time represented this
-branch.
-Otherwise, list all backed up commits for any branches.
-.Pp
-If this option is used,
-.Cm got rebase
-does not require a work tree.
-None of the other options can be used together with
-.Fl l .
-.It Fl X
-Delete backups created by past rebase operations, represented by references
-in the
-.Dq refs/got/backup/rebase
-reference namespace.
-.Pp
-If a
-.Ar branch
-is specified, only delete backups which at some point in time represented
-this branch.
-Otherwise, delete all references found within
-.Dq refs/got/backup/rebase .
-.Pp
-Any commit, tree, tag, and blob objects belonging to deleted backups
-remain in the repository and may be removed separately with
-Git's garbage collector or
-.Cm gotadmin cleanup .
-.Pp
-If this option is used,
-.Cm got rebase
-does not require a work tree.
-None of the other options can be used together with
-.Fl X .
-.El
-.Tg he
-.It Xo
-.Cm histedit
-.Op Fl aCcdeflmX
-.Op Fl F Ar histedit-script
-.Op Ar branch
-.Xc
-.Dl Pq alias: Cm he
-Edit commit history between the work tree's current base commit and
-the tip commit of the work tree's current branch.
-.Pp
-The
-.Cm got histedit
-command requires the
-.Ev GOT_AUTHOR
-environment variable to be set,
-unless an author has been configured in
-.Xr got.conf 5
-or Git's
-.Dv user.name
-and
-.Dv user.email
-configuration settings can be obtained from the repository's
-.Pa .git/config
-file or from Git's global
-.Pa ~/.gitconfig
-configuration file.
-.Pp
-Before starting a
-.Cm histedit
-operation, the work tree's current branch must be set with
-.Cm got update -b
-to the branch which should be edited, unless this branch is already the
-current branch of the work tree.
-The tip of this branch represents the upper bound (inclusive) of commits
-touched by the
-.Cm histedit
-operation.
-.Pp
-Furthermore, the work tree's base commit
-must be set with
-.Cm got update -c
-to a point in this branch's commit history where editing should begin.
-This commit represents the lower bound (non-inclusive) of commits touched
-by the
-.Cm histedit
-operation.
-.Pp
-Editing of commit history is controlled via a
-.Ar histedit script
-which can be written in an editor based on a template, passed on the
-command line, or generated with the
-.Fl d ,
-.Fl e ,
-.Fl f ,
-or
-.Fl m
-options.
-.Pp
-The format of the histedit script is line-based.
-Each line in the script begins with a command name, followed by
-whitespace and an argument.
-For most commands, the expected argument is a commit ID SHA1 hash.
-Any remaining text on the line is ignored.
-Lines which begin with the
-.Sq #
-character are ignored entirely.
-.Pp
-The available histedit script commands are as follows:
-.Bl -column YXZ pick-commit
-.It Cm pick Ar commit Ta Use the specified commit as it is.
-.It Cm edit Ar commit Ta Apply the changes from the specified commit, but
-then interrupt the histedit operation for amending, without creating a commit.
-While the histedit operation is interrupted arbitrary files may be edited,
-and commands which manipulate the work tree can be used freely.
-The
-.Cm got add
-and
-.Cm got remove
-commands can be used to add new files or remove existing ones.
-The
-.Cm got revert -p
-command can be used to eliminate arbitrary changes from files in the work tree.
-The
-.Cm got stage -p
-command may be used to prepare a subset of changes for inclusion in the
-next commit.
-Finally, the
-.Cm got commit
-command can be used to insert arbitrary commits into the edited history.
-Regular editing of history must eventually be resumed by running
-.Cm got histedit -c .
-.It Cm fold Ar commit Ta Combine the specified commit with the next commit
-listed further below that will be used.
-.It Cm drop Ar commit Ta Remove this commit from the edited history.
-.It Cm mesg Oo Ar log-message Oc Ta Create a new log message for the commit of
-a preceding
-.Cm pick
-or
-.Cm edit
-command on the previous line of the histedit script.
-The optional
-.Ar log-message
-argument provides a new single-line log message to use.
-If the
-.Ar log-message
-argument is omitted, open an editor where a new log message can be written.
-.El
-.Pp
-Every commit in the history being edited must be mentioned in the script.
-Lines may be re-ordered to change the order of commits in the edited history.
-No commit may be listed more than once.
-.Pp
-Edited commits are accumulated on a temporary branch which the work tree
-will remain switched to throughout the entire histedit operation.
-Once history editing has completed successfully, the temporary branch becomes
-the new version of the work tree's branch and the work tree is automatically
-switched to it.
-.Pp
-Old commits in their pre-histedit state are automatically backed up in the
-.Dq refs/got/backup/histedit
-reference namespace.
-As long as these references are not removed older versions of edited
-commits will remain in the repository and can be viewed with the
-.Cm got histedit -l
-command.
-Removal of these references makes objects which become unreachable via
-any reference subject to removal by Git's garbage collector or
-.Cm gotadmin cleanup .
-.Pp
-While merging commits, show the status of each affected file,
-using the following status codes:
-.Bl -column YXZ description
-.It G Ta file was merged
-.It C Ta file was merged and conflicts occurred during merge
-.It ! Ta changes destined for a missing file were not merged
-.It D Ta file was deleted
-.It d Ta file's deletion was prevented by local modifications
-.It A Ta new file was added
-.It \(a~ Ta changes destined for a non-regular file were not merged
-.It ? Ta changes destined for an unversioned file were not merged
-.El
-.Pp
-If merge conflicts occur, the histedit operation is interrupted and may
-be continued once conflicts have been resolved.
-If any files with destined changes are found to be missing or unversioned,
-or if files could not be deleted due to differences in deleted content,
-the histedit operation will be interrupted to prevent potentially incomplete
-changes from being committed to the repository without user intervention.
-The work tree may be modified as desired and the histedit operation can be
-continued once the changes present in the work tree are considered complete.
-Alternatively, the histedit operation may be aborted which will leave
-the work tree switched back to its original branch.
-.Pp
-If a merge conflict is resolved in a way which renders the merged
-change into a no-op change, the corresponding commit will be elided
-when the histedit operation continues.
-.Pp
-.Cm got histedit
-will refuse to run if certain preconditions are not met.
-If the work tree's current branch is not in the
-.Dq refs/heads/
-reference namespace, the history of the branch may not be edited.
-If the work tree contains multiple base commits, it must first be updated
-to a single base commit with
-.Cm got update .
-If changes have been staged with
-.Cm got stage ,
-these changes must first be committed with
-.Cm got commit
-or unstaged with
-.Cm got unstage .
-If the work tree contains local changes, these changes must first be
-committed with
-.Cm got commit
-or reverted with
-.Cm got revert .
-If the edited history contains changes to files outside of the work tree's
-path prefix, the work tree cannot be used to edit the history of this branch.
-.Pp
-The
-.Cm got update ,
-.Cm got rebase ,
-.Cm got merge ,
-and
-.Cm got integrate
-commands will refuse to run while a histedit operation is in progress.
-Other commands which manipulate the work tree may be used, and the
-.Cm got commit
-command may be used to commit arbitrary changes to the temporary branch
-while the histedit operation is interrupted.
-.Pp
-The options for
-.Cm got histedit
-are as follows:
-.Bl -tag -width Ds
-.It Fl a
-Abort an interrupted histedit operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl C
-Allow a histedit operation to continue with files in conflicted status.
-This option should generally be avoided, and can only be used with the
-.Fl c
-option.
-.It Fl c
-Continue an interrupted histedit operation.
-If this option is used, no other command-line arguments are allowed except
-.Fl C .
-.It Fl d
-Drop all commits.
-This option is a quick equivalent to a histedit script which drops all
-commits.
-The
-.Fl d
-option can only be used when starting a new histedit operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl e
-Interrupt the histedit operation for editing after merging each commit.
-This option is a quick equivalent to a histedit script which uses the
-.Cm edit
-command for all commits.
-The
-.Fl e
-option can only be used when starting a new histedit operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl F Ar histedit-script
-Use the specified
-.Ar histedit-script
-instead of opening a temporary file in an editor where a histedit script
-can be written.
-.It Fl f
-Fold all commits into a single commit.
-This option is a quick equivalent to a histedit script which folds all
-commits, combining them all into one commit.
-The
-.Fl f
-option can only be used when starting a new histedit operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl l
-Show a list of past histedit operations, represented by references in the
-.Dq refs/got/backup/histedit
-reference namespace.
-.Pp
-Display the author, date, and log message of each backed up commit,
-the object ID of the corresponding post-histedit commit, and
-the object ID of their common ancestor commit.
-Given these object IDs,
-the
-.Cm got log
-command with the
-.Fl c
-and
-.Fl x
-options can be used to examine the history of either version of the branch,
-and the
-.Cm got branch
-command with the
-.Fl c
-option can be used to create a new branch from a pre-histedit state if desired.
-.Pp
-If a
-.Ar branch
-is specified, only show commits which at some point in time represented this
-branch.
-Otherwise, list all backed up commits for any branches.
-.Pp
-If this option is used,
-.Cm got histedit
-does not require a work tree.
-None of the other options can be used together with
-.Fl l .
-.It Fl m
-Edit log messages only.
-This option is a quick equivalent to a histedit script which edits
-only log messages but otherwise leaves every picked commit as-is.
-The
-.Fl m
-option can only be used when starting a new histedit operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl X
-Delete backups created by past histedit operations, represented by references
-in the
-.Dq refs/got/backup/histedit
-reference namespace.
-.Pp
-If a
-.Ar branch
-is specified, only delete backups which at some point in time represented
-this branch.
-Otherwise, delete all references found within
-.Dq refs/got/backup/histedit .
-.Pp
-Any commit, tree, tag, and blob objects belonging to deleted backups
-remain in the repository and may be removed separately with
-Git's garbage collector or
-.Cm gotadmin cleanup .
-.Pp
-If this option is used,
-.Cm got histedit
-does not require a work tree.
-None of the other options can be used together with
-.Fl X .
-.El
-.Tg ig
-.It Cm integrate Ar branch
-.Dl Pq alias: Cm ig
-Integrate the specified
-.Ar branch
-into the work tree's current branch.
-Files in the work tree are updated to match the contents on the integrated
-.Ar branch ,
-and the reference of the work tree's branch is changed to point at the
-head commit of the integrated
-.Ar branch .
-.Pp
-Both branches can be considered equivalent after integration since they
-will be pointing at the same commit.
-Both branches remain available for future work, if desired.
-In case the integrated
-.Ar branch
-is no longer needed it may be deleted with
-.Cm got branch -d .
-.Pp
-Show the status of each affected file, using the following status codes:
-.Bl -column YXZ description
-.It U Ta file was updated
-.It D Ta file was deleted
-.It A Ta new file was added
-.It \(a~ Ta versioned file is obstructed by a non-regular file
-.It ! Ta a missing versioned file was restored
-.El
-.Pp
-.Cm got integrate
-will refuse to run if certain preconditions are not met.
-Most importantly, the
-.Ar branch
-must have been rebased onto the work tree's current branch with
-.Cm got rebase
-before it can be integrated, in order to linearize commit history and
-resolve merge conflicts.
-If the work tree contains multiple base commits, it must first be updated
-to a single base commit with
-.Cm got update .
-If changes have been staged with
-.Cm got stage ,
-these changes must first be committed with
-.Cm got commit
-or unstaged with
-.Cm got unstage .
-If the work tree contains local changes, these changes must first be
-committed with
-.Cm got commit
-or reverted with
-.Cm got revert .
-.Tg mg
-.It Xo
-.Cm merge
-.Op Fl aCcMn
-.Op Ar branch
-.Xc
-.Dl Pq alias: Cm mg
-Merge the specified
-.Ar branch
-into the current branch of the work tree.
-If the branches have diverged, creates a merge commit.
-Otherwise, if
-.Ar branch
-already includes all commits from the work tree's branch, updates the work
-tree's branch to be the same as
-.Ar branch
-without creating a commit, and updates the work tree to the most recent commit
-on the branch.
-.Pp
-If a linear project history is desired, then use of
-.Cm got rebase
-should be preferred over
-.Cm got merge .
-However, even strictly linear projects may require merge commits in order
-to merge in new versions of third-party code stored on vendor branches
-created with
-.Cm got import .
-.Pp
-Merge commits are commits based on multiple parent commits.
-The tip commit of the work tree's current branch, which must be in the
-.Dq refs/heads/
-reference namespace and must be set with
-.Cm got update -b
-before starting the
-.Cm merge
-operation, will be used as the first parent.
-The tip commit of the specified
-.Ar branch
-will be used as the second parent.
-.Pp
-No ancestral relationship between the two branches is required.
-If the two branches have already been merged previously, only new changes
-will be merged.
-.Pp
-It is not possible to create merge commits with more than two parents.
-If more than one branch needs to be merged, then multiple merge commits
-with two parents each can be created in sequence.
-.Pp
-While merging changes found on the
-.Ar branch
-into the work tree, show the status of each affected file,
-using the following status codes:
-.Bl -column YXZ description
-.It G Ta file was merged
-.It C Ta file was merged and conflicts occurred during merge
-.It ! Ta changes destined for a missing file were not merged
-.It D Ta file was deleted
-.It d Ta file's deletion was prevented by local modifications
-.It A Ta new file was added
-.It \(a~ Ta changes destined for a non-regular file were not merged
-.It ? Ta changes destined for an unversioned file were not merged
-.El
-.Pp
-If merge conflicts occur, the merge operation is interrupted and conflicts
-must be resolved before the merge operation can continue.
-If any files with destined changes are found to be missing or unversioned,
-or if files could not be deleted due to differences in deleted content,
-the merge operation will be interrupted to prevent potentially incomplete
-changes from being committed to the repository without user intervention.
-The work tree may be modified as desired and the merge can be continued
-once the changes present in the work tree are considered complete.
-Alternatively, the merge operation may be aborted which will leave
-the work tree's current branch unmodified.
-.Pp
-.Cm got merge
-will refuse to run if certain preconditions are not met.
-If the work tree's current branch is not in the
-.Dq refs/heads/
-reference namespace then the work tree must first be switched to a
-branch in the
-.Dq refs/heads/
-namespace with
-.Cm got update -b .
-If the work tree is not yet fully updated to the tip commit of its
-branch, then the work tree must first be updated with
-.Cm got update .
-If the work tree contains multiple base commits, it must first be updated
-to a single base commit with
-.Cm got update .
-If changes have been staged with
-.Cm got stage ,
-these changes must first be committed with
-.Cm got commit
-or unstaged with
-.Cm got unstage .
-If the work tree contains local changes, these changes must first be
-committed with
-.Cm got commit
-or reverted with
-.Cm got revert .
-If the
-.Ar branch
-contains changes to files outside of the work tree's path prefix,
-the work tree cannot be used to merge this branch.
-.Pp
-The
-.Cm got update ,
-.Cm got commit ,
-.Cm got rebase ,
-.Cm got histedit ,
-.Cm got integrate ,
-and
-.Cm got stage
-commands will refuse to run while a merge operation is in progress.
-Other commands which manipulate the work tree may be used for
-conflict resolution purposes.
-.Pp
-The options for
-.Cm got merge
-are as follows:
-.Bl -tag -width Ds
-.It Fl a
-Abort an interrupted merge operation.
-If this option is used, no other command-line arguments are allowed.
-.It Fl C
-Allow a merge operation to continue with files in conflicted status.
-This option should generally be avoided, and can only be used with the
-.Fl c
-option.
-.It Fl c
-Continue an interrupted merge operation.
-If this option is used, no other command-line arguments are allowed except
-.Fl C .
-.It Fl M
-Create a merge commit even if the branches have not diverged.
-.It Fl n
-Merge changes into the work tree as usual but do not create a merge
-commit immediately.
-The merge result can be adjusted as desired before a merge commit is
-created with
-.Cm got merge -c .
-Alternatively, the merge may be aborted with
-.Cm got merge -a .
-.El
-.Tg sg
-.It Xo
-.Cm stage
-.Op Fl lpS
-.Op Fl F Ar response-script
-.Op Ar path ...
-.Xc
-.Dl Pq alias: Cm sg
-Stage local changes for inclusion in the next commit.
-If no
-.Ar path
-is specified, stage all changes in the work tree.
-Otherwise, stage changes at or within the specified paths.
-Paths may be staged if they are added, modified, or deleted according to
-.Cm got status .
-.Pp
-Show the status of each affected file, using the following status codes:
-.Bl -column YXZ description
-.It A Ta file addition has been staged
-.It M Ta file modification has been staged
-.It D Ta file deletion has been staged
-.El
-.Pp
-Staged file contents are saved in newly created blob objects in the repository.
-These blobs will be referred to by tree objects once staged changes have been
-committed.
-.Pp
-Staged changes affect the behaviour of
-.Cm got commit ,
-.Cm got status ,
-and
-.Cm got diff .
-While paths with staged changes exist, the
-.Cm got commit
-command will refuse to commit any paths which do not have staged changes.
-Local changes created on top of staged changes can only be committed if
-the path is staged again, or if the staged changes are committed first.
-The
-.Cm got status
-command will show both local changes and staged changes.
-The
-.Cm got diff
-command is able to display local changes relative to staged changes,
-and to display staged changes relative to the repository.
-The
-.Cm got revert
-command cannot revert staged changes but may be used to revert
-local changes created on top of staged changes.
-.Pp
-The options for
-.Cm got stage
-are as follows:
-.Bl -tag -width Ds
-.It Fl F Ar response-script
-With the
-.Fl p
-option, read
-.Dq y ,
-.Dq n ,
-and
-.Dq q
-responses line-by-line from the specified
-.Ar response-script
-file instead of prompting interactively.
-.It Fl l
-Instead of staging new changes, list paths which are already staged,
-along with the IDs of staged blob objects and stage status codes.
-If paths were provided on the command line, show the staged paths
-among the specified paths.
-Otherwise, show all staged paths.
-.It Fl p
-Instead of staging the entire content of a changed file, interactively
-select or reject changes for staging based on
-.Dq y
-(stage change),
-.Dq n
-(reject change), and
-.Dq q
-(quit staging this file) responses.
-If a file is in modified status, individual patches derived from the
-modified file content can be staged.
-Files in added or deleted status may only be staged or rejected in
-their entirety.
-.It Fl S
-Allow staging of symbolic links which point outside of the path space
-that is under version control.
-By default,
-.Cm got stage
-will reject such symbolic links due to safety concerns.
-As a precaution,
-.Nm
-may decide to represent such a symbolic link as a regular file which contains
-the link's target path, rather than creating an actual symbolic link which
-points outside of the work tree.
-Use of this option is discouraged because external mechanisms such as
-.Dq make obj
-are better suited for managing symbolic links to paths not under
-version control.
-.El
-.Pp
-.Cm got stage
-will refuse to run if certain preconditions are not met.
-If a file contains merge conflicts, these conflicts must be resolved first.
-If a file is found to be out of date relative to the head commit on the
-work tree's current branch, the file must be updated with
-.Cm got update
-before it can be staged (however, this does not prevent the file from
-becoming out-of-date at some point after having been staged).
-.Pp
-The
-.Cm got update ,
-.Cm got rebase ,
-.Cm got merge ,
-and
-.Cm got histedit
-commands will refuse to run while staged changes exist.
-If staged changes cannot be committed because a staged path
-is out of date, the path must be unstaged with
-.Cm got unstage
-before it can be updated with
-.Cm got update ,
-and may then be staged again if necessary.
-.Tg ug
-.It Xo
-.Cm unstage
-.Op Fl p
-.Op Fl F Ar response-script
-.Op Ar path ...
-.Xc
-.Dl Pq alias: Cm ug
-Merge staged changes back into the work tree and put affected paths
-back into non-staged status.
-If no
-.Ar path
-is specified, unstage all staged changes across the entire work tree.
-Otherwise, unstage changes at or within the specified paths.
-.Pp
-Show the status of each affected file, using the following status codes:
-.Bl -column YXZ description
-.It G Ta file was unstaged
-.It C Ta file was unstaged and conflicts occurred during merge
-.It ! Ta changes destined for a missing file were not merged
-.It D Ta file was staged as deleted and still is deleted
-.It d Ta file's deletion was prevented by local modifications
-.It \(a~ Ta changes destined for a non-regular file were not merged
-.El
-.Pp
-The options for
-.Cm got unstage
-are as follows:
-.Bl -tag -width Ds
-.It Fl F Ar response-script
-With the
-.Fl p
-option, read
-.Dq y ,
-.Dq n ,
-and
-.Dq q
-responses line-by-line from the specified
-.Ar response-script
-file instead of prompting interactively.
-.It Fl p
-Instead of unstaging the entire content of a changed file, interactively
-select or reject changes for unstaging based on
-.Dq y
-(unstage change),
-.Dq n
-(keep change staged), and
-.Dq q
-(quit unstaging this file) responses.
-If a file is staged in modified status, individual patches derived from the
-staged file content can be unstaged.
-Files staged in added or deleted status may only be unstaged in their entirety.
-.El
-.It Xo
.Cm cat
.Op Fl P
.Op Fl c Ar commit
