commit f0044e44f2afaac08bf8b7ac931a652a8d998904 Author: teor teor@torproject.org Date: Tue Sep 10 12:14:49 2019 +1000
scripts: Make the git scripts show usage messages
All of the git scripts now have usage messages on: * a new -h option, and * usage errors.
Closes 31677. --- scripts/git/git-merge-forward.sh | 63 ++++++++++++++++++---------- scripts/git/git-pull-all.sh | 74 +++++++++++++++++++++++---------- scripts/git/git-push-all.sh | 89 +++++++++++++++++++++++++++++----------- 3 files changed, 161 insertions(+), 65 deletions(-)
diff --git a/scripts/git/git-merge-forward.sh b/scripts/git/git-merge-forward.sh index cbd2f3c3b..e481b4097 100755 --- a/scripts/git/git-merge-forward.sh +++ b/scripts/git/git-merge-forward.sh @@ -1,31 +1,47 @@ #!/usr/bin/env bash
-# Usage: git-merge-forward.sh -n -t <test-branch-prefix> -u -# arguments: -# -n: dry run mode -# -t: test branch mode: create new branches from the commits checked -# out in each maint directory. Call these branches prefix_029, -# prefix_035, ... , prefix_master. -# -u: in test branch mode, if a prefix_* branch exists, skip creating -# that branch. Use after a merge error, to restart the merge -# forward at the first unmerged branch. -# env vars: -# See the Configuration section for env vars and their default values. +SCRIPT_NAME=`basename $0` + +function usage() +{ + echo "$SCRIPT_NAME [-h] [-n] [-t <test-branch-prefix> [-u]]" + echo + echo " arguments:" + echo " -h: show this help text" + echo " -n: dry run mode" + echo " (default: run commands)" + echo " -t: test branch mode: create new branches from the commits checked" + echo " out in each maint directory. Call these branches prefix_029," + echo " prefix_035, ... , prefix_master." + echo " (default: merge forward maint-*, release-*, and master)" + echo " -u: in test branch mode, if a prefix_* branch already exists," + echo " skip creating that branch. Use after a merge error, to" + echo " restart the merge forward at the first unmerged branch." + echo " (default: if a prefix_* branch already exists, fail and exit)" + echo + echo " env vars:" + echo " required:" + echo " TOR_FULL_GIT_PATH: where the git repository directories reside." + echo " You must set this env var, we recommend $HOME/git/" + echo " (default: fail if this env var is not set;" + echo " current: $GIT_PATH)" + echo + echo " optional:" + echo " TOR_MASTER: the name of the directory containing the tor.git clone" + echo " The tor master git directory is $GIT_PATH/$TOR_MASTER" + echo " (default: tor; current: $TOR_MASTER_NAME)" + echo " TOR_WKT_NAME: the name of the directory containing the tor" + echo " worktrees. The tor worktrees are:" + echo " $GIT_PATH/$TOR_WKT_NAME/{maint-*,release-*}" + echo " (default: tor-wkt; current: $TOR_WKT_NAME)" + echo " we recommend that you set these env vars in your ~/.profile" +}
################# # Configuration # #################
# Don't change this configuration - set the env vars in your .profile -# -# The general setup that is suggested here is: -# -# GIT_PATH = /home/<user>/git/ -# ... where the git repository directories resides. -# TOR_MASTER_NAME = "tor" -# ... which means that tor.git was cloned in /home/<user>/git/tor -# TOR_WKT_NAME = "tor-wkt" -# ... which means that the tor worktrees are in /home/<user>/git/tor-wkt
# Where are all those git repositories? GIT_PATH=${TOR_FULL_GIT_PATH:-"FULL_PATH_TO_GIT_REPOSITORY_DIRECTORY"} @@ -126,8 +142,11 @@ TEST_BRANCH_PREFIX= # creating a new branch. USE_EXISTING=0
-while getopts "nt:u" opt; do +while getopts "hnt:u" opt; do case "$opt" in + h) usage + exit 0 + ;; n) DRY_RUN=1 echo " *** DRY RUN MODE ***" ;; @@ -138,6 +157,8 @@ while getopts "nt:u" opt; do echo " *** USE EXISTING TEST BRANCHES MODE ***" ;; *) + echo + usage exit 1 ;; esac diff --git a/scripts/git/git-pull-all.sh b/scripts/git/git-pull-all.sh index 26e26e8b5..0d6daf432 100755 --- a/scripts/git/git-pull-all.sh +++ b/scripts/git/git-pull-all.sh @@ -1,17 +1,39 @@ #!/usr/bin/env bash
-################################## -# User configuration (change me) # -################################## +SCRIPT_NAME=`basename $0`
-# The general setup that is suggested here is: -# -# GIT_PATH = /home/<user>/git/ -# ... where the git repository directories resides. -# TOR_MASTER_NAME = "tor" -# ... which means that tor.git was cloned in /home/<user>/git/tor -# TOR_WKT_NAME = "tor-wkt" -# ... which means that the tor worktrees are in /home/<user>/git/tor-wkt +function usage() +{ + echo "$SCRIPT_NAME [-h] [-n]" + echo + echo " arguments:" + echo " -h: show this help text" + echo " -n: dry run mode" + echo " (default: run commands)" + echo + echo " env vars:" + echo " required:" + echo " TOR_FULL_GIT_PATH: where the git repository directories reside." + echo " You must set this env var, we recommend $HOME/git/" + echo " (default: fail if this env var is not set;" + echo " current: $GIT_PATH)" + echo + echo " optional:" + echo " TOR_MASTER: the name of the directory containing the tor.git clone" + echo " The tor master git directory is $GIT_PATH/$TOR_MASTER" + echo " (default: tor; current: $TOR_MASTER_NAME)" + echo " TOR_WKT_NAME: the name of the directory containing the tor" + echo " worktrees. The tor worktrees are:" + echo " $GIT_PATH/$TOR_WKT_NAME/{maint-*,release-*}" + echo " (default: tor-wkt; current: $TOR_WKT_NAME)" + echo " we recommend that you set these env vars in your ~/.profile" +} + +################# +# Configuration # +################# + +# Don't change this configuration - set the env vars in your .profile
# Where are all those git repositories? GIT_PATH=${TOR_FULL_GIT_PATH:-"FULL_PATH_TO_GIT_REPOSITORY_DIRECTORY"} @@ -88,10 +110,30 @@ WORKTREE=( ) COUNT=${#WORKTREE[@]}
+####################### +# Argument processing # +####################### + # Controlled by the -n option. The dry run option will just output the command # that would have been executed for each worktree. DRY_RUN=0
+while getopts "hn" opt; do + case "$opt" in + h) usage + exit 0 + ;; + n) DRY_RUN=1 + echo " *** DRY DRUN MODE ***" + ;; + *) + echo + usage + exit 1 + ;; + esac +done + ############# # Constants # ############# @@ -195,16 +237,6 @@ function fetch_tor_github # Entry point # ###############
-while getopts "n" opt; do - case "$opt" in - n) DRY_RUN=1 - echo " *** DRY DRUN MODE ***" - ;; - *) - ;; - esac -done - # First, fetch tor-github. goto_repo "$ORIGIN_PATH" fetch_tor_github diff --git a/scripts/git/git-push-all.sh b/scripts/git/git-push-all.sh index ccbca012f..a388f0156 100755 --- a/scripts/git/git-push-all.sh +++ b/scripts/git/git-push-all.sh @@ -1,26 +1,65 @@ #!/usr/bin/env bash
-# Usage: git-push-all.sh -t <test-branch-prefix> -r <remote-name> -s -# -- <git-opts> -# arguments: -# -t: test branch mode: Push test branches, rather than maint and -# release branches. Pushes the branches called prefix_029, -# prefix_035, ... , prefix_master. -# -r: push to remote-name, rather than $TOR_UPSTREAM_REMOTE_NAME. -# -s: push branches whose tips match upstream maint, release, or -# master branches. The default is to skip these branches. Use -# -s when testing for CI environment failures with old code. -# --: pass any other arguments to git, rather than the script. -# env vars: -# TOR_GIT_PUSH: the git push command and arguments -# TOR_UPSTREAM_REMOTE_NAME: the default upstream, overridden by -r -# TOR_PUSH_DELAY: pushes the master and maint branches separately, -# so that CI runs in a sensible order. -# TOR_PUSH_SAME: push branches whose tips match upstream maint, -# release, or master branches. Inverted by -s. -# See the Configuration section for env var default values. -# git-opts: -# --no-atomic --dry-run (and any other git push option) +SCRIPT_NAME=`basename $0` + +function usage() +{ + if [ "$TOR_PUSH_SAME" ]; then + CURRENT_PUSH_SAME="push" + else + CURRENT_PUSH_SAME="skip" + fi + + echo "$SCRIPT_NAME [-h] [-r <remote-name> [-t <test-branch-prefix>]] [-s]" + # The next line looks misaligned, but it lines up in the output + echo " [-- [-n] [--no-atomic] <git push options>]" + echo + echo " arguments:" + echo " -h: show this help text" + echo " -n: dry run mode" + echo " (default: run commands)" + echo " -r: push to remote-name, rather than the default upstream remote." + echo " (default: $DEFAULT_UPSTREAM_REMOTE, current: $UPSTREAM_REMOTE)" + echo " -t: test branch mode: push test branches to remote-name. Pushes" + echo " branches prefix_029, prefix_035, ... , prefix_master." + echo " (default: push maint-*, release-*, and master)" + echo " -s: push branches whose tips match upstream maint, release, or" + echo " master branches. The default is to skip these branches," + echo " because they do not contain any new code. Use -s to test for" + echo " CI environment failures, using code that previously passed CI." + echo " (default: skip; current: $CURRENT_PUSH_SAME matching branches)" + echo " --: pass further arguments to git push." + echo " (default: git push --atomic, current: $GIT_PUSH)" + echo + echo " env vars:" + echo " optional:" + echo " TOR_GIT_PUSH_PATH: change to this directory before pushing." + echo " (default: if $TOR_FULL_GIT_PATH is set," + echo " use $TOR_FULL_GIT_PATH/$TOR_MASTER;" + echo " Otherwise, use the current directory for pushes;" + echo " current: $TOR_GIT_PUSH_PATH)" + echo " TOR_FULL_GIT_PATH: where the git repository directories reside." + echo " We recommend using $HOME/git/." + echo " (default: use the current directory for pushes;" + echo " current: $TOR_FULL_GIT_PATH)" + echo " TOR_MASTER: the name of the directory containing the tor.git clone" + echo " The tor master git directory is $GIT_PATH/$TOR_MASTER" + echo " (default: tor; current: $TOR_MASTER_NAME)" + echo + echo " TOR_UPSTREAM_REMOTE_NAME: the default upstream remote." + echo " Overridden by -r." + echo " (default: upstream; current: $UPSTREAM_REMOTE)" + echo " TOR_GIT_PUSH: the git push command and default arguments." + echo " Overridden by <git push options> after --." + echo " (default: git push --atomic; current: $GIT_PUSH)" + echo " TOR_PUSH_SAME: push branches whose tips match upstream maint," + echo " release, or master branches. Inverted by -s." + echo " (default: skip; current: $CURRENT_PUSH_SAME matching branches)" + echo " TOR_PUSH_DELAY: pushes the master and maint branches separately," + echo " so that CI runs in a sensible order." + echo " (default: push all branches immediately; current: $PUSH_DELAY)" + echo " we recommend that you set these env vars in your ~/.profile" +}
set -e
@@ -61,8 +100,11 @@ PUSH_SAME=${TOR_PUSH_SAME:-0} # <tbbn>_029, <tbbn>_035, ... , <tbbn>_master, and merge forward. TEST_BRANCH_PREFIX=
-while getopts ":r:st:" opt; do +while getopts ":hr:st:" opt; do case "$opt" in + h) usage + exit 0 + ;; r) UPSTREAM_REMOTE="$OPTARG" echo " *** PUSHING TO REMOTE: ${UPSTREAM_REMOTE} ***" shift @@ -102,7 +144,8 @@ if [ "$TEST_BRANCH_PREFIX" ]; then if [ "$UPSTREAM_REMOTE" = "$DEFAULT_UPSTREAM_REMOTE" ]; then echo "Pushing test branches ${TEST_BRANCH_PREFIX}_nnn to " \ "the default remote $DEFAULT_UPSTREAM_REMOTE is not allowed." - echo "Usage: $0 -r <remote-name> -t <test-branch-prefix> <git-opts>" + echo + usage exit 1 fi fi