Merge branch 'master' into feature/positional-args

Author: Matt Pearson

arg-parsing-test.bats

@@ -0,0 +1,78 @@
+#!/usr/bin/env bats
+
+source lib/assert.bash
+source deploy.sh --source-only
+
+setup() {
+	run mktemp -dt deploy_test.XXXX
+	assert_success
+	tmp=$output
+	pushd "$tmp" >/dev/null
+}
+
+teardown() {
+	popd >/dev/null
+	rm -rf "$tmp"
+}
+
+set_env_vars() {
+	# Set environment variables.
+	export GIT_DEPLOY_APPEND_HASH=env-var
+}
+
+write_env_file() {
+	# Write a '.env' file to override environment variables.
+	cat <<-EOF > .env
+		GIT_DEPLOY_APPEND_HASH=env-file
+	EOF
+}
+
+write_conf_file() {
+	# Write a config-file to override '.env'.
+	cat <<-EOF > conf
+		GIT_DEPLOY_APPEND_HASH=conf-file
+	EOF
+}
+
+@test 'Arg-parsing defaults to in-script values.' {
+	parse_args
+	assert that "$append_hash" = "true"
+}
+
+@test '        overrides script defaults with environment variables.' {
+	set_env_vars
+
+	parse_args
+	assert that "$append_hash" = "env-var"
+}
+
+@test '        overrides environment variables with .env file.' {
+	set_env_vars
+	write_env_file
+
+	parse_args
+	assert that "$append_hash" = "env-file"
+}
+
+@test '        overrides .env with a file specified on the command-line.' {
+	set_env_vars
+	write_env_file
+	write_conf_file
+
+	parse_args --config-file conf
+	assert that "$append_hash" = "conf-file"
+}
+
+@test '        overrides everything with a command-line option.' {	
+	set_env_vars
+	write_env_file
+	write_conf_file
+
+	parse_args --config-file conf --no-hash
+	assert that "$append_hash" = "false"
+}
+@test '        sets a commit message with spaces in it.' {
+	parse_args --message "a message"
+	assert that "$commit_message" = "a message"
+}
+

deploy.sh

@@ -1,19 +1,55 @@
 #!/usr/bin/env bash
 set -o errexit #abort if any command fails
+me=$(basename "$0")
+
+help_message="\
+Usage: $me [-c FILE] [<options>]
+Deploy generated files to a git branch.
+
+Options:
+
+  -h, --help               Show this help information.
+  -v, --verbose            Increase verbosity. Useful for debugging.
+  -e, --allow-empty        Allow deployment of an empty directory.
+  -m, --message MESSAGE    Specify the message used when committing on the
+                           deploy branch.
+  -n, --no-hash            Don't append the source commit's hash to the deploy
+                           commit's message.
+  -c, --config-file PATH   Override default & environment variables' values
+                           with those in set in the file at 'PATH'. Must be the
+                           first option specified.
+
+Variables:
+
+  GIT_DEPLOY_DIR      Folder path containing the files to deploy.
+  GIT_DEPLOY_BRANCH   Commit deployable files to this branch.
+  GIT_DEPLOY_REPO     Push the deploy branch to this repository.
+
+These variables have default values defined in the script. The defaults can be
+overridden by environment variables. Any environment variables are overridden
+by values set in a '.env' file (if it exists), and in turn by those set in a
+file specified by the '--config-file' option."
 
 parse_args() {
 	# Set args from a local environment file.
 	if [ -e ".env" ]; then
 		source .env
 	fi
 
-	#append commit hash to the end of message by default
-	append_hash=true
+	# Set args from file specified on the command-line.
+	if [[ $1 = "-c" || $1 = "--config-file" ]]; then
+		source "$2"
+		shift 2
+	fi
 
 	# Parse arg flags
-	# [<options>] [<directory> [<branch> [<repository]]]
+	# If something is exposed as an environment variable, set/overwrite it
+	# here. Otherwise, set/overwrite the internal variable instead.
 	while : ; do
-		if [[ $1 = "-v" || $1 = "--verbose" ]]; then
+		if [[ $1 = "-h" || $1 = "--help" ]]; then
+			echo "$help_message"
+			return 0
+		elif [[ $1 = "-v" || $1 = "--verbose" ]]; then
 			verbose=true
 			shift
 		elif [[ $1 = "-e" || $1 = "--allow-empty" ]]; then
@@ -23,11 +59,8 @@ parse_args() {
 			commit_message=$2
 			shift 2
 		elif [[ $1 = "-n" || $1 = "--no-hash" ]]; then
-			append_hash=false
+			GIT_DEPLOY_APPEND_HASH=false
 			shift
-		elif [[ $1 = "-c" || $1 = "--config-file" ]]; then
-			source "$2"
-			shift 2
 		elif [[ -n ${1} ]]; then
 			# Set positional args
 			deploy_directory=$1
@@ -43,7 +76,10 @@ parse_args() {
 		fi
 	done
 
-	# Set default options
+	# Set internal option vars from the environment and arg flags. All internal
+	# vars should be declared here, with sane defaults if applicable.
+
+	# Source directory & target branch.
 	deploy_directory=${GIT_DEPLOY_DIR:-dist}
 	deploy_branch=${GIT_DEPLOY_BRANCH:-gh-pages}
 
@@ -53,6 +89,9 @@ parse_args() {
 
 	#repository to deploy to. must be readable and writable.
 	repo=${GIT_DEPLOY_REPO:-origin}
+
+	#append commit hash to the end of message by default
+	append_hash=${GIT_DEPLOY_APPEND_HASH:-true}
 }
 
 main() {

readme.md

@@ -37,7 +37,9 @@ Do this every time you want to deploy, or have your CI server do it.
 5. run `./deploy.sh`
 
 ### options
-`-c`, `--config-file`: specify a file that overrides the script's default configuration, or those values set in `.env`. The syntax for this file should be normal `var=value` declarations.
+`-h`, `--help`: show the program's help info.
+
+`-c`, `--config-file`: specify a file that overrides the script's default configuration, or those values set in `.env`. The syntax for this file should be normal `var=value` declarations. __This option _must_ come first on the command-line__.
 
 `-m`, `--message <message>`: specify message to be used for the commit on `deploy_branch`. By default, the message is the title of the source commit, prepended with 'publish: '.