diff --git a/src/cmd/diff.rs b/src/cmd/diff.rs index b9fc05f6..b277a8e0 100644 --- a/src/cmd/diff.rs +++ b/src/cmd/diff.rs @@ -24,12 +24,14 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Show a diff") + .about("Show diff between revisions, a patch, or the working tree") .long_about( - "Show the diff (default) or diffstat between the current working copy \ - or a tree-ish object and another tree-ish object (defaulting to HEAD). \ - File names can also be given to restrict the diff output. The \ - tree-ish object has the format accepted by the 'stg id' command.", + "Show diff between revisions, a patch, or the working tree.\n\ + \n\ + Display the diff (default) or diffstat comparing the current working \ + directory or a tree-ish object against another tree-ish object (defaulting \ + to HEAD). File paths can be specified to limit the diff output to the \ + specified files. Tree-ish objects use the format accepted by 'stg id'.", ) .arg( Arg::new("pathspecs") diff --git a/src/cmd/float.rs b/src/cmd/float.rs index b6fa1e4b..51618409 100644 --- a/src/cmd/float.rs +++ b/src/cmd/float.rs @@ -28,15 +28,15 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Push patches to the top, even if applied") + .about("Reorder patches by moving them to the top of the stack") .long_about( - "Push patches to the top, even if applied.\n\ + "Reorder patches by moving them to the top of the stack.\n\ \n\ - Float one or more patches to be the topmost applied patches. The patches \ - to be floated may currently be either applied or unapplied. The necessary \ - pop and push operations will be performed to float the named patches. \ - Patches not specified will remain applied or unapplied as they were prior \ - to the float operation.", + Move one or more patches to become the topmost applied patches. The patches \ + may currently be either applied or unapplied. The necessary pop and push \ + operations will be performed to reorder the named patches. Patches not \ + specified will remain applied or unapplied as they were prior to the \ + operation.", ) .override_usage(super::make_usage( "stg float", diff --git a/src/cmd/fold.rs b/src/cmd/fold.rs index 25bcbc2b..9e72839e 100644 --- a/src/cmd/fold.rs +++ b/src/cmd/fold.rs @@ -25,10 +25,12 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Fold diff file into the current patch") + .about("Integrate a GNU diff file into the current patch") .long_about( - "Fold diff file into the current patch. The given GNU diff file (or \ - standard input) is applied onto the current patch.\n\ + "Integrate a GNU diff file into the current patch.\n\ + \n\ + Apply changes from a GNU diff file (or standard input) to the current patch, \ + updating the patch to include those changes.\n\ \n\ With the '--threeway' option, the diff is applied onto the bottom of the \ current patch and a three-way merge is performed with the current top. \ diff --git a/src/cmd/id.rs b/src/cmd/id.rs index eb443d46..57d64da2 100644 --- a/src/cmd/id.rs +++ b/src/cmd/id.rs @@ -22,15 +22,15 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Print git hash of a StGit revision") + .about("Print the git hash of a StGit revision") .long_about( - "Print the hash (object id) of a StGit revision.\n\ + "Print the git hash of a StGit revision.\n\ \n\ - In addition to standard Git revision specifiers (revspecs), \ - patches may be specified in the form '[:]' or \ - '[:]{base}' for the base of a stack. If no branch is \ - specified, the current branch is used by default. The parent \ - of a patch may be specified with '[:]^'.", + Convert a StGit revision specifier to its corresponding git commit hash. \ + In addition to standard Git revision specifiers (revspecs), patches may \ + be specified in the form '[:]' or '[:]{base}' for \ + the base of a stack. If no branch is specified, the current branch is used \ + by default. The parent of a patch may be specified with '[:]^'.", ) .arg(argset::branch_arg()) .arg( diff --git a/src/cmd/name.rs b/src/cmd/name.rs index 4e4be9f4..bc707e8d 100644 --- a/src/cmd/name.rs +++ b/src/cmd/name.rs @@ -25,13 +25,12 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Print patch name of a StGit revision") + .about("Print the patch name corresponding to a StGit revision") .long_about( - "Print the patch name of a StGit revision.\n\ + "Print the patch name corresponding to a StGit revision.\n\ \n\ - Try to get the name of the patch in the current \ - branch as specified by a StGit revision. Revisions \ - can be specified in the all the forms accepted by \ + Look up and display the patch name for a given StGit revision in the current \ + branch. Revisions can be specified in all the forms accepted by the \ \"stg id\" command.", ) .arg(argset::branch_arg()) diff --git a/src/cmd/sink.rs b/src/cmd/sink.rs index d0630adb..fd859b00 100644 --- a/src/cmd/sink.rs +++ b/src/cmd/sink.rs @@ -23,22 +23,22 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Move patches deeper in the stack") + .about("Reorder patches by moving them toward the bottom of the stack") .long_about( - "Move the specified patches down the stack.\n\ + "Reorder patches by moving them toward the bottom of the stack.\n\ \n\ If no patch is specified on the command line, the current (topmost) patch \ - is sunk. By default, patches are sunk to the bottom of the stack, but the \ + is moved. By default, patches are moved to the bottom of the stack, but the \ '--above' or '--below' (alias '--to') options may be used to place them \ above or below any applied patch.\n\ \n\ - Internally, sinking involves popping all patches to the bottom (or to the \ - target patch if '--above' or '--below' is used), then pushing the patches \ - to sink, and then, unless '--nopush' is specified, pushing back any other \ + Internally, this operation involves popping all patches to the bottom (or to \ + the target patch if '--above' or '--below' is used), then pushing the patches \ + being moved, and then, unless '--nopush' is specified, pushing back any other \ formerly applied patches.\n\ \n\ - Sinking may be useful, for example, to group stable patches at the bottom \ - of the stack where they less likely to be impacted by the push of another \ + This may be useful, for example, to group stable patches at the bottom \ + of the stack where they are less likely to be impacted by the push of another \ patch, and from where they can be more easily committed or pushed to \ another repository.\n\ ", diff --git a/src/cmd/spill.rs b/src/cmd/spill.rs index 9d2a0977..228b2378 100644 --- a/src/cmd/spill.rs +++ b/src/cmd/spill.rs @@ -24,12 +24,14 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Spill changes from the topmost patch") + .about("Remove changes from the topmost patch, keeping them in the index/worktree") .long_about( - "Spill changes from the topmost patch. Changes are removed from the patch, \ - but remain in the index and worktree.\n\ + "Remove changes from the topmost patch, keeping them in the index/worktree.\n\ \n\ - Spilling a patch may be useful for reselecting the files/hunks to be \ + The patch is updated to be empty, but its changes remain in the index and \ + worktree for further editing or selective staging.\n\ + \n\ + This operation may be useful for reselecting which files or hunks should be \ included in the patch.", ) .arg( diff --git a/src/cmd/sync.rs b/src/cmd/sync.rs index 56f31fca..261d765c 100644 --- a/src/cmd/sync.rs +++ b/src/cmd/sync.rs @@ -31,13 +31,16 @@ pub(super) const STGIT_COMMAND: super::StGitCommand = super::StGitCommand { fn make() -> clap::Command { clap::Command::new(STGIT_COMMAND.name) - .about("Synchronize patches with a branch or a series") + .about("Update patches with changes from another branch or series") .long_about( - "For each of the specified patches, perform a three-way merge with the \ - same patch in the specified branch or series. The command can be used for \ - keeping patches on several branches in sync. Note that the operation may \ - fail for some patches because of conflicts. The patches in the series \ - must apply cleanly.", + "Update patches with changes from another branch or series.\n\ + \n\ + For each specified patch, perform a three-way merge with the same patch \ + from the specified branch or series file. This allows keeping the same \ + patches synchronized across multiple branches.\n\ + \n\ + The operation may fail for some patches due to merge conflicts. The patches \ + in the series must apply cleanly.", ) .override_usage(super::make_usage( "stg sync",