From ac020225c2994e3573020d953480cdb6e04e0eea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohni=C4=87?= <git@mislav.net>
Date: Mon, 29 Apr 2024 14:20:47 +0200
Subject: [PATCH] Clarify help text of some commands (#1567)

---
 libexec/rbenv-commands |  6 ++++++
 libexec/rbenv-exec     |  2 +-
 libexec/rbenv-help     |  7 +++++--
 libexec/rbenv-rehash   | 13 ++++++++++++-
 test/help.bats         |  2 +-
 5 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/libexec/rbenv-commands b/libexec/rbenv-commands
index e084331..a8c08de 100755
--- a/libexec/rbenv-commands
+++ b/libexec/rbenv-commands
@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # Summary: List all available rbenv commands
 # Usage: rbenv commands [--sh|--no-sh]
+#
+# List names of all rbenv commands, including 3rd-party ones found in the
+# PATH or in rbenv plugins. With `--sh`, list only shell commands.
+#
+# This functionality is mainly meant for scripting. To see usage help for
+# rbenv, run `rbenv help`.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-exec b/libexec/rbenv-exec
index 3520c9d..fac0eb8 100755
--- a/libexec/rbenv-exec
+++ b/libexec/rbenv-exec
@@ -2,7 +2,7 @@
 #
 # Summary: Run an executable with the selected Ruby version
 #
-# Usage: rbenv exec <command> [arg1 arg2...]
+# Usage: rbenv exec <command> [<args>...]
 #
 # Runs an executable by first preparing PATH so that the selected Ruby
 # version's `bin' directory is at the front.
diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index 84d6e46..8e5eaf0 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -164,8 +164,11 @@ if [ -z "$1" ] || [ "$1" == "rbenv" ]; then
   echo "Usage: rbenv <command> [<args>...]"
   [ -n "$usage" ] && exit
   echo
-  echo "Some useful rbenv commands are:"
-  print_summaries commands local global shell install uninstall rehash version versions which whence
+  echo "Commands to manage available Ruby versions:"
+  print_summaries versions install uninstall rehash
+  echo
+  echo "Commands to view or change the current Ruby version:"
+  print_summaries version local global shell
   echo
   echo "See \`rbenv help <command>' for information on a specific command."
   echo "For full documentation, see: https://github.com/rbenv/rbenv#readme"
diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash
index f819b82..8ed7674 100755
--- a/libexec/rbenv-rehash
+++ b/libexec/rbenv-rehash
@@ -1,5 +1,16 @@
 #!/usr/bin/env bash
-# Summary: Rehash rbenv shims (run this after installing executables)
+# Summary: Regenerate rbenv shims
+#
+# Regenerate shims for every Ruby executable in `$RBENV_ROOT/versions/*/bin'
+# and write them to the `$RBENV_ROOT/shims' directory. A shell environment
+# properly set up for rbenv will have this shims directory in PATH, which is
+# the core mechanism for Ruby version switching.
+#
+# Running rbenv rehash should only be necessary after installing new Ruby
+# versions or gems. Note that this is sometimes done automatically: the
+# `rbenv install' command from the ruby-build plugin runs rehash after
+# every successful installation, and a RubyGems plugin that ships with
+# rbenv runs rehash after every `gem install' command.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/test/help.bats b/test/help.bats
index 3102136..ac7525e 100644
--- a/test/help.bats
+++ b/test/help.bats
@@ -6,7 +6,7 @@ load test_helper
   run rbenv-help
   assert_success
   assert_line "Usage: rbenv <command> [<args>...]"
-  assert_line "Some useful rbenv commands are:"
+  assert_line "Commands to manage available Ruby versions:"
 }
 
 @test "usage flag" {