Merge pull request #55 from matthiasbeyer/docv0.1

Doc

4 files changed, 83 insertions, 6 deletions

diff --git a/README.md b/README.md
index 62fd71f..d580d2c 100644
--- a/README.md
+++ b/README.md
@@ -33,23 +33,23 @@ nix-script diff-generations -s -n 114..115
 
 Execute "nixos-rebuild switch" and tags the current checked-out commit
 in "/home/myself/nixos-configuration/" on successfull build (including
-generation number). Default format for the tag name is
+generation number). Format for the tag name is
 
 ```plain
-  nixos-<generation>-<command>
+  nixos-[<hostname>-]<generation>-<command>
 ```
 
 Where <generation> is the generation which was just build
 and <command> is the command for nixos-rebuild, so either switch or test
 or... you get the point
 
-You can, of course, override the tag name (no way to insert the generation
-number by now) or the git command to use ('tag -a' be default).
-
 ```bash
 nix-script switch -c switch -w /home/myself/nixos-configuration/
 ```
 
+Add a `-n` to include the hostname into the tag name (usefull if you share
+your configuration over several hosts, as I do).
+
 You can also provide flags for 'nixos-rebuild' like so:
 (everything after the two dashes is appended to the nixos-rebuild command)
 
@@ -57,6 +57,8 @@ You can also provide flags for 'nixos-rebuild' like so:
 nix-script switch -c switch -w /home/myself/conf -- -I nixpkgs=/home/myself/pkgs
 ```
 
+Dive into the code or use the `-h` flags for getting more help.
+
 ## License
 
 This code is released under the terms of GNU GPL v2.
diff --git a/nix-script b/nix-script
index 5c22a90..308cb3c 100755
--- a/nix-script
+++ b/nix-script
@@ -17,24 +17,46 @@ VERBOSE=0
 
 source $(dirname ${BASH_SOURCE[0]})/nix-utils.sh
 
+#
+# Get the name of the script file for the command passed as argument
+#
+# Does not check whether the file exists.
+#
 script_for() {
     echo "$(dirname ${BASH_SOURCE[0]})/nix-script-${1}.sh"
 }
 
 SHIFT_ARGS=0
+
+#
+# Increase the SHIFT_ARGS variable
+#
 shift_one_more() {
     SHIFT_ARGS=$(( SHIFT_ARGS + 1 ))
 }
 
+#
+# Shift N times the arguments, so:
+#
+#  shift_n 5 a b c d e f
+#
+# will print "f"
+#
 shift_n() {
     for n in `seq 0 $1`; do shift; done
     echo $*
 }
 
+#
+# List all available commands
+#
 all_commands() {
     find $(dirname ${BASH_SOURCE[0]}) -type f -name "nix-script-*.sh"
 }
 
+#
+# Parse the arguments for this script
+#
 for cmd
 do
     case $cmd in
@@ -91,11 +113,17 @@ fi
 stdout "Searching for script for '$COMMAND'"
 SCRIPT=$(script_for $COMMAND)
 
+#
+# Error checking whether the script is available and executable.
+#
 [ ! -f $SCRIPT ]   && stderr "Not available: $COMMAND -> $SCRIPT" && exit 1
 [[ ! -x $SCRIPT ]] && stderr "Not executeable: $SCRIPT"           && exit 1
 
 stdout "Parsing args for '$COMMAND'"
 SCRIPT_ARGS=$(shift_n $SHIFT_ARGS $*)
 
+#
+# execute the script with its arguments
+#
 stdout "Calling: '$SCRIPT $SCRIPT_ARGS'"
 exec bash $SCRIPT $SCRIPT_ARGS
diff --git a/nix-script-diff-generations.sh b/nix-script-diff-generations.sh
index 0df561d..4dd11d2 100755
--- a/nix-script-diff-generations.sh
+++ b/nix-script-diff-generations.sh
@@ -65,6 +65,9 @@ do
     esac
 done
 
+#
+# Helper to generate a path for the profile we want to diff with
+#
 gen_path() {
     [[ $__SYSTEM -eq 1 ]] && echo "/nix/var/nix/profiles/system-${1}-link"
     [[ $__USER -eq 1 ]] && echo "/nix/var/nix/profiles/per-user/$USER/profile-${1}-link"
@@ -81,16 +84,24 @@ stdout "from directory  : $DIR_A"
 stdout "Generation B    : $GEN_B"
 stdout "from directory  : $DIR_B"
 
+#
+# Error checking whether the generations exist.
+#
 [[ -z "$GEN_A" || -z "$GEN_B" ]] && stderr "No generations"     && exit 1
 [[ ! -e $DIR_A ]] && stderr "Generation $GEN_A does not exist." && exit 1
 [[ ! -e $DIR_B ]] && stderr "Generation $GEN_B does not exist." && exit 1
 
+#
+# Querying the store for the stuff in a generation A
+#
 versA=$(mktemp)
 stdout "TMP file '$versA' created"
 nix-store -qR $DIR_A | sort -t'-' -k 2 > $versA
 stdout "Generation packages written for $GEN_A"
 
-
+#
+# Querying the store for the stuff in a generation B
+#
 versB=$(mktemp)
 stdout "TMP file '$versB' created"
 nix-store -qR $DIR_B | sort -t'-' -k 2 > $versB
diff --git a/nix-utils.sh b/nix-utils.sh
index 39c7b80..7887feb 100644
--- a/nix-utils.sh
+++ b/nix-utils.sh
@@ -5,24 +5,39 @@ Red='\e[0;31m'
 Yellow='\e[0;33m'
 Green='\e[0;32m'
 
+#
+# Print on stderr, in red
+#
 stderr() {
     echo -e "${Red}[$(basename $0)]: ${*}${Color_Off}" >&2
 }
 
+#
+# Print on stdout, if verbosity is enabled, prefix in green
+#
 stdout() {
     [[ $VERBOSE -eq 1 ]] && echo -e "${Green}[$(basename $0)]:${Color_Off} $*"
 }
 
+#
+# Get the command name from a script path
+#
 scriptname_to_command() {
         echo "$1" | sed 's,^\.\/nix-script-,,' | sed 's,\.sh$,,' | \
             sed -r "s,$(dirname ${BASH_SOURCE[0]})/nix-script-,,"
 }
 
+#
+# Generate a help synopsis text
+#
 help_synopsis() {
     SCRIPT=$(scriptname_to_command $1); shift
     echo "usage: nix-script $SCRIPT $*"
 }
 
+#
+# generate a help text footnote
+#
 help_end() {
     echo -e "\tAdding '-v' before the '$1' command turns on verbosity"
     echo -e ""
@@ -31,23 +46,38 @@ help_end() {
     echo ""
 }
 
+#
+# Explain the next command
+#
 explain() {
     stdout "$*"
     $*
 }
 
+#
+# Helper for greping the current generation
+#
 grep_generation() {
     $* | grep current | sed -r 's,\s*([0-9]*)(.*),\1,'
 }
 
+#
+# get the current system generation
+#
 current_system_generation() {
     grep_generation "sudo nix-env -p /nix/var/nix/profiles/system --list-generations"
 }
 
+#
+# get the current user generation
+#
 current_user_generation() {
     grep_generation "nix-env --list-generations"
 }
 
+#
+# Ask the user whether to continue or not
+#
 continue_question() {
 	local answer
 	echo -ne "${Yellow}$1 [yN]?:${Color_Off} " >&2
@@ -56,6 +86,9 @@ continue_question() {
 	[[ "${answer}" =~ ^[Yy]$ ]] || return 1
 }
 
+#
+# Ask whether a command should be executed or not.
+#
 ask_execute() {
     q="$1"; shift
 	local answer
@@ -64,6 +97,9 @@ ask_execute() {
 	[[ ! "${answer}" =~ ^[Nn]$ ]] && eval $*
 }
 
+#
+# Helper for executing git commands in another git directory
+#
 __git() {
     DIR=$1; shift
     explain git --git-dir="$DIR/.git" --work-tree="$DIR" $*