Improve command usage

10 files changed, 97 insertions, 10 deletions

diff --git a/src/subgit-check b/src/subgit-check
index 2ba748b..5a27b0a 100755
--- a/src/subgit-check
+++ b/src/subgit-check
@@ -3,7 +3,16 @@
 # Checks whether the branch / commit tracked by subgit for the
 # specified repos are up-to-date, and whether the worktree is dirty.
 
-usage() { die "Usage: subgit check PATH.."; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit check [PATH..]
+
+	  Checks whether tracked subrepositories have uncommitted changes,
+	  or if their remote, branch, or commit differ from what's recorded
+	  in .subgitrc. Reports any discrepancies or dirty working trees.
+	EOF
+	)
+}
 
 while [ "$1" ]; do
 	case $1 in
diff --git a/src/subgit-clone b/src/subgit-clone
index 7831519..205b518 100755
--- a/src/subgit-clone
+++ b/src/subgit-clone
@@ -2,7 +2,16 @@
 
 # Clones a repository for use in .subgit for tracking worktree changes.
 
-usage() { die "Usage: subgit clone [-b BRANCH] [CLONE-ARGS..] REMOTE PATH"; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit clone [-b BRANCH] [CLONE-ARGS..] REMOTE PATH
+
+	  Clones a bare repository for use in .subgit directory. The bare
+	  repository is configured to track changes from a remote while
+	  allowing the working tree to be symlinked separately.
+	EOF
+	)
+}
 
 while [ "$1" ]; do
 	case $1 in
diff --git a/src/subgit-init b/src/subgit-init
index 3299f76..7b22344 100755
--- a/src/subgit-init
+++ b/src/subgit-init
@@ -2,7 +2,20 @@
 
 # Initializes or updates the bare repository in the subgit container.
 
-usage() { die "Usage: subgit [init|pull] [-r] [PATH..]"; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit init [-r] [-f] [-u] [PATH..]
+
+	  Initializes or updates subrepositories by cloning bare repos into
+	  .subgit/ and symlinking working directories. Fetches and resets to
+	  the tracked commit/branch from .subgitrc.
+
+	  -r  Recursively initialize nested subgit repos
+	  -f  Force reset working trees (discards local changes)
+	  -u  Update .subgitrc with current commit after init
+	EOF
+	)
+}
 
 recursive=
 force=
diff --git a/src/subgit-ls b/src/subgit-ls
index 3f8c6f0..5016684 100755
--- a/src/subgit-ls
+++ b/src/subgit-ls
@@ -1,6 +1,12 @@
 #!/bin/bash
 
-[ "$1" = "-h" ] && die "Usage: subgit ls"
+[ "$1" = "-h" ] && die $(cat <<-EOF
+	Usage: subgit ls
+
+	  Lists all tracked subrepositories (relative paths) from the
+	  current subgit container's .subgitrc file.
+	EOF
+	)
 
 root=$(subgit-source root .)
 source "$root/.subgitrc"
diff --git a/src/subgit-parent b/src/subgit-parent
index 92ac56b..c3999a8 100755
--- a/src/subgit-parent
+++ b/src/subgit-parent
@@ -3,7 +3,16 @@
 # Returns the longest subpath of the given path, which
 # tracks the current path in its .subgit folder.
 
-usage() { die "Usage: subgit parent [PATH]"; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit parent [PATH]
+
+	  Finds the subgit container (root directory with .subgitrc) that
+	  tracks the given PATH as a subrepository. Walks up the directory
+	  tree to find the appropriate parent.
+	EOF
+	)
+}
 
 while [ "$1" ]; do
 	case $1 in
diff --git a/src/subgit-relpath b/src/subgit-relpath
index 6e47625..f22f119 100755
--- a/src/subgit-relpath
+++ b/src/subgit-relpath
@@ -3,7 +3,16 @@
 # Finds the relative path at which tracking for a target path
 # starts within its subgit parent.
 
-usage() { die "Usage: subgit relpath ROOT PATH"; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit relpath ROOT PATH
+
+	  Determines the relative path (from ROOT) where tracking begins
+	  for the given PATH. Walks up from PATH until finding a tracked
+	  entry in ROOT's .subgitrc.
+	EOF
+	)
+}
 
 while [ "$1" ]; do
 	case $1 in
diff --git a/src/subgit-root b/src/subgit-root
index 1ef9650..9a02512 100755
--- a/src/subgit-root
+++ b/src/subgit-root
@@ -3,7 +3,16 @@
 # Returns the longest subpath of the given path
 # which includes a .subgitrc file.
 
-usage() { die "Usage: subgit root [PATH]"; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit root [PATH]
+
+	  Finds the root of the subgit container by walking up from PATH
+	  until finding a directory with a .subgitrc file. Returns the
+	  absolute path to that directory.
+	EOF
+	)
+}
 
 while [ "$1" ]; do
 	case $1 in
diff --git a/src/subgit-run b/src/subgit-run
index 98f6be7..4ba15c7 100755
--- a/src/subgit-run
+++ b/src/subgit-run
@@ -1,6 +1,13 @@
 #!/bin/bash
 
-[ $# -eq 0 ] && die "Usage: subgit run CMD [ARG..]"
+[ $# -eq 0 ] && die $(cat <<-EOF
+	Usage: subgit run CMD [ARG..]
+
+	  Executes a command in the current subrepository context,
+	  temporarily symlinking .git to the bare repository before
+	  running the command.
+	EOF
+	)
 
 root="$(subgit-sub root)"
 relpath=$(subgit-sub relpath "$root" .)
diff --git a/src/subgit-save b/src/subgit-save
index 3f6e8d1..570d166 100755
--- a/src/subgit-save
+++ b/src/subgit-save
@@ -1,6 +1,13 @@
 #!/bin/bash
 
-[ "$1" = "-h" ] && die "Usage: subgit update [PATH..]"
+[ "$1" = "-h" ] && die $(cat <<-EOF
+	Usage: subgit save [PATH..]
+
+	  Updates .subgitrc with current remote, branch, and commit from
+	  the bare repositories. Captures the current state of specified
+	  subrepositories (or all if none specified).
+	EOF
+	)
 
 root=$(subgit-sub root .)
 source "$root/.subgitrc"
diff --git a/src/subgit-subrepo b/src/subgit-subrepo
index 713d32f..d1271e2 100755
--- a/src/subgit-subrepo
+++ b/src/subgit-subrepo
@@ -3,7 +3,16 @@
 # Return either the subrepo path for each path or all
 # subrepo paths in the current subgit container.
 
-usage() { die "Usage: subgit subrepo [PATH..]"; }
+usage() {
+	die $(cat <<-EOF
+	Usage: subgit subrepo [PATH..]
+
+	  Resolves and returns absolute paths to subrepositories. With no
+	  arguments, lists all subrepos in current container. With arguments,
+	  normalizes each path to its tracked subrepo root.
+	EOF
+	)
+}
 
 while [ "$1" ]; do
 	case $1 in