docs: avoid using the command name as a verb to explain itself.

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")

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",

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. \

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 '[<branch>:]<patch>' or \
-             '[<branch>:]{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 '[<branch>:]<patch>^'.",
+             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 '[<branch>:]<patch>' or '[<branch>:]{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 '[<branch>:]<patch>^'.",
         )
         .arg(argset::branch_arg())
         .arg(

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())

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\
              ",

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(

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",