git-rewrite-branch: touch up

 * change USAGE to not imply an order between `-h` `-v` and `--svn`
 * have panic() print to stderr, not stdout
 * use [[ $var == string ]] instead of [[ $var = string ]] for readability
   (the only place I used a single = was when checking argument numbers)
 * add "Usage:" comments to functions
 * move git-rewrite-branch--appendid into the main file, as a quoted string

2 files changed, 28 insertions, 10 deletions

diff --git a/git-rewrite-branch b/git-rewrite-branch
index 5135fdc..b9c6ab3 100755
--- a/git-rewrite-branch
+++ b/git-rewrite-branch
@@ -3,7 +3,7 @@
 # Copyright (c) 2012-2013 Luke Shumaker <lukeshu@sbcglobal.net>
 #
 
-USAGE='[-h] [-v] [--svn] <in-branch> <out-branch> <filters>...'
+USAGE='[-h|-v|--svn] <in-branch> <out-branch> <filters>...'
 LONG_USAGE='Like filter-branch, but can be used to update branches.
 
 This creates or updates <out-branch> from <in-branch>.  If <in-branch> already
@@ -36,18 +36,24 @@ obranch=''
 wbranch=''
 
 panic() {
-	echo 'panic: malformed call to internal function'
+	echo 'panic: malformed call to internal function' >&2
 	exit 1
 }
 
+# Usage: verbose arg1 arg2...
+# Print the arguments, but only if in verbose mode.
+# Verbose mode works by redefining this function during option parsing if -v is
+# encountered.
 verbose() {
 	:
 }
 
 ################################################################################
 
+# Usage: id2commit $branch $id
+# Returns the commit on $branch with $id.
 id2commit() {
-	[[ $# = 2 ]] || panic
+	[[ $# == 2 ]] || panic
 	local branch=$1
 	local id=$2
 	if [[ $branch == $ibranch ]] && $gitmode; then
@@ -57,8 +63,10 @@ id2commit() {
 	fi
 }
 
+# Usage: commit2id $branch $commit
+# Returns the id of $commit, which is on $branch.
 commit2id() {
-	[[ $# = 2 ]] || panic
+	[[ $# == 2 ]] || panic
 	local branch=$1
 	local commit=$2
 	if [[ $branch == $ibranch ]] && $gitmode; then
@@ -69,8 +77,11 @@ commit2id() {
 }
 
 # commit2commit
+# Usage: c2c $from $to $commit
+# Returns the commit on branch $to that has the same id as $commit, which is
+# on branch $from.
 c2c() {
-	[[ $# = 3 ]] || panic
+	[[ $# == 3 ]] || panic
 	local from=$1
 	local to=$2
 	local commit=$3
@@ -119,7 +130,18 @@ main() {
 
 	local filters=();
 	if $gitmode; then
-		filters=(--msg-filter "git-rewrite-branch--appendid '${tag}'")
+		# Add a filter to append the id to the commit message.
+		# This is a little confusing to read because of double quoting.
+		filters=(--msg-filter "sed '\$a'\"${tag}: \${GIT_COMMIT}\"")
+		# Here it is annotated; "@" indicates characters to be taken
+		# literally, and "^" indicates string expansion.
+		#
+		# Argument to git-filter-branch:
+		#    sed '$a'"${tag}: ${GIT_COMMIT}"
+		#    @@@@@@@@@^^^^^^@@@@@@@@@@@@@@@@
+		# Argument to sed:
+		#    $a${tag}: ${GIT_COMMIT}
+		#    @@^^^^^^@@^^^^^^^^^^^^^
 	fi
 	filters+=("$@")
 
diff --git a/git-rewrite-branch--appendid b/git-rewrite-branch--appendid
deleted file mode 100755
index e44180a..0000000
--- a/git-rewrite-branch--appendid
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/bin/bash
-
-tag=$1
-sed '$a'"${tag}: ${GIT_COMMIT}"