commit 4ed9f6144de87b2c060570a77f86e076b927934e from: Stefan Sperling date: Sun Aug 04 00:36:34 2019 UTC document staging commit - 9bc94a15e33f1e4458cc06bce6696a0f6048639f commit + 4ed9f6144de87b2c060570a77f86e076b927934e blob - ee870b09516306986d2a13d443fcf472fc660796 blob + 1ff79c320b05ec288c7e1d7305735e86a9682cc6 --- got/got.1 +++ got/got.1 @@ -195,6 +195,15 @@ is incompatible with the .Fl b option. .Pp +.Cm got update +cannot update paths with staged changes. +If changes have been staged with +.Cm got stage , +these changes must first be comitted with +.Cm got commit +or unstaged with +.Cm got unstage . +.Pp The options for .Cm got update are as follows: @@ -235,6 +244,23 @@ If no .Ar path is specified, show modifications in the entire work tree. Otherwise, show modifications at or within the specified paths. +.Pp +If changes have been staged with +.Cm got stage , +staged changes are shown in the second output column, using the following +status codes: +.Bl -column YXZ description +.It M Ta file modification is staged +.It A Ta file addition is staged +.It D Ta file deletion is staged +.El +.Pp +If a path has staged changes, modification status of local changes shown +in the first output column is relative to the staged changes: +.Bl -column YXZ description +.It MM Ta modified file was modified again after being staged +.It MA Ta added file was modified after being staged +.El .It Cm st Short alias for .Cm status . @@ -278,7 +304,7 @@ If this directory is a .Nm work tree, use the repository path associated with this work tree. .El -.It Cm diff [ Fl C Ar number ] [ Fl r Ar repository-path ] [ Ar object1 Ar object2 | Ar path ] +.It Cm diff [ Fl C Ar number ] [ Fl r Ar repository-path ] [ Fl s ] [ Ar object1 Ar object2 | Ar path ] When invoked within a work tree with less than two arguments, display uncommitted changes in the work tree. If a @@ -305,6 +331,13 @@ working directory. If this directory is a .Nm work tree, use the repository path associated with this work tree. +.It Fl s +Show changes staged with +.Cm got stage +instead of showing local changes. +This option is only valid when +.Cm got diff +is invoked in a work tree. .El .It Cm blame [ Fl c Ar commit ] [ Fl r Ar repository-path ] Ar path Display line-by-line history of a file at the specified path. @@ -479,13 +512,18 @@ it will be restored. Short alias for .Cm revert . .It Cm commit [ Fl m Ar message ] [ path ... ] -Create a new commit in the repository from local changes in a work tree +Create a new commit in the repository from changes in a work tree and use this commit as the new base commit for the work tree. If no .Ar path -is specified, commit all local changes in the work tree. -Otherwise, commit local changes at or within the specified paths. +is specified, commit all changes in the work tree. +Otherwise, commit changes at or within the specified paths. .Pp +If changes have been explicitly staged for commit with +.Cm got stage, +only commit staged changes and reject any specified paths which +have not been staged. +.Pp Show the status of each affected file, using the following status codes: .Bl -column YXZ description .It M Ta modified file @@ -533,6 +571,11 @@ 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. +If changes have been staged with +.Cm got stage , +the +.Cm got commit +command will refuse to commit any paths which do not have staged changes. .It Cm ci Short alias for .Cm commit . @@ -675,6 +718,12 @@ will refuse to run if certain preconditions are not me 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 comitted 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 @@ -775,6 +824,12 @@ reference namespace, the history of the branch may not 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 comitted 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 @@ -805,7 +860,92 @@ If this option is used, no further command-line argume .It Cm he Short alias for .Cm histedit . +.It Cm stage [ Fl l ] Ar file-path ... +Stage local changes at the specified paths for inclusion in the next commit. +Paths may be staged if they are added, modified, or deleted according to +.Cm got status . +.Pp +Staged changes affect the behaviour of the +.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 +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 relative to staged changes. +.Pp +The options for +.Cm got stage +are as follows: +.Bl -tag -width Ds +.It Fl l +Instead of staging new changes, list paths which are already staged, +along with the IDs of corresponding blob objects. +Indicate staged status using the following status codes: +.Bl -column YXZ description +.It A Ta file addition is staged +.It M Ta file modification is staged +.It D Ta file deletion is staged .El +.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 , +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. +.It Cm sg +Short alias for +.Cm stage . +.It Cm unstage [ Ar path ... ] +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. +.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 obstructed by local modifications +.It ~ Ta changes destined for a non-regular file were not merged +.El +.It Cm ug +Short alias for +.Cm unstage . +.El .Sh ENVIRONMENT .Bl -tag -width GOT_AUTHOR .It Ev GOT_AUTHOR