diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..8d038485f --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +debian/files +debian/*.substvars +debian/*.debhelper.log +debian/*/* diff --git a/AUTHORS b/AUTHORS index 060f09ffe..aded955fc 100644 --- a/AUTHORS +++ b/AUTHORS @@ -11,5 +11,14 @@ Authors are (ordered by first commit date): - Felipe Talavera - Guillaume-Jean Herbiet - Joseph A. Levin +- Jannis Leidel +- Konstantin Tjuterev +- Kiall Mac Innes +- Jon Bernard +- Olivier Mengué +- Emre Berge Ergenekon +- Eric Holmes +- Vedang Manerikar +- Myke Hines Portions derived from other open source works are clearly marked. diff --git a/Changes.mdown b/Changes.mdown index 72c04bc7f..2281f2307 100644 --- a/Changes.mdown +++ b/Changes.mdown @@ -1,3 +1,24 @@ +0.4.2: +----- +Release date: **not yet** + +* `git flow init` now detects situations where origin already has gitflow + branches set up, and behaves accordingly (thanks Emre Berge Ergenekon). + +* `git flow feature finish` can now be called without a feature branch + name(prefix) argument and will finish the current branch, if on any. + +* `git flow feature pull` now has a `-r` flag, to support `pull --rebase` + semantics (thanks Vedang Manerikar). + +* Various minor bug fixes related to internal argument passing. + +* Improved some documentation. + +* Better support for Windows and BSD users. + +* Add package installer for the Windows platform. + 0.4.1: ----- Release date: **2011/02/04** diff --git a/Makefile b/Makefile index 6f82544fe..fbbfd2c00 100644 --- a/Makefile +++ b/Makefile @@ -26,6 +26,7 @@ # those of the authors and should not be interpreted as representing official # policies, either expressed or implied, of Vincent Driessen. # + prefix=/usr/local # files that need mode 755 diff --git a/README.mdown b/README.mdown index 44c13fb81..a01079b4b 100644 --- a/README.mdown +++ b/README.mdown @@ -1,5 +1,6 @@ -git-flow ![Project status](http://stillmaintained.com/nvie/gitflow.png) +git-flow ======== + A collection of Git extensions to provide high-level repository operations for Vincent Driessen's [branching model](http://nvie.com/git-model "original blog post"). @@ -14,86 +15,14 @@ Kreeftmeijer's blog post: Or have a look at one of these screen casts: +* [How to use a scalable Git branching model called git-flow](http://buildamodule.com/video/change-management-and-version-control-deploying-releases-features-and-fixes-with-git-how-to-use-a-scalable-git-branching-model-called-gitflow) (by Build a Module) * [A short introduction to git-flow](http://vimeo.com/16018419) (by Mark Derricutt) * [On the path with git-flow](http://codesherpas.com/screencasts/on_the_path_gitflow.mov) (by Dave Bock) Installing git-flow ------------------- - -### Mac OS -If you're on a Mac and use [homebrew](http://github.com/mxcl/homebrew), it's simple: - - $ brew install git-flow - -If you're on a Mac and use [MacPorts](http://macports.org/), it's simple: - - $ port install git-flow - -### Linux, etc. -Another easy way to install git-flow is using Rick Osborne's excellent git-flow -installer, which can be run using the following command: - - $ wget --no-check-certificate -q -O - https://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sudo sh - -### Windows -#### Using Cygwin -For Windows users who wish to use the automated install, it is suggested that you install [Cygwin](http://www.cygwin.com/) -first to install tools like `git`, `util-linux` and `wget` (with those three being packages that can be selected -during installation). Then simply run this command from a Cygwin shell: - - $ wget -q -O - https://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sh - -#### Using msysgit -This is much like the manual installation below, but there are additional steps required to install some extra tools that -are not distributed with [msysgit](http://code.google.com/p/msysgit/). - -Clone the git-flow sources from Github: - - $ git clone --recursive git://github.com/nvie/gitflow.git - -Copy git-flow's relevant files to your msysgit installation directory: - - $ mkdir /usr/local/bin - $ cp git-flow* gitflow* /usr/local/bin/ - $ cp shFlags/src/shflags /usr/local/bin/gitflow-shFlags - -Next up we need to borrow a couple of binaries from [Cygwin](http://www.cygwin.com/). If you don't have Cygwin installed, please -install it including the `util-linux` package. Apart from `util-linux`'s dependencies, no other packages are required. When you -finished installation, copy the following files using msysgit's _Git Bash_. We assume the Cygwin's default installation path in C:\cygwin. - - $ cd /c/cygwin/ - $ cp bin/getopt.exe /usr/local/bin/ - $ cp bin/cyggcc_s-1.dll /usr/local/bin/ - $ cp bin/cygiconv-2.dll /usr/local/bin/ - $ cp bin/cygintl-8.dll /usr/local/bin/ - $ cp bin/cygwin1.dll /usr/local/bin/ - -After copying the files above, you can safely uninstall your Cygwin installation by deleting the C:\cygwin directory. - -### Manual installation -If you prefer a manual installation, please use the following instructions: - - $ git clone --recursive git://github.com/nvie/gitflow.git - -Then, you can install `git-flow`, using: - - $ sudo make install - -By default, git-flow will be installed in /usr/local. To change the prefix -where git-flow will be installed, simply specify it explicitly, using: - - $ sudo make prefix=/opt/local install - -Or simply point your `PATH` environment variable to your git-flow checkout -directory. - -*Installation note:* -git-flow depends on the availability of the command line utility `getopt`, -which may not be available in your Unix/Linux environment. Please use your -favorite package manager to install `getopt`. For Cygwin, install the -`util-linux` package to get `getopt`. If you use `apt-get` as your install -manager, the package name is `opt`. +See the Wiki for up-to-date [Installation Instructions](https://github.com/nvie/gitflow/wiki/Installation). Integration with your shell @@ -104,9 +33,6 @@ For those who use the [Bash](http://www.gnu.org/software/bash/) or by [bobthecow](http://github.com/bobthecow). It offers tab-completion for all git-flow subcommands and branch names. -For Windows users, [msysgit](http://code.google.com/p/msysgit/) is a good -starting place for installing git. - FAQ --- @@ -127,6 +53,23 @@ contributors, please see the [AUTHORS](AUTHORS) file. Any questions, tips, or general discussion can be posted to our Google group: [http://groups.google.com/group/gitflow-users](http://groups.google.com/group/gitflow-users) +Contributing +------------ +Fork the repository. Then, run: + + git clone --recursive git@github.com:/gitflow.git + cd gitflow + git branch master origin/master + git flow init -d + git flow feature start + +Then, do work and commit your changes. **Hint**: ``export PATH=`pwd`:$PATH`` +from within the gitflow directory makes sure you're using the version of +gitflow you're currently developing. + + git flow feature publish + +When done, open a pull request to your feature branch. License terms ------------- @@ -141,13 +84,15 @@ in a Github fork, of course. To initialize a new repo with the basic branch structure, use: - git flow init + git flow init [-d] This will then interactively prompt you with some questions on which branches you would like to use as development and production branches, and how you would like your prefixes be named. You may simply press Return on any of those questions to accept the (sane) default suggestions. +The ``-d`` flag will accept all defaults. + ### Creating feature/release/hotfix/support branches @@ -159,6 +104,11 @@ those questions to accept the (sane) default suggestions. For feature branches, the `` arg must be a commit on `develop`. +* To push/pull a feature branch to the remote repository, use: + + git flow feature publish + git flow feature pull + * To list/start/finish release branches, use: git flow release @@ -188,7 +138,7 @@ Showing your appreciation A few people already requested it, so now it's here: a Flattr button. Of course, the best way to show your appreciation for the original -[blog post](http://nvie.com/git-model) or the git-flow tool itself remains +[blog post](http://nvie.com/posts/a-successful-git-branching-model/) or the git-flow tool itself remains contributing to the community. If you'd like to show your appreciation in another way, however, consider Flattr'ing me: diff --git a/contrib/gitflow-installer.sh b/contrib/gitflow-installer.sh index 33dbe583c..0e92ffcef 100644 --- a/contrib/gitflow-installer.sh +++ b/contrib/gitflow-installer.sh @@ -1,4 +1,4 @@ -#!/bin/sh +#!/bin/bash # git-flow make-less installer for *nix systems, by Rick Osborne # Based on the git-flow core Makefile: @@ -50,7 +50,7 @@ case "$1" in ;; *) echo "Installing git-flow to $INSTALL_PREFIX" - if [[ -d "$REPO_NAME" && -d "$REPO_NAME/.git" ]] ; then + if [ -d "$REPO_NAME" -a -d "$REPO_NAME/.git" ] ; then echo "Using existing repo: $REPO_NAME" else echo "Cloning repo from GitHub to $REPO_NAME" diff --git a/contrib/msysgit-install.cmd b/contrib/msysgit-install.cmd new file mode 100644 index 000000000..994235c79 --- /dev/null +++ b/contrib/msysgit-install.cmd @@ -0,0 +1,77 @@ +@echo off +setlocal +if not "%~1"=="" set GIT_HOME=%~f1 +if "%GIT_HOME%"=="" call :FindGitHome "git.cmd" + +if exist "%GIT_HOME%" goto :GitHomeOK + +echo MsysGit installation directory not found.>&2 +echo Try to give the directory name on the command line:>&2 +echo %0 "%ProgramFiles%\Git" +endlocal +exit /B 1 + +:GitHomeOK +set ERR=0 + +echo Installing gitflow into "%GIT_HOME%"... + +call :ChkGetopt getopt.exe || set ERR=1 +if %ERR%==1 goto :End +echo getopt.exe... Found + +if not exist "%GIT_HOME%\bin\git-flow" goto :Install +echo GitFlow is already installed.>&2 +set /p mychoice="Do you want to replace it [y/n]" +if "%mychoice%"=="y" goto :DeleteOldFiles +goto :Abort + +:DeleteOldFiles +echo Deleting old files... +for /F %%i in ("%GIT_HOME%\git-flow*" "%GIT_HOME%\gitflow-*") do if exist "%%~fi" del /F /Q "%%~fi" + +:Install +echo Copying files... +::goto :EOF +xcopy "%~dp0\..\git-flow" "%GIT_HOME%\bin" /Y /R /F +if errorlevel 4 if not errorlevel 5 goto :AccessDenied +if errorlevel 1 set ERR=1 +xcopy "%~dp0\..\git-flow*" "%GIT_HOME%\bin" /Y /R /F || set ERR=1 +xcopy "%~dp0\..\gitflow-*" "%GIT_HOME%\bin" /Y /R /F || set ERR=1 +xcopy "%~dp0\..\shFlags\src\shflags" "%GIT_HOME%\bin\gitflow-shFlags" /Y /R /F || set ERR=1 + +if %ERR%==1 choice /T 30 /C Y /D Y /M "Some unexpected errors happened. Sorry, you'll have to fix them by yourself." + +:End +endlocal & exit /B %ERR% +goto :EOF + +:AccessDenied +set ERR=1 +echo. +echo You should run this script with "Full Administrator" rights:>&2 +echo - Right-click with Shift on the script from the Explorer>&2 +echo - Select "Run as administrator">&2 +choice /T 30 /C YN /D Y /N >nul +goto :End + +:Abort +echo Installation canceled.>&2 +set ERR=1 +goto :End + +:ChkGetopt +:: %1 is getopt.exe +if exist "%GIT_HOME%\bin\%1" goto :EOF +if exist "%USERPROFILE%\bin\%1" goto :EOF +if exist "%~f$PATH:1" goto :EOF +echo %GIT_HOME%\bin\%1 not found.>&2 +echo You have to install this file manually. See the GitFlow README. +exit /B 1 + +:FindGitHome +setlocal +set GIT_CMD_DIR=%~dp$PATH:1 +if "%GIT_CMD_DIR%"=="" endlocal & goto :EOF +endlocal & set GIT_HOME=%GIT_CMD_DIR:~0,-5% +goto :EOF diff --git a/git-flow b/git-flow index fa87e71f4..fd16d5168 100755 --- a/git-flow +++ b/git-flow @@ -37,12 +37,17 @@ # policies, either expressed or implied, of Vincent Driessen. # +# set this to workaround expr problems in shFlags on freebsd +if uname -s | egrep -iq 'bsd'; then export EXPR_COMPAT=1; fi + # enable debug mode if [ "$DEBUG" = "yes" ]; then set -x fi -export GITFLOW_DIR=$(dirname "$0") +# The sed expression here replaces all backslashes by forward slashes. +# This helps our Windows users, while not bothering our Unix users. +export GITFLOW_DIR=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')") usage() { echo "usage: git flow " @@ -75,6 +80,11 @@ main() { # use the shFlags project to parse the command line arguments . "$GITFLOW_DIR/gitflow-shFlags" FLAGS_PARENT="git flow" + + # allow user to request git action logging + DEFINE_boolean show_commands false 'show actions taken (git commands)' g + + # do actual parsing FLAGS "$@" || exit $? eval set -- "${FLAGS_ARGV}" @@ -94,7 +104,7 @@ main() { # in that case, we interpret this arg as a flag for the default # command SUBACTION="default" - if [ "$1" != "" ] && ! echo "$1" | grep -q "^-"; then + if [ "$1" != "" ] && { ! echo "$1" | grep -q "^-"; } then SUBACTION="$1"; shift fi if ! type "cmd_$SUBACTION" >/dev/null 2>&1; then @@ -104,7 +114,10 @@ main() { fi # run the specified action - cmd_$SUBACTION "$@" + if [ $SUBACTION != "help" ] && [ $SUBCOMMAND != "init" ] ; then + init + fi + cmd_$SUBACTION "$@" } main "$@" diff --git a/git-flow-develop b/git-flow-develop new file mode 100755 index 000000000..90d80ae8a --- /dev/null +++ b/git-flow-develop @@ -0,0 +1,23 @@ +cmd_merge() { + + if has "$ORIGIN/$DEVELOP_BRANCH" $(git_remote_branches); then + git_do fetch -q "$ORIGIN" "$BRANCH" + git_do fetch -q "$ORIGIN" "$DEVELOP_BRANCH" + git_do push "$ORIGIN" "$DEVELOP_BRANCH" + fi + if has "$ORIGIN/$DEVELOP_BRANCH" $(git_remote_branches); then + require_branches_equal "$DEVELOP_BRANCH" "$ORIGIN/$DEVELOP_BRANCH" + fi + + + git_do checkout "$MASTER_BRANCH" + git_do merge --squash "$DEVELOP_BRANCH" + git_do commit + git_do merge "$DEVELOP_BRANCH" +} + +init() { + require_git_repo + require_gitflow_initialized + gitflow_load_settings +} \ No newline at end of file diff --git a/git-flow-feature b/git-flow-feature index 226730a9b..55198ad82 100644 --- a/git-flow-feature +++ b/git-flow-feature @@ -36,21 +36,23 @@ # policies, either expressed or implied, of Vincent Driessen. # -require_git_repo -require_gitflow_initialized -gitflow_load_settings -PREFIX=$(git config --get gitflow.prefix.feature) +init() { + require_git_repo + require_gitflow_initialized + gitflow_load_settings + PREFIX=$(git config --get gitflow.prefix.feature) +} usage() { echo "usage: git flow feature [list] [-v]" echo " git flow feature start [-F] []" - echo " git flow feature finish [-rFk] " + echo " git flow feature finish [-rFkDS] []" echo " git flow feature publish " echo " git flow feature track " echo " git flow feature diff []" echo " git flow feature rebase [-i] []" echo " git flow feature checkout []" - echo " git flow feature pull []" + echo " git flow feature pull [-r] []" } cmd_default() { @@ -202,7 +204,7 @@ cmd_start() { # update the local repo with remote changes, if asked if flag fetch; then - git fetch -q "$ORIGIN" "$DEVELOP_BRANCH" + git_do fetch -q "$ORIGIN" "$DEVELOP_BRANCH" fi # if the origin branch counterpart exists, assert that the local branch @@ -212,7 +214,7 @@ cmd_start() { fi # create branch - if ! git checkout -b "$BRANCH" "$BASE"; then + if ! git_do checkout -b "$BRANCH" "$BASE"; then die "Could not create feature branch '$BRANCH'" fi @@ -231,8 +233,10 @@ cmd_finish() { DEFINE_boolean fetch false "fetch from $ORIGIN before performing finish" F DEFINE_boolean rebase false "rebase instead of merge" r DEFINE_boolean keep false "keep branch after performing finish" k + DEFINE_boolean force_delete false "force delete feature branch after finish" D + DEFINE_boolean squash false "squash feature during merge" S parse_args "$@" - expand_nameprefix_arg + expand_nameprefix_arg_or_current # sanity checks require_branch "$BRANCH" @@ -281,16 +285,17 @@ cmd_finish() { require_clean_working_tree # update local repo with remote changes first, if asked - if has "$ORIGIN/$BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$BRANCH" $(git_remote_branches); then if flag fetch; then - git fetch -q "$ORIGIN" "$BRANCH" + git_do fetch -q "$ORIGIN" "$BRANCH" + git_do fetch -q "$ORIGIN" "$DEVELOP_BRANCH" fi fi - if has "$ORIGIN/$BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$BRANCH" $(git_remote_branches); then require_branches_equal "$BRANCH" "$ORIGIN/$BRANCH" fi - if has "$ORIGIN/$DEVELOP_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$DEVELOP_BRANCH" $(git_remote_branches); then require_branches_equal "$DEVELOP_BRANCH" "$ORIGIN/$DEVELOP_BRANCH" fi @@ -306,11 +311,17 @@ cmd_finish() { fi # merge into BASE - git checkout "$DEVELOP_BRANCH" + git_do checkout "$DEVELOP_BRANCH" if [ "$(git rev-list -n2 "$DEVELOP_BRANCH..$BRANCH" | wc -l)" -eq 1 ]; then - git merge --ff "$BRANCH" + git_do merge --ff "$BRANCH" else - git merge --no-ff "$BRANCH" + if noflag squash; then + git_do merge --no-ff "$BRANCH" + else + git_do merge --squash "$BRANCH" + git_do commit + git_do merge "$BRANCH" + fi fi if [ $? -ne 0 ]; then @@ -340,12 +351,16 @@ helper_finish_cleanup() { # delete branch if flag fetch; then - git push "$ORIGIN" ":refs/heads/$BRANCH" + git_do push "$ORIGIN" ":refs/heads/$BRANCH" fi if noflag keep; then - git branch -d "$BRANCH" + if flag force_delete; then + git_do branch -D "$BRANCH" + else + git_do branch -d "$BRANCH" + fi fi echo @@ -368,17 +383,17 @@ cmd_publish() { # sanity checks require_clean_working_tree require_branch "$BRANCH" - git fetch -q "$ORIGIN" + git_do fetch -q "$ORIGIN" require_branch_absent "$ORIGIN/$BRANCH" # create remote branch - git push "$ORIGIN" "$BRANCH:refs/heads/$BRANCH" - git fetch -q "$ORIGIN" + git_do push "$ORIGIN" "$BRANCH:refs/heads/$BRANCH" + git_do fetch -q "$ORIGIN" # configure remote tracking - git config "branch.$BRANCH.remote" "$ORIGIN" - git config "branch.$BRANCH.merge" "refs/heads/$BRANCH" - git checkout "$BRANCH" + git_do config "branch.$BRANCH.remote" "$ORIGIN" + git_do config "branch.$BRANCH.merge" "refs/heads/$BRANCH" + git_do checkout "$BRANCH" echo echo "Summary of actions:" @@ -395,11 +410,11 @@ cmd_track() { # sanity checks require_clean_working_tree require_branch_absent "$BRANCH" - git fetch -q "$ORIGIN" + git_do fetch -q "$ORIGIN" require_branch "$ORIGIN/$BRANCH" # create tracking branch - git checkout -b "$BRANCH" "$ORIGIN/$BRANCH" + git_do checkout -b "$BRANCH" "$ORIGIN/$BRANCH" echo echo "Summary of actions:" @@ -430,7 +445,7 @@ cmd_checkout() { if [ "$NAME" != "" ]; then expand_nameprefix_arg - git checkout "$BRANCH" + git_do checkout "$BRANCH" else die "Name a feature branch explicitly." fi @@ -449,12 +464,12 @@ cmd_rebase() { require_clean_working_tree require_branch "$BRANCH" - git checkout -q "$BRANCH" + git_do checkout -q "$BRANCH" local OPTS= if flag interactive; then OPTS="$OPTS -i" fi - git rebase $OPTS "$DEVELOP_BRANCH" + git_do rebase $OPTS "$DEVELOP_BRANCH" } avoid_accidental_cross_branch_action() { @@ -469,6 +484,7 @@ avoid_accidental_cross_branch_action() { cmd_pull() { #DEFINE_string prefix false 'alternative remote feature branch name prefix' p + DEFINE_boolean rebase false "pull with rebase" r parse_remote_name "$@" if [ -z "$REMOTE" ]; then @@ -494,13 +510,21 @@ cmd_pull() { # we already have a local branch called like this, so simply pull the # remote changes in - git pull -q "$REMOTE" "$BRANCH" || die "Failed to pull from remote '$REMOTE'." + if flag rebase; then + if ! git_do pull --rebase -q "$REMOTE" "$BRANCH"; then + warn "Pull was aborted. There might be conflicts during rebase or '$REMOTE' might be inaccessible." + exit 1 + fi + else + git_do pull -q "$REMOTE" "$BRANCH" || die "Failed to pull from remote '$REMOTE'." + fi + echo "Pulled $REMOTE's changes into $BRANCH." else # setup the local branch clone for the first time - git fetch -q "$REMOTE" "$BRANCH" || die "Fetch failed." # stores in FETCH_HEAD - git branch --no-track "$BRANCH" FETCH_HEAD || die "Branch failed." - git checkout -q "$BRANCH" || die "Checking out new local branch failed." + git_do fetch -q "$REMOTE" "$BRANCH" || die "Fetch failed." # stores in FETCH_HEAD + git_do branch --no-track "$BRANCH" FETCH_HEAD || die "Branch failed." + git_do checkout -q "$BRANCH" || die "Checking out new local branch failed." echo "Created local branch $BRANCH based on $REMOTE's $BRANCH." fi } diff --git a/git-flow-hotfix b/git-flow-hotfix index 5660131bf..ba485f6fe 100644 --- a/git-flow-hotfix +++ b/git-flow-hotfix @@ -36,16 +36,20 @@ # policies, either expressed or implied, of Vincent Driessen. # -require_git_repo -require_gitflow_initialized -gitflow_load_settings -VERSION_PREFIX=$(eval "echo `git config --get gitflow.prefix.versiontag`") -PREFIX=$(git config --get gitflow.prefix.hotfix) +init() { + require_git_repo + require_gitflow_initialized + gitflow_load_settings + VERSION_PREFIX=$(eval "echo `git config --get gitflow.prefix.versiontag`") + PREFIX=$(git config --get gitflow.prefix.hotfix) +} usage() { echo "usage: git flow hotfix [list] [-v]" echo " git flow hotfix start [-F] []" echo " git flow hotfix finish [-Fsumpk] " + echo " git flow hotfix publish " + echo " git flow hotfix track " } cmd_default() { @@ -165,14 +169,14 @@ cmd_start() { require_branch_absent "$BRANCH" require_tag_absent "$VERSION_PREFIX$VERSION" if flag fetch; then - git fetch -q "$ORIGIN" "$MASTER_BRANCH" + git_do fetch -q "$ORIGIN" "$MASTER_BRANCH" fi - if has "$ORIGIN/$MASTER_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$MASTER_BRANCH" $(git_remote_branches); then require_branches_equal "$MASTER_BRANCH" "$ORIGIN/$MASTER_BRANCH" fi # create branch - git checkout -b "$BRANCH" "$BASE" + git_do checkout -b "$BRANCH" "$BASE" echo echo "Summary of actions:" @@ -188,11 +192,59 @@ cmd_start() { echo } +cmd_publish() { + parse_args "$@" + require_version_arg + + # sanity checks + require_clean_working_tree + require_branch "$BRANCH" + git_do fetch -q "$ORIGIN" + require_branch_absent "$ORIGIN/$BRANCH" + + # create remote branch + git_do push "$ORIGIN" "$BRANCH:refs/heads/$BRANCH" + git_do fetch -q "$ORIGIN" + + # configure remote tracking + git config "branch.$BRANCH.remote" "$ORIGIN" + git config "branch.$BRANCH.merge" "refs/heads/$BRANCH" + git_do checkout "$BRANCH" + + echo + echo "Summary of actions:" + echo "- A new remote branch '$BRANCH' was created" + echo "- The local branch '$BRANCH' was configured to track the remote branch" + echo "- You are now on branch '$BRANCH'" + echo +} + +cmd_track() { + parse_args "$@" + require_version_arg + + # sanity checks + require_clean_working_tree + require_branch_absent "$BRANCH" + git_do fetch -q "$ORIGIN" + require_branch "$ORIGIN/$BRANCH" + + # create tracking branch + git_do checkout -b "$BRANCH" "$ORIGIN/$BRANCH" + + echo + echo "Summary of actions:" + echo "- A new remote tracking branch '$BRANCH' was created" + echo "- You are now on branch '$BRANCH'" + echo +} + cmd_finish() { DEFINE_boolean fetch false "fetch from $ORIGIN before performing finish" F DEFINE_boolean sign false "sign the release tag cryptographically" s DEFINE_string signingkey "" "use the given GPG-key for the digital signature (implies -s)" u DEFINE_string message "" "use the given tag message" m + DEFINE_string messagefile "" "use the contents of the given file as tag message" f DEFINE_boolean push false "push to $ORIGIN after performing finish" p DEFINE_boolean keep false "keep branch after performing finish" k DEFINE_boolean notag false "don't tag this release" n @@ -208,15 +260,15 @@ cmd_finish() { require_branch "$BRANCH" require_clean_working_tree if flag fetch; then - git fetch -q "$ORIGIN" "$MASTER_BRANCH" || \ + git_do fetch -q "$ORIGIN" "$MASTER_BRANCH" || \ die "Could not fetch $MASTER_BRANCH from $ORIGIN." - git fetch -q "$ORIGIN" "$DEVELOP_BRANCH" || \ + git_do fetch -q "$ORIGIN" "$DEVELOP_BRANCH" || \ die "Could not fetch $DEVELOP_BRANCH from $ORIGIN." fi - if has "$ORIGIN/$MASTER_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$MASTER_BRANCH" $(git_remote_branches); then require_branches_equal "$MASTER_BRANCH" "$ORIGIN/$MASTER_BRANCH" fi - if has "$ORIGIN/$DEVELOP_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$DEVELOP_BRANCH" $(git_remote_branches); then require_branches_equal "$DEVELOP_BRANCH" "$ORIGIN/$DEVELOP_BRANCH" fi @@ -224,9 +276,9 @@ cmd_finish() { # in case a previous attempt to finish this release branch has failed, # but the merge into master was successful, we skip it now if ! git_is_branch_merged_into "$BRANCH" "$MASTER_BRANCH"; then - git checkout "$MASTER_BRANCH" || \ + git_do checkout "$MASTER_BRANCH" || \ die "Could not check out $MASTER_BRANCH." - git merge --no-ff "$BRANCH" || \ + git_do merge --no-ff "$BRANCH" || \ die "There were merge conflicts." # TODO: What do we do now? fi @@ -241,7 +293,8 @@ cmd_finish() { flag sign && opts="$opts -s" [ "$FLAGS_signingkey" != "" ] && opts="$opts -u '$FLAGS_signingkey'" [ "$FLAGS_message" != "" ] && opts="$opts -m '$FLAGS_message'" - git tag $opts "$VERSION_PREFIX$VERSION" || \ + [ "$FLAGS_messagefile" != "" ] && opts="$opts -F '$FLAGS_messagefile'" + eval git_do tag $opts "$VERSION_PREFIX$VERSION" "$BRANCH" || \ die "Tagging failed. Please run finish again to retry." fi fi @@ -250,28 +303,28 @@ cmd_finish() { # in case a previous attempt to finish this release branch has failed, # but the merge into develop was successful, we skip it now if ! git_is_branch_merged_into "$BRANCH" "$DEVELOP_BRANCH"; then - git checkout "$DEVELOP_BRANCH" || \ + git_do checkout "$DEVELOP_BRANCH" || \ die "Could not check out $DEVELOP_BRANCH." # TODO: Actually, accounting for 'git describe' pays, so we should # ideally git merge --no-ff $tagname here, instead! - git merge --no-ff "$BRANCH" || \ + git_do merge --no-ff "$BRANCH" || \ die "There were merge conflicts." # TODO: What do we do now? fi # delete branch if noflag keep; then - git branch -d "$BRANCH" + git_do branch -d "$BRANCH" fi if flag push; then - git push "$ORIGIN" "$DEVELOP_BRANCH" || \ + git_do push "$ORIGIN" "$DEVELOP_BRANCH" || \ die "Could not push to $DEVELOP_BRANCH from $ORIGIN." - git push "$ORIGIN" "$MASTER_BRANCH" || \ + git_do push "$ORIGIN" "$MASTER_BRANCH" || \ die "Could not push to $MASTER_BRANCH from $ORIGIN." if noflag notag; then - git push --tags "$ORIGIN" || \ + git_do push --tags "$ORIGIN" || \ die "Could not push tags to $ORIGIN." fi fi diff --git a/git-flow-init b/git-flow-init index 57ab2441e..5b4e7e807 100644 --- a/git-flow-init +++ b/git-flow-init @@ -53,7 +53,7 @@ cmd_default() { parse_args "$@" if ! git rev-parse --git-dir >/dev/null 2>&1; then - git init + git_do init else # assure that we are not working in a repo with local changes git_repo_is_headless || require_clean_working_tree @@ -117,12 +117,18 @@ cmd_default() { # check existence in case of an already existing repo if [ "$should_check_existence" = "YES" ]; then - git_local_branch_exists "$master_branch" || \ + # if no local branch exists and a remote branch of the same + # name exists, checkout that branch and use it for master + if ! git_local_branch_exists "$master_branch" && \ + git_remote_branch_exists "origin/$master_branch"; then + git_do branch "$master_branch" "origin/$master_branch" >/dev/null 2>&1 + elif ! git_local_branch_exists "$master_branch"; then die "Local branch '$master_branch' does not exist." + fi fi # store the name of the master branch - git config gitflow.branch.master "$master_branch" + git_do config gitflow.branch.master "$master_branch" fi # add a develop branch if no such branch exists yet @@ -147,11 +153,17 @@ cmd_default() { default_suggestion= for guess in $(git config --get gitflow.branch.develop) \ 'develop' 'int' 'integration' 'master'; do - if git_local_branch_exists "$guess"; then + if git_local_branch_exists "$guess" && [ "$guess" != "$master_branch" ]; then default_suggestion="$guess" break fi done + + if [ -z $default_suggestion ]; then + should_check_existence=NO + default_suggestion=$(git config --get gitflow.branch.develop || echo develop) + fi + fi printf "Branch name for \"next release\" development: [$default_suggestion] " @@ -173,7 +185,7 @@ cmd_default() { fi # store the name of the develop branch - git config gitflow.branch.develop "$develop_branch" + git_do config gitflow.branch.develop "$develop_branch" fi # Creation of HEAD @@ -182,8 +194,8 @@ cmd_default() { # it to be able to create new branches. local created_gitflow_branch=0 if ! git rev-parse --quiet --verify HEAD >/dev/null 2>&1; then - git symbolic-ref HEAD "refs/heads/$master_branch" - git commit --allow-empty --quiet -m "Initial commit" + git_do symbolic-ref HEAD "refs/heads/$master_branch" + git_do commit --allow-empty --quiet -m "Initial commit" created_gitflow_branch=1 fi @@ -200,7 +212,11 @@ cmd_default() { # default production branch and develop was "created". We should create # the develop branch now in that case (we base it on master, of course) if ! git_local_branch_exists "$develop_branch"; then - git branch --no-track "$develop_branch" "$master_branch" + if git_remote_branch_exists "origin/$develop_branch"; then + git_do branch "$develop_branch" "origin/$develop_branch" >/dev/null 2>&1 + else + git_do branch --no-track "$develop_branch" "$master_branch" + fi created_gitflow_branch=1 fi @@ -209,7 +225,7 @@ cmd_default() { # switch to develop branch if its newly created if [ $created_gitflow_branch -eq 1 ]; then - git checkout -q "$develop_branch" + git_do checkout -q "$develop_branch" fi # finally, ask the user for naming conventions (branch and tag prefixes) @@ -235,7 +251,7 @@ cmd_default() { printf "\n" fi [ "$answer" = "-" ] && prefix= || prefix=${answer:-$default_suggestion} - git config gitflow.prefix.feature "$prefix" + git_do config gitflow.prefix.feature "$prefix" fi # Release branches @@ -248,7 +264,7 @@ cmd_default() { printf "\n" fi [ "$answer" = "-" ] && prefix= || prefix=${answer:-$default_suggestion} - git config gitflow.prefix.release "$prefix" + git_do config gitflow.prefix.release "$prefix" fi @@ -262,7 +278,7 @@ cmd_default() { printf "\n" fi [ "$answer" = "-" ] && prefix= || prefix=${answer:-$default_suggestion} - git config gitflow.prefix.hotfix "$prefix" + git_do config gitflow.prefix.hotfix "$prefix" fi @@ -276,7 +292,7 @@ cmd_default() { printf "\n" fi [ "$answer" = "-" ] && prefix= || prefix=${answer:-$default_suggestion} - git config gitflow.prefix.support "$prefix" + git_do config gitflow.prefix.support "$prefix" fi @@ -290,7 +306,7 @@ cmd_default() { printf "\n" fi [ "$answer" = "-" ] && prefix= || prefix=${answer:-$default_suggestion} - git config gitflow.prefix.versiontag "$prefix" + git_do config gitflow.prefix.versiontag "$prefix" fi diff --git a/git-flow-release b/git-flow-release index 05815bcf0..cb95bd486 100644 --- a/git-flow-release +++ b/git-flow-release @@ -36,16 +36,18 @@ # policies, either expressed or implied, of Vincent Driessen. # -require_git_repo -require_gitflow_initialized -gitflow_load_settings -VERSION_PREFIX=$(eval "echo `git config --get gitflow.prefix.versiontag`") -PREFIX=$(git config --get gitflow.prefix.release) +init() { + require_git_repo + require_gitflow_initialized + gitflow_load_settings + VERSION_PREFIX=$(eval "echo `git config --get gitflow.prefix.versiontag`") + PREFIX=$(git config --get gitflow.prefix.release) +} usage() { echo "usage: git flow release [list] [-v]" - echo " git flow release start [-F] " - echo " git flow release finish [-Fsumpk] " + echo " git flow release start [-F] []" + echo " git flow release finish [-FsumpkS] " echo " git flow release publish " echo " git flow release track " } @@ -134,7 +136,7 @@ require_version_arg() { } require_base_is_on_develop() { - if ! git branch --no-color --contains "$BASE" 2>/dev/null \ + if ! git_do branch --no-color --contains "$BASE" 2>/dev/null \ | sed 's/[* ] //g' \ | grep -q "^$DEVELOP_BRANCH\$"; then die "fatal: Given base '$BASE' is not a valid commit on '$DEVELOP_BRANCH'." @@ -162,14 +164,14 @@ cmd_start() { require_branch_absent "$BRANCH" require_tag_absent "$VERSION_PREFIX$VERSION" if flag fetch; then - git fetch -q "$ORIGIN" "$DEVELOP_BRANCH" + git_do fetch -q "$ORIGIN" "$DEVELOP_BRANCH" fi - if has "$ORIGIN/$DEVELOP_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$DEVELOP_BRANCH" $(git_remote_branches); then require_branches_equal "$DEVELOP_BRANCH" "$ORIGIN/$DEVELOP_BRANCH" fi # create branch - git checkout -b "$BRANCH" "$BASE" + git_do checkout -b "$BRANCH" "$BASE" echo echo "Summary of actions:" @@ -190,9 +192,11 @@ cmd_finish() { DEFINE_boolean sign false "sign the release tag cryptographically" s DEFINE_string signingkey "" "use the given GPG-key for the digital signature (implies -s)" u DEFINE_string message "" "use the given tag message" m + DEFINE_string messagefile "" "use the contents of the given file as a tag message" f DEFINE_boolean push false "push to $ORIGIN after performing finish" p DEFINE_boolean keep false "keep branch after performing finish" k DEFINE_boolean notag false "don't tag this release" n + DEFINE_boolean squash false "squash release during merge" S parse_args "$@" require_version_arg @@ -206,15 +210,15 @@ cmd_finish() { require_branch "$BRANCH" require_clean_working_tree if flag fetch; then - git fetch -q "$ORIGIN" "$MASTER_BRANCH" || \ + git_do fetch -q "$ORIGIN" "$MASTER_BRANCH" || \ die "Could not fetch $MASTER_BRANCH from $ORIGIN." - git fetch -q "$ORIGIN" "$DEVELOP_BRANCH" || \ + git_do fetch -q "$ORIGIN" "$DEVELOP_BRANCH" || \ die "Could not fetch $DEVELOP_BRANCH from $ORIGIN." fi - if has "$ORIGIN/$MASTER_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$MASTER_BRANCH" $(git_remote_branches); then require_branches_equal "$MASTER_BRANCH" "$ORIGIN/$MASTER_BRANCH" fi - if has "$ORIGIN/$DEVELOP_BRANCH" "$(git_remote_branches)"; then + if has "$ORIGIN/$DEVELOP_BRANCH" $(git_remote_branches); then require_branches_equal "$DEVELOP_BRANCH" "$ORIGIN/$DEVELOP_BRANCH" fi @@ -222,11 +226,17 @@ cmd_finish() { # in case a previous attempt to finish this release branch has failed, # but the merge into master was successful, we skip it now if ! git_is_branch_merged_into "$BRANCH" "$MASTER_BRANCH"; then - git checkout "$MASTER_BRANCH" || \ + git_do checkout "$MASTER_BRANCH" || \ die "Could not check out $MASTER_BRANCH." - git merge --no-ff "$BRANCH" || \ - die "There were merge conflicts." - # TODO: What do we do now? + if noflag squash; then + git_do merge --no-ff "$BRANCH" || \ + die "There were merge conflicts." + # TODO: What do we do now? + else + git_do merge --squash "$BRANCH" || \ + die "There were merge conflicts." + git_do commit + fi fi if noflag notag; then @@ -239,7 +249,8 @@ cmd_finish() { flag sign && opts="$opts -s" [ "$FLAGS_signingkey" != "" ] && opts="$opts -u '$FLAGS_signingkey'" [ "$FLAGS_message" != "" ] && opts="$opts -m '$FLAGS_message'" - git tag $opts "$tagname" || \ + [ "$FLAGS_messagefile" != "" ] && opts="$opts -F '$FLAGS_messagefile'" + eval git_do tag $opts "$tagname" "$BRANCH" || \ die "Tagging failed. Please run finish again to retry." fi fi @@ -248,34 +259,41 @@ cmd_finish() { # in case a previous attempt to finish this release branch has failed, # but the merge into develop was successful, we skip it now if ! git_is_branch_merged_into "$BRANCH" "$DEVELOP_BRANCH"; then - git checkout "$DEVELOP_BRANCH" || \ + git_do checkout "$DEVELOP_BRANCH" || \ die "Could not check out $DEVELOP_BRANCH." # TODO: Actually, accounting for 'git describe' pays, so we should # ideally git merge --no-ff $tagname here, instead! - git merge --no-ff "$BRANCH" || \ - die "There were merge conflicts." - # TODO: What do we do now? + if noflag squash; then + git_do merge --no-ff "$BRANCH" || \ + die "There were merge conflicts." + # TODO: What do we do now? + else + git_do merge --squash "$BRANCH" || \ + die "There were merge conflicts." + # TODO: What do we do now? + git_do commit + fi fi # delete branch if noflag keep; then if [ "$BRANCH" = "$(git_current_branch)" ]; then - git checkout "$MASTER_BRANCH" + git_do checkout "$MASTER_BRANCH" fi - git branch -d "$BRANCH" + git_do branch -d "$BRANCH" fi if flag push; then - git push "$ORIGIN" "$DEVELOP_BRANCH" || \ + git_do push "$ORIGIN" "$DEVELOP_BRANCH" || \ die "Could not push to $DEVELOP_BRANCH from $ORIGIN." - git push "$ORIGIN" "$MASTER_BRANCH" || \ + git_do push "$ORIGIN" "$MASTER_BRANCH" || \ die "Could not push to $MASTER_BRANCH from $ORIGIN." if noflag notag; then - git push --tags "$ORIGIN" || \ + git_do push --tags "$ORIGIN" || \ die "Could not push tags to $ORIGIN." fi - git push "$ORIGIN" :"$BRANCH" || \ + git_do push "$ORIGIN" :"$BRANCH" || \ die "Could not delete the remote $BRANCH in $ORIGIN." fi @@ -306,17 +324,17 @@ cmd_publish() { # sanity checks require_clean_working_tree require_branch "$BRANCH" - git fetch -q "$ORIGIN" + git_do fetch -q "$ORIGIN" require_branch_absent "$ORIGIN/$BRANCH" # create remote branch - git push "$ORIGIN" "$BRANCH:refs/heads/$BRANCH" - git fetch -q "$ORIGIN" + git_do push "$ORIGIN" "$BRANCH:refs/heads/$BRANCH" + git_do fetch -q "$ORIGIN" # configure remote tracking - git config "branch.$BRANCH.remote" "$ORIGIN" - git config "branch.$BRANCH.merge" "refs/heads/$BRANCH" - git checkout "$BRANCH" + git_do config "branch.$BRANCH.remote" "$ORIGIN" + git_do config "branch.$BRANCH.merge" "refs/heads/$BRANCH" + git_do checkout "$BRANCH" echo echo "Summary of actions:" @@ -333,11 +351,11 @@ cmd_track() { # sanity checks require_clean_working_tree require_branch_absent "$BRANCH" - git fetch -q "$ORIGIN" + git_do fetch -q "$ORIGIN" require_branch "$ORIGIN/$BRANCH" # create tracking branch - git checkout -b "$BRANCH" "$ORIGIN/$BRANCH" + git_do checkout -b "$BRANCH" "$ORIGIN/$BRANCH" echo echo "Summary of actions:" diff --git a/git-flow-support b/git-flow-support index 605694dc9..cdbfc717c 100644 --- a/git-flow-support +++ b/git-flow-support @@ -36,11 +36,13 @@ # policies, either expressed or implied, of Vincent Driessen. # -require_git_repo -require_gitflow_initialized -gitflow_load_settings -VERSION_PREFIX=$(eval "echo `git config --get gitflow.prefix.versiontag`") -PREFIX=$(git config --get gitflow.prefix.support) +init() { + require_git_repo + require_gitflow_initialized + gitflow_load_settings + VERSION_PREFIX=$(eval "echo `git config --get gitflow.prefix.versiontag`") + PREFIX=$(git config --get gitflow.prefix.support) +} warn "note: The support subcommand is still very EXPERIMENTAL!" warn "note: DO NOT use it in a production situation." @@ -167,12 +169,12 @@ cmd_start() { # fetch remote changes if flag fetch; then - git fetch -q "$ORIGIN" "$BASE" + git_do fetch -q "$ORIGIN" "$BASE" fi require_branch_absent "$BRANCH" # create branch - git checkout -b "$BRANCH" "$BASE" + git_do checkout -b "$BRANCH" "$BASE" echo echo "Summary of actions:" diff --git a/git-flow-version b/git-flow-version index 51fd67136..8c314996c 100644 --- a/git-flow-version +++ b/git-flow-version @@ -36,7 +36,7 @@ # policies, either expressed or implied, of Vincent Driessen. # -GITFLOW_VERSION=0.4.1 +GITFLOW_VERSION=0.4.2-pre usage() { echo "usage: git flow version" diff --git a/gitflow-common b/gitflow-common index 75eb210ee..332740533 100644 --- a/gitflow-common +++ b/gitflow-common @@ -45,7 +45,7 @@ warn() { echo "$@" >&2; } die() { warn "$@"; exit 1; } escape() { - echo "$1" | sed 's/\([\.\+\$\*]\)/\\\1/g' + echo "$1" | sed 's/\([\.\$\*]\)/\\\1/g' } # set logic @@ -70,6 +70,14 @@ noflag() { local FLAG; eval FLAG='$FLAGS_'$1; [ $FLAG -ne $FLAGS_TRUE ]; } # Git specific common functionality # +git_do() { + # equivalent to git, used to indicate actions that make modifications + if flag show_commands; then + echo "git $@" >&2 + fi + git "$@" +} + git_local_branches() { git branch --no-color | sed 's/^[* ] //'; } git_remote_branches() { git branch -r --no-color | sed 's/^[* ] //'; } git_all_branches() { ( git branch --no-color; git branch -r --no-color) | sed 's/^[* ] //'; } @@ -97,6 +105,10 @@ git_local_branch_exists() { has $1 $(git_local_branches) } +git_remote_branch_exists() { + has $1 $(git_remote_branches) +} + git_branch_exists() { has $1 $(git_all_branches) } @@ -181,7 +193,7 @@ gitflow_is_initialized() { # loading settings that can be overridden using git config gitflow_load_settings() { - export DOT_GIT_DIR=$(git rev-parse --git-dir >/dev/null 2>&1) + export DOT_GIT_DIR=$(git rev-parse --git-dir 2>/dev/null) export MASTER_BRANCH=$(git config --get gitflow.branch.master) export DEVELOP_BRANCH=$(git config --get gitflow.branch.develop) export ORIGIN=$(git config --get gitflow.origin || echo origin) @@ -288,9 +300,11 @@ require_branch_absent() { } require_tag_absent() { - if has $1 $(git_all_tags); then - die "Tag '$1' already exists. Pick another name." - fi + for tag in $(git_all_tags); do + if [ "$1" = "$tag" ]; then + die "Tag '$1' already exists. Pick another name." + fi + done } require_branches_equal() { diff --git a/gitflow-shFlags b/gitflow-shFlags deleted file mode 120000 index 7b736c183..000000000 --- a/gitflow-shFlags +++ /dev/null @@ -1 +0,0 @@ -shFlags/src/shflags \ No newline at end of file diff --git a/gitflow-shFlags b/gitflow-shFlags new file mode 100644 index 000000000..f69928ef9 --- /dev/null +++ b/gitflow-shFlags @@ -0,0 +1,1009 @@ +# $Id$ +# vim:et:ft=sh:sts=2:sw=2 +# +# Copyright 2008 Kate Ward. All Rights Reserved. +# Released under the LGPL (GNU Lesser General Public License) +# +# shFlags -- Advanced command-line flag library for Unix shell scripts. +# http://code.google.com/p/shflags/ +# +# Author: kate.ward@forestent.com (Kate Ward) +# +# This module implements something like the google-gflags library available +# from http://code.google.com/p/google-gflags/. +# +# FLAG TYPES: This is a list of the DEFINE_*'s that you can do. All flags take +# a name, default value, help-string, and optional 'short' name (one-letter +# name). Some flags have other arguments, which are described with the flag. +# +# DEFINE_string: takes any input, and intreprets it as a string. +# +# DEFINE_boolean: typically does not take any argument: say --myflag to set +# FLAGS_myflag to true, or --nomyflag to set FLAGS_myflag to false. +# Alternately, you can say +# --myflag=true or --myflag=t or --myflag=0 or +# --myflag=false or --myflag=f or --myflag=1 +# Passing an option has the same affect as passing the option once. +# +# DEFINE_float: takes an input and intreprets it as a floating point number. As +# shell does not support floats per-se, the input is merely validated as +# being a valid floating point value. +# +# DEFINE_integer: takes an input and intreprets it as an integer. +# +# SPECIAL FLAGS: There are a few flags that have special meaning: +# --help (or -?) prints a list of all the flags in a human-readable fashion +# --flagfile=foo read flags from foo. (not implemented yet) +# -- as in getopt(), terminates flag-processing +# +# EXAMPLE USAGE: +# +# -- begin hello.sh -- +# #! /bin/sh +# . ./shflags +# DEFINE_string name 'world' "somebody's name" n +# FLAGS "$@" || exit $? +# eval set -- "${FLAGS_ARGV}" +# echo "Hello, ${FLAGS_name}." +# -- end hello.sh -- +# +# $ ./hello.sh -n Kate +# Hello, Kate. +# +# NOTE: Not all systems include a getopt version that supports long flags. On +# these systems, only short flags are recognized. + +#============================================================================== +# shFlags +# +# Shared attributes: +# flags_error: last error message +# flags_return: last return value +# +# __flags_longNames: list of long names for all flags +# __flags_shortNames: list of short names for all flags +# __flags_boolNames: list of boolean flag names +# +# __flags_opts: options parsed by getopt +# +# Per-flag attributes: +# FLAGS_: contains value of flag named 'flag_name' +# __flags__default: the default flag value +# __flags__help: the flag help string +# __flags__short: the flag short name +# __flags__type: the flag type +# +# Notes: +# - lists of strings are space separated, and a null value is the '~' char. + +# return if FLAGS already loaded +[ -n "${FLAGS_VERSION:-}" ] && return 0 +FLAGS_VERSION='1.0.3' + +# return values +FLAGS_TRUE=0 +FLAGS_FALSE=1 +FLAGS_ERROR=2 + +# reserved flag names +FLAGS_RESERVED='ARGC ARGV ERROR FALSE HELP PARENT RESERVED TRUE VERSION' + +_flags_debug() { echo "flags:DEBUG $@" >&2; } +_flags_warn() { echo "flags:WARN $@" >&2; } +_flags_error() { echo "flags:ERROR $@" >&2; } +_flags_fatal() { echo "flags:FATAL $@" >&2; } + +# specific shell checks +if [ -n "${ZSH_VERSION:-}" ]; then + setopt |grep "^shwordsplit$" >/dev/null + if [ $? -ne ${FLAGS_TRUE} ]; then + _flags_fatal 'zsh shwordsplit option is required for proper zsh operation' + exit ${FLAGS_ERROR} + fi + if [ -z "${FLAGS_PARENT:-}" ]; then + _flags_fatal "zsh does not pass \$0 through properly. please declare' \ +\"FLAGS_PARENT=\$0\" before calling shFlags" + exit ${FLAGS_ERROR} + fi +fi + +# +# constants +# + +# getopt version +__FLAGS_GETOPT_VERS_STD=0 +__FLAGS_GETOPT_VERS_ENH=1 +__FLAGS_GETOPT_VERS_BSD=2 + +getopt >/dev/null 2>&1 +case $? in + 0) __FLAGS_GETOPT_VERS=${__FLAGS_GETOPT_VERS_STD} ;; # bsd getopt + 2) + # TODO(kward): look into '-T' option to test the internal getopt() version + if [ "`getopt --version`" = '-- ' ]; then + __FLAGS_GETOPT_VERS=${__FLAGS_GETOPT_VERS_STD} + else + __FLAGS_GETOPT_VERS=${__FLAGS_GETOPT_VERS_ENH} + fi + ;; + *) + _flags_fatal 'unable to determine getopt version' + exit ${FLAGS_ERROR} + ;; +esac + +# getopt optstring lengths +__FLAGS_OPTSTR_SHORT=0 +__FLAGS_OPTSTR_LONG=1 + +__FLAGS_NULL='~' + +# flag info strings +__FLAGS_INFO_DEFAULT='default' +__FLAGS_INFO_HELP='help' +__FLAGS_INFO_SHORT='short' +__FLAGS_INFO_TYPE='type' + +# flag lengths +__FLAGS_LEN_SHORT=0 +__FLAGS_LEN_LONG=1 + +# flag types +__FLAGS_TYPE_NONE=0 +__FLAGS_TYPE_BOOLEAN=1 +__FLAGS_TYPE_FLOAT=2 +__FLAGS_TYPE_INTEGER=3 +__FLAGS_TYPE_STRING=4 + +# set the constants readonly +__flags_constants=`set |awk -F= '/^FLAGS_/ || /^__FLAGS_/ {print $1}'` +for __flags_const in ${__flags_constants}; do + # skip certain flags + case ${__flags_const} in + FLAGS_HELP) continue ;; + FLAGS_PARENT) continue ;; + esac + # set flag readonly + if [ -z "${ZSH_VERSION:-}" ]; then + readonly ${__flags_const} + else # handle zsh + case ${ZSH_VERSION} in + [123].*) readonly ${__flags_const} ;; + *) readonly -g ${__flags_const} ;; # declare readonly constants globally + esac + fi +done +unset __flags_const __flags_constants + +# +# internal variables +# + +__flags_boolNames=' ' # space separated list of boolean flag names +__flags_longNames=' ' # space separated list of long flag names +__flags_shortNames=' ' # space separated list of short flag names + +__flags_columns='' # screen width in columns +__flags_opts='' # temporary storage for parsed getopt flags + +#------------------------------------------------------------------------------ +# private functions +# + +# Define a flag. +# +# Calling this function will define the following info variables for the +# specified flag: +# FLAGS_flagname - the name for this flag (based upon the long flag name) +# __flags__default - the default value +# __flags_flagname_help - the help string +# __flags_flagname_short - the single letter alias +# __flags_flagname_type - the type of flag (one of __FLAGS_TYPE_*) +# +# Args: +# _flags__type: integer: internal type of flag (__FLAGS_TYPE_*) +# _flags__name: string: long flag name +# _flags__default: default flag value +# _flags__help: string: help string +# _flags__short: string: (optional) short flag name +# Returns: +# integer: success of operation, or error +_flags_define() +{ + if [ $# -lt 4 ]; then + flags_error='DEFINE error: too few arguments' + flags_return=${FLAGS_ERROR} + _flags_error "${flags_error}" + return ${flags_return} + fi + + _flags_type_=$1 + _flags_name_=$2 + _flags_default_=$3 + _flags_help_=$4 + _flags_short_=${5:-${__FLAGS_NULL}} + + _flags_return_=${FLAGS_TRUE} + + # TODO(kward): check for validity of the flag name (e.g. dashes) + + # check whether the flag name is reserved + echo " ${FLAGS_RESERVED} " |grep " ${_flags_name_} " >/dev/null + if [ $? -eq 0 ]; then + flags_error="flag name (${_flags_name_}) is reserved" + _flags_return_=${FLAGS_ERROR} + fi + + # require short option for getopt that don't support long options + if [ ${_flags_return_} -eq ${FLAGS_TRUE} \ + -a ${__FLAGS_GETOPT_VERS} -ne ${__FLAGS_GETOPT_VERS_ENH} \ + -a "${_flags_short_}" = "${__FLAGS_NULL}" ] + then + flags_error="short flag required for (${_flags_name_}) on this platform" + _flags_return_=${FLAGS_ERROR} + fi + + # check for existing long name definition + if [ ${_flags_return_} -eq ${FLAGS_TRUE} ]; then + if _flags_itemInList "${_flags_name_}" \ + ${__flags_longNames} ${__flags_boolNames} + then + flags_error="flag name ([no]${_flags_name_}) already defined" + _flags_warn "${flags_error}" + _flags_return_=${FLAGS_FALSE} + fi + fi + + # check for existing short name definition + if [ ${_flags_return_} -eq ${FLAGS_TRUE} \ + -a "${_flags_short_}" != "${__FLAGS_NULL}" ] + then + if _flags_itemInList "${_flags_short_}" ${__flags_shortNames}; then + flags_error="flag short name (${_flags_short_}) already defined" + _flags_warn "${flags_error}" + _flags_return_=${FLAGS_FALSE} + fi + fi + + # handle default value. note, on several occasions the 'if' portion of an + # if/then/else contains just a ':' which does nothing. a binary reversal via + # '!' is not done because it does not work on all shells. + if [ ${_flags_return_} -eq ${FLAGS_TRUE} ]; then + case ${_flags_type_} in + ${__FLAGS_TYPE_BOOLEAN}) + if _flags_validateBoolean "${_flags_default_}"; then + case ${_flags_default_} in + true|t|0) _flags_default_=${FLAGS_TRUE} ;; + false|f|1) _flags_default_=${FLAGS_FALSE} ;; + esac + else + flags_error="invalid default flag value '${_flags_default_}'" + _flags_return_=${FLAGS_ERROR} + fi + ;; + + ${__FLAGS_TYPE_FLOAT}) + if _flags_validateFloat "${_flags_default_}"; then + : + else + flags_error="invalid default flag value '${_flags_default_}'" + _flags_return_=${FLAGS_ERROR} + fi + ;; + + ${__FLAGS_TYPE_INTEGER}) + if _flags_validateInteger "${_flags_default_}"; then + : + else + flags_error="invalid default flag value '${_flags_default_}'" + _flags_return_=${FLAGS_ERROR} + fi + ;; + + ${__FLAGS_TYPE_STRING}) ;; # everything in shell is a valid string + + *) + flags_error="unrecognized flag type '${_flags_type_}'" + _flags_return_=${FLAGS_ERROR} + ;; + esac + fi + + if [ ${_flags_return_} -eq ${FLAGS_TRUE} ]; then + # store flag information + eval "FLAGS_${_flags_name_}='${_flags_default_}'" + eval "__flags_${_flags_name_}_${__FLAGS_INFO_TYPE}=${_flags_type_}" + eval "__flags_${_flags_name_}_${__FLAGS_INFO_DEFAULT}=\ +\"${_flags_default_}\"" + eval "__flags_${_flags_name_}_${__FLAGS_INFO_HELP}=\"${_flags_help_}\"" + eval "__flags_${_flags_name_}_${__FLAGS_INFO_SHORT}='${_flags_short_}'" + + # append flag name(s) to list of names + __flags_longNames="${__flags_longNames}${_flags_name_} " + __flags_shortNames="${__flags_shortNames}${_flags_short_} " + [ ${_flags_type_} -eq ${__FLAGS_TYPE_BOOLEAN} ] && \ + __flags_boolNames="${__flags_boolNames}no${_flags_name_} " + fi + + flags_return=${_flags_return_} + unset _flags_default_ _flags_help_ _flags_name_ _flags_return_ _flags_short_ \ + _flags_type_ + [ ${flags_return} -eq ${FLAGS_ERROR} ] && _flags_error "${flags_error}" + return ${flags_return} +} + +# Return valid getopt options using currently defined list of long options. +# +# This function builds a proper getopt option string for short (and long) +# options, using the current list of long options for reference. +# +# Args: +# _flags_optStr: integer: option string type (__FLAGS_OPTSTR_*) +# Output: +# string: generated option string for getopt +# Returns: +# boolean: success of operation (always returns True) +_flags_genOptStr() +{ + _flags_optStrType_=$1 + + _flags_opts_='' + + for _flags_flag_ in ${__flags_longNames}; do + _flags_type_=`_flags_getFlagInfo ${_flags_flag_} ${__FLAGS_INFO_TYPE}` + case ${_flags_optStrType_} in + ${__FLAGS_OPTSTR_SHORT}) + _flags_shortName_=`_flags_getFlagInfo \ + ${_flags_flag_} ${__FLAGS_INFO_SHORT}` + if [ "${_flags_shortName_}" != "${__FLAGS_NULL}" ]; then + _flags_opts_="${_flags_opts_}${_flags_shortName_}" + # getopt needs a trailing ':' to indicate a required argument + [ ${_flags_type_} -ne ${__FLAGS_TYPE_BOOLEAN} ] && \ + _flags_opts_="${_flags_opts_}:" + fi + ;; + + ${__FLAGS_OPTSTR_LONG}) + _flags_opts_="${_flags_opts_:+${_flags_opts_},}${_flags_flag_}" + # getopt needs a trailing ':' to indicate a required argument + [ ${_flags_type_} -ne ${__FLAGS_TYPE_BOOLEAN} ] && \ + _flags_opts_="${_flags_opts_}:" + ;; + esac + done + + echo "${_flags_opts_}" + unset _flags_flag_ _flags_opts_ _flags_optStrType_ _flags_shortName_ \ + _flags_type_ + return ${FLAGS_TRUE} +} + +# Returns flag details based on a flag name and flag info. +# +# Args: +# string: long flag name +# string: flag info (see the _flags_define function for valid info types) +# Output: +# string: value of dereferenced flag variable +# Returns: +# integer: one of FLAGS_{TRUE|FALSE|ERROR} +_flags_getFlagInfo() +{ + _flags_name_=$1 + _flags_info_=$2 + + _flags_nameVar_="__flags_${_flags_name_}_${_flags_info_}" + _flags_strToEval_="_flags_value_=\"\${${_flags_nameVar_}:-}\"" + eval "${_flags_strToEval_}" + if [ -n "${_flags_value_}" ]; then + flags_return=${FLAGS_TRUE} + else + # see if the _flags_name_ variable is a string as strings can be empty... + # note: the DRY principle would say to have this function call itself for + # the next three lines, but doing so results in an infinite loop as an + # invalid _flags_name_ will also not have the associated _type variable. + # Because it doesn't (it will evaluate to an empty string) the logic will + # try to find the _type variable of the _type variable, and so on. Not so + # good ;-) + _flags_typeVar_="__flags_${_flags_name_}_${__FLAGS_INFO_TYPE}" + _flags_strToEval_="_flags_type_=\"\${${_flags_typeVar_}:-}\"" + eval "${_flags_strToEval_}" + if [ "${_flags_type_}" = "${__FLAGS_TYPE_STRING}" ]; then + flags_return=${FLAGS_TRUE} + else + flags_return=${FLAGS_ERROR} + flags_error="invalid flag name (${_flags_nameVar_})" + fi + fi + + echo "${_flags_value_}" + unset _flags_info_ _flags_name_ _flags_strToEval_ _flags_type_ _flags_value_ \ + _flags_nameVar_ _flags_typeVar_ + [ ${flags_return} -eq ${FLAGS_ERROR} ] && _flags_error "${flags_error}" + return ${flags_return} +} + +# check for presense of item in a list. passed a string (e.g. 'abc'), this +# function will determine if the string is present in the list of strings (e.g. +# ' foo bar abc '). +# +# Args: +# _flags__str: string: string to search for in a list of strings +# unnamed: list: list of strings +# Returns: +# boolean: true if item is in the list +_flags_itemInList() +{ + _flags_str_=$1 + shift + + echo " ${*:-} " |grep " ${_flags_str_} " >/dev/null + if [ $? -eq 0 ]; then + flags_return=${FLAGS_TRUE} + else + flags_return=${FLAGS_FALSE} + fi + + unset _flags_str_ + return ${flags_return} +} + +# Returns the width of the current screen. +# +# Output: +# integer: width in columns of the current screen. +_flags_columns() +{ + if [ -z "${__flags_columns}" ]; then + # determine the value and store it + if eval stty size >/dev/null 2>&1; then + # stty size worked :-) + set -- `stty size` + __flags_columns=$2 + elif eval tput cols >/dev/null 2>&1; then + set -- `tput cols` + __flags_columns=$1 + else + __flags_columns=80 # default terminal width + fi + fi + echo ${__flags_columns} +} + +# Validate a boolean. +# +# Args: +# _flags__bool: boolean: value to validate +# Returns: +# bool: true if the value is a valid boolean +_flags_validateBoolean() +{ + _flags_bool_=$1 + + flags_return=${FLAGS_TRUE} + case "${_flags_bool_}" in + true|t|0) ;; + false|f|1) ;; + *) flags_return=${FLAGS_FALSE} ;; + esac + + unset _flags_bool_ + return ${flags_return} +} + +# Validate a float. +# +# Args: +# _flags__float: float: value to validate +# Returns: +# bool: true if the value is a valid float +_flags_validateFloat() +{ + _flags_float_=$1 + + if _flags_validateInteger ${_flags_float_}; then + flags_return=${FLAGS_TRUE} + else + flags_return=${FLAGS_TRUE} + case ${_flags_float_} in + -*) # negative floats + _flags_test_=`expr "${_flags_float_}" : '\(-[0-9][0-9]*\.[0-9][0-9]*\)'` + ;; + *) # positive floats + _flags_test_=`expr "${_flags_float_}" : '\([0-9][0-9]*\.[0-9][0-9]*\)'` + ;; + esac + [ "${_flags_test_}" != "${_flags_float_}" ] && flags_return=${FLAGS_FALSE} + fi + + unset _flags_float_ _flags_test_ + return ${flags_return} +} + +# Validate an integer. +# +# Args: +# _flags__integer: interger: value to validate +# Returns: +# bool: true if the value is a valid integer +_flags_validateInteger() +{ + _flags_int_=$1 + + flags_return=${FLAGS_TRUE} + case ${_flags_int_} in + -*) # negative ints + _flags_test_=`expr "${_flags_int_}" : '\(-[0-9][0-9]*\)'` + ;; + *) # positive ints + _flags_test_=`expr "${_flags_int_}" : '\([0-9][0-9]*\)'` + ;; + esac + [ "${_flags_test_}" != "${_flags_int_}" ] && flags_return=${FLAGS_FALSE} + + unset _flags_int_ _flags_test_ + return ${flags_return} +} + +# Parse command-line options using the standard getopt. +# +# Note: the flag options are passed around in the global __flags_opts so that +# the formatting is not lost due to shell parsing and such. +# +# Args: +# @: varies: command-line options to parse +# Returns: +# integer: a FLAGS success condition +_flags_getoptStandard() +{ + flags_return=${FLAGS_TRUE} + _flags_shortOpts_=`_flags_genOptStr ${__FLAGS_OPTSTR_SHORT}` + + # check for spaces in passed options + for _flags_opt_ in "$@"; do + # note: the silliness with the x's is purely for ksh93 on Ubuntu 6.06 + _flags_match_=`echo "x${_flags_opt_}x" |sed 's/ //g'` + if [ "${_flags_match_}" != "x${_flags_opt_}x" ]; then + flags_error='the available getopt does not support spaces in options' + flags_return=${FLAGS_ERROR} + break + fi + done + + if [ ${flags_return} -eq ${FLAGS_TRUE} ]; then + __flags_opts=`getopt ${_flags_shortOpts_} $@ 2>&1` + _flags_rtrn_=$? + if [ ${_flags_rtrn_} -ne ${FLAGS_TRUE} ]; then + _flags_warn "${__flags_opts}" + flags_error='unable to parse provided options with getopt.' + flags_return=${FLAGS_ERROR} + fi + fi + + unset _flags_match_ _flags_opt_ _flags_rtrn_ _flags_shortOpts_ + return ${flags_return} +} + +# Parse command-line options using the enhanced getopt. +# +# Note: the flag options are passed around in the global __flags_opts so that +# the formatting is not lost due to shell parsing and such. +# +# Args: +# @: varies: command-line options to parse +# Returns: +# integer: a FLAGS success condition +_flags_getoptEnhanced() +{ + flags_return=${FLAGS_TRUE} + _flags_shortOpts_=`_flags_genOptStr ${__FLAGS_OPTSTR_SHORT}` + _flags_boolOpts_=`echo "${__flags_boolNames}" \ + |sed 's/^ *//;s/ *$//;s/ /,/g'` + _flags_longOpts_=`_flags_genOptStr ${__FLAGS_OPTSTR_LONG}` + + __flags_opts=`getopt \ + -o ${_flags_shortOpts_} \ + -l "${_flags_longOpts_},${_flags_boolOpts_}" \ + -- "$@" 2>&1` + _flags_rtrn_=$? + if [ ${_flags_rtrn_} -ne ${FLAGS_TRUE} ]; then + _flags_warn "${__flags_opts}" + flags_error='unable to parse provided options with getopt.' + flags_return=${FLAGS_ERROR} + fi + + unset _flags_boolOpts_ _flags_longOpts_ _flags_rtrn_ _flags_shortOpts_ + return ${flags_return} +} + +# Dynamically parse a getopt result and set appropriate variables. +# +# This function does the actual conversion of getopt output and runs it through +# the standard case structure for parsing. The case structure is actually quite +# dynamic to support any number of flags. +# +# Args: +# argc: int: original command-line argument count +# @: varies: output from getopt parsing +# Returns: +# integer: a FLAGS success condition +_flags_parseGetopt() +{ + _flags_argc_=$1 + shift + + flags_return=${FLAGS_TRUE} + + if [ ${__FLAGS_GETOPT_VERS} -ne ${__FLAGS_GETOPT_VERS_ENH} ]; then + set -- $@ + else + # note the quotes around the `$@' -- they are essential! + eval set -- "$@" + fi + + # provide user with number of arguments to shift by later + # NOTE: the FLAGS_ARGC variable is obsolete as of 1.0.3 because it does not + # properly give user access to non-flag arguments mixed in between flag + # arguments. Its usage was replaced by FLAGS_ARGV, and it is being kept only + # for backwards compatibility reasons. + FLAGS_ARGC=`expr $# - 1 - ${_flags_argc_}` + + # handle options. note options with values must do an additional shift + while true; do + _flags_opt_=$1 + _flags_arg_=${2:-} + _flags_type_=${__FLAGS_TYPE_NONE} + _flags_name_='' + + # determine long flag name + case "${_flags_opt_}" in + --) shift; break ;; # discontinue option parsing + + --*) # long option + _flags_opt_=`expr "${_flags_opt_}" : '--\(.*\)'` + _flags_len_=${__FLAGS_LEN_LONG} + if _flags_itemInList "${_flags_opt_}" ${__flags_longNames}; then + _flags_name_=${_flags_opt_} + else + # check for negated long boolean version + if _flags_itemInList "${_flags_opt_}" ${__flags_boolNames}; then + _flags_name_=`expr "${_flags_opt_}" : 'no\(.*\)'` + _flags_type_=${__FLAGS_TYPE_BOOLEAN} + _flags_arg_=${__FLAGS_NULL} + fi + fi + ;; + + -*) # short option + _flags_opt_=`expr "${_flags_opt_}" : '-\(.*\)'` + _flags_len_=${__FLAGS_LEN_SHORT} + if _flags_itemInList "${_flags_opt_}" ${__flags_shortNames}; then + # yes. match short name to long name. note purposeful off-by-one + # (too high) with awk calculations. + _flags_pos_=`echo "${__flags_shortNames}" \ + |awk 'BEGIN{RS=" ";rn=0}$0==e{rn=NR}END{print rn}' \ + e=${_flags_opt_}` + _flags_name_=`echo "${__flags_longNames}" \ + |awk 'BEGIN{RS=" "}rn==NR{print $0}' rn="${_flags_pos_}"` + fi + ;; + esac + + # die if the flag was unrecognized + if [ -z "${_flags_name_}" ]; then + flags_error="unrecognized option (${_flags_opt_})" + flags_return=${FLAGS_ERROR} + break + fi + + # set new flag value + [ ${_flags_type_} -eq ${__FLAGS_TYPE_NONE} ] && \ + _flags_type_=`_flags_getFlagInfo \ + "${_flags_name_}" ${__FLAGS_INFO_TYPE}` + case ${_flags_type_} in + ${__FLAGS_TYPE_BOOLEAN}) + if [ ${_flags_len_} -eq ${__FLAGS_LEN_LONG} ]; then + if [ "${_flags_arg_}" != "${__FLAGS_NULL}" ]; then + eval "FLAGS_${_flags_name_}=${FLAGS_TRUE}" + else + eval "FLAGS_${_flags_name_}=${FLAGS_FALSE}" + fi + else + _flags_strToEval_="_flags_val_=\ +\${__flags_${_flags_name_}_${__FLAGS_INFO_DEFAULT}}" + eval "${_flags_strToEval_}" + if [ ${_flags_val_} -eq ${FLAGS_FALSE} ]; then + eval "FLAGS_${_flags_name_}=${FLAGS_TRUE}" + else + eval "FLAGS_${_flags_name_}=${FLAGS_FALSE}" + fi + fi + ;; + + ${__FLAGS_TYPE_FLOAT}) + if _flags_validateFloat "${_flags_arg_}"; then + eval "FLAGS_${_flags_name_}='${_flags_arg_}'" + else + flags_error="invalid float value (${_flags_arg_})" + flags_return=${FLAGS_ERROR} + break + fi + ;; + + ${__FLAGS_TYPE_INTEGER}) + if _flags_validateInteger "${_flags_arg_}"; then + eval "FLAGS_${_flags_name_}='${_flags_arg_}'" + else + flags_error="invalid integer value (${_flags_arg_})" + flags_return=${FLAGS_ERROR} + break + fi + ;; + + ${__FLAGS_TYPE_STRING}) + eval "FLAGS_${_flags_name_}='${_flags_arg_}'" + ;; + esac + + # handle special case help flag + if [ "${_flags_name_}" = 'help' ]; then + if [ ${FLAGS_help} -eq ${FLAGS_TRUE} ]; then + flags_help + flags_error='help requested' + flags_return=${FLAGS_FALSE} + break + fi + fi + + # shift the option and non-boolean arguements out. + shift + [ ${_flags_type_} != ${__FLAGS_TYPE_BOOLEAN} ] && shift + done + + # give user back non-flag arguments + FLAGS_ARGV='' + while [ $# -gt 0 ]; do + FLAGS_ARGV="${FLAGS_ARGV:+${FLAGS_ARGV} }'$1'" + shift + done + + unset _flags_arg_ _flags_len_ _flags_name_ _flags_opt_ _flags_pos_ \ + _flags_strToEval_ _flags_type_ _flags_val_ + return ${flags_return} +} + +#------------------------------------------------------------------------------ +# public functions +# + +# A basic boolean flag. Boolean flags do not take any arguments, and their +# value is either 1 (false) or 0 (true). For long flags, the false value is +# specified on the command line by prepending the word 'no'. With short flags, +# the presense of the flag toggles the current value between true and false. +# Specifying a short boolean flag twice on the command results in returning the +# value back to the default value. +# +# A default value is required for boolean flags. +# +# For example, lets say a Boolean flag was created whose long name was 'update' +# and whose short name was 'x', and the default value was 'false'. This flag +# could be explicitly set to 'true' with '--update' or by '-x', and it could be +# explicitly set to 'false' with '--noupdate'. +DEFINE_boolean() { _flags_define ${__FLAGS_TYPE_BOOLEAN} "$@"; } + +# Other basic flags. +DEFINE_float() { _flags_define ${__FLAGS_TYPE_FLOAT} "$@"; } +DEFINE_integer() { _flags_define ${__FLAGS_TYPE_INTEGER} "$@"; } +DEFINE_string() { _flags_define ${__FLAGS_TYPE_STRING} "$@"; } + +# Parse the flags. +# +# Args: +# unnamed: list: command-line flags to parse +# Returns: +# integer: success of operation, or error +FLAGS() +{ + # define a standard 'help' flag if one isn't already defined + [ -z "${__flags_help_type:-}" ] && \ + DEFINE_boolean 'help' false 'show this help' 'h' + + # parse options + if [ $# -gt 0 ]; then + if [ ${__FLAGS_GETOPT_VERS} -ne ${__FLAGS_GETOPT_VERS_ENH} ]; then + _flags_getoptStandard "$@" + else + _flags_getoptEnhanced "$@" + fi + flags_return=$? + else + # nothing passed; won't bother running getopt + __flags_opts='--' + flags_return=${FLAGS_TRUE} + fi + + if [ ${flags_return} -eq ${FLAGS_TRUE} ]; then + _flags_parseGetopt $# "${__flags_opts}" + flags_return=$? + fi + + [ ${flags_return} -eq ${FLAGS_ERROR} ] && _flags_fatal "${flags_error}" + return ${flags_return} +} + +# This is a helper function for determining the `getopt` version for platforms +# where the detection isn't working. It simply outputs debug information that +# can be included in a bug report. +# +# Args: +# none +# Output: +# debug info that can be included in a bug report +# Returns: +# nothing +flags_getoptInfo() +{ + # platform info + _flags_debug "uname -a: `uname -a`" + _flags_debug "PATH: ${PATH}" + + # shell info + if [ -n "${BASH_VERSION:-}" ]; then + _flags_debug 'shell: bash' + _flags_debug "BASH_VERSION: ${BASH_VERSION}" + elif [ -n "${ZSH_VERSION:-}" ]; then + _flags_debug 'shell: zsh' + _flags_debug "ZSH_VERSION: ${ZSH_VERSION}" + fi + + # getopt info + getopt >/dev/null + _flags_getoptReturn=$? + _flags_debug "getopt return: ${_flags_getoptReturn}" + _flags_debug "getopt --version: `getopt --version 2>&1`" + + unset _flags_getoptReturn +} + +# Returns whether the detected getopt version is the enhanced version. +# +# Args: +# none +# Output: +# none +# Returns: +# bool: true if getopt is the enhanced version +flags_getoptIsEnh() +{ + test ${__FLAGS_GETOPT_VERS} -eq ${__FLAGS_GETOPT_VERS_ENH} +} + +# Returns whether the detected getopt version is the standard version. +# +# Args: +# none +# Returns: +# bool: true if getopt is the standard version +flags_getoptIsStd() +{ + test ${__FLAGS_GETOPT_VERS} -eq ${__FLAGS_GETOPT_VERS_STD} +} + +# This is effectively a 'usage()' function. It prints usage information and +# exits the program with ${FLAGS_FALSE} if it is ever found in the command line +# arguments. Note this function can be overridden so other apps can define +# their own --help flag, replacing this one, if they want. +# +# Args: +# none +# Returns: +# integer: success of operation (always returns true) +flags_help() +{ + if [ -n "${FLAGS_HELP:-}" ]; then + echo "${FLAGS_HELP}" >&2 + else + echo "USAGE: ${FLAGS_PARENT:-$0} [flags] args" >&2 + fi + if [ -n "${__flags_longNames}" ]; then + echo 'flags:' >&2 + for flags_name_ in ${__flags_longNames}; do + flags_flagStr_='' + flags_boolStr_='' + + flags_default_=`_flags_getFlagInfo \ + "${flags_name_}" ${__FLAGS_INFO_DEFAULT}` + flags_help_=`_flags_getFlagInfo \ + "${flags_name_}" ${__FLAGS_INFO_HELP}` + flags_short_=`_flags_getFlagInfo \ + "${flags_name_}" ${__FLAGS_INFO_SHORT}` + flags_type_=`_flags_getFlagInfo \ + "${flags_name_}" ${__FLAGS_INFO_TYPE}` + + [ "${flags_short_}" != "${__FLAGS_NULL}" ] \ + && flags_flagStr_="-${flags_short_}" + + if [ ${__FLAGS_GETOPT_VERS} -eq ${__FLAGS_GETOPT_VERS_ENH} ]; then + [ "${flags_short_}" != "${__FLAGS_NULL}" ] \ + && flags_flagStr_="${flags_flagStr_}," + [ ${flags_type_} -eq ${__FLAGS_TYPE_BOOLEAN} ] \ + && flags_boolStr_='[no]' + flags_flagStr_="${flags_flagStr_}--${flags_boolStr_}${flags_name_}:" + fi + + case ${flags_type_} in + ${__FLAGS_TYPE_BOOLEAN}) + if [ ${flags_default_} -eq ${FLAGS_TRUE} ]; then + flags_defaultStr_='true' + else + flags_defaultStr_='false' + fi + ;; + ${__FLAGS_TYPE_FLOAT}|${__FLAGS_TYPE_INTEGER}) + flags_defaultStr_=${flags_default_} ;; + ${__FLAGS_TYPE_STRING}) flags_defaultStr_="'${flags_default_}'" ;; + esac + flags_defaultStr_="(default: ${flags_defaultStr_})" + + flags_helpStr_=" ${flags_flagStr_} ${flags_help_} ${flags_defaultStr_}" + flags_helpStrLen_=`expr "${flags_helpStr_}" : '.*'` + flags_columns_=`_flags_columns` + if [ ${flags_helpStrLen_} -lt ${flags_columns_} ]; then + echo "${flags_helpStr_}" >&2 + else + echo " ${flags_flagStr_} ${flags_help_}" >&2 + # note: the silliness with the x's is purely for ksh93 on Ubuntu 6.06 + # because it doesn't like empty strings when used in this manner. + flags_emptyStr_="`echo \"x${flags_flagStr_}x\" \ + |awk '{printf "%"length($0)-2"s", ""}'`" + flags_helpStr_=" ${flags_emptyStr_} ${flags_defaultStr_}" + flags_helpStrLen_=`expr "${flags_helpStr_}" : '.*'` + if [ ${__FLAGS_GETOPT_VERS} -eq ${__FLAGS_GETOPT_VERS_STD} \ + -o ${flags_helpStrLen_} -lt ${flags_columns_} ]; then + # indented to match help string + echo "${flags_helpStr_}" >&2 + else + # indented four from left to allow for longer defaults as long flag + # names might be used too, making things too long + echo " ${flags_defaultStr_}" >&2 + fi + fi + done + fi + + unset flags_boolStr_ flags_default_ flags_defaultStr_ flags_emptyStr_ \ + flags_flagStr_ flags_help_ flags_helpStr flags_helpStrLen flags_name_ \ + flags_columns_ flags_short_ flags_type_ + return ${FLAGS_TRUE} +} + +# Reset shflags back to an uninitialized state. +# +# Args: +# none +# Returns: +# nothing +flags_reset() +{ + for flags_name_ in ${__flags_longNames}; do + flags_strToEval_="unset FLAGS_${flags_name_}" + for flags_type_ in \ + ${__FLAGS_INFO_DEFAULT} \ + ${__FLAGS_INFO_HELP} \ + ${__FLAGS_INFO_SHORT} \ + ${__FLAGS_INFO_TYPE} + do + flags_strToEval_=\ +"${flags_strToEval_} __flags_${flags_name_}_${flags_type_}" + done + eval ${flags_strToEval_} + done + + # reset internal variables + __flags_boolNames=' ' + __flags_longNames=' ' + __flags_shortNames=' ' + + unset flags_name_ flags_type_ flags_strToEval_ +}