commit 21002b1b278e14573f85a3ec87c2aa5b8da47f49 from: Stefan Sperling date: Sat Jul 08 14:24:02 2023 UTC remove documentation of Got commands which cvg will not implement commit - 705cce7454a397f5c9eaa7a44ef383e0659d1242 commit + 21002b1b278e14573f85a3ec87c2aa5b8da47f49 blob - 119d3bd5d96ed7dd1e9875f0a41f1662f5fffd38 blob + 4c1cec0823d60146457085b972328049ac986934 --- cvg/cvg.1 +++ cvg/cvg.1 @@ -321,207 +321,6 @@ if applicable. 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 @@ -1089,70 +888,6 @@ automatically, provided the abbreviation is unique. 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 @@ -1160,294 +895,7 @@ working directory. 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 @@ -1827,205 +1275,6 @@ If a path is found to be out of date, .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 @@ -2242,899 +1491,7 @@ This option cannot be used with .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