git-feature: add configurable branch separator (tj#1072)

* git-feature: add configurable branch separator

Closes tj#1069

This allows the use of a separator other than `/` for feature or other
alias branches. While a command-line option has been provided (`-s` or
`--separator`), this will most often be used via
`git-extras.feature.separator`.

* Significant update to bin/git-feature

- Changed option parsing so that `--alias` requires an argument and will
  fail with an error unless provided. Applied the same logic to
  `--separator`.

- Changed `finish` parsing to capture it as a variable flag during
  argument parsing.

  This could be extended so that if `finish` is already true, a second
  `finish` results in the word being added to the argument list.

  ```console
  $ git feature -- finish remote
  $ git feature finish finish remote
  ```

  This has not been done because it is a bit of an inconsistent handling
  for documentation purposes.

- Add handling of `--` to permit options or `finish` to be made part of
  the feature branch name.

- Since `finish` is now a variable flag, simplify the name-building
  logic to always use `concatargs "${argv[@]}"`. This means that
  `git feature finish ...` and `git feature ...` behave the same in
  terms of feature branch name building.

- Basically rewrote the man page to include better descriptions of the
  options as well as adding a GIT CONFIG section and additional EXAMPLES
  for the new features/behaviour.

bin/git-feature

@@ -6,36 +6,63 @@ if [ -z "$branch_prefix" ]; then
    branch_prefix="feature"
 fi
 
+branch_separator=$(git config --get git-extras.feature.separator)
+
+if [ -z "$branch_separator" ]; then
+   branch_separator="/"
+fi
+
 merge_mode="--no-ff"
+finish=false
 declare -a argv
 while test $# != 0
 do
   case $1 in
   -a|--alias )
-    if [[ -n $2 ]]
+    if [[ -n $2 ]] && [[ $2 != -- ]]
     then
       shift # shift -a|-alias
       branch_prefix=$1
     else
-      argv+=("$1") # treat tail '-a' as <name>
+      echo >&2 "option $1 requires a value"
+      exit 1
     fi
     ;;
   -r|--remote )
-    if [[ -n $2 ]]
+    if [[ -n $2 ]] && [[ $2 != -- ]]
     then
       remote=$2
       shift
     else
       remote="origin"
     fi
     ;;
+  -s|--separator )
+    if [[ -n $2 ]] && [[ $2 != -- ]]
+    then
+      branch_separator=$2
+      shift
+    else
+      echo >&2 "option $1 requires a value"
+      exit 1
+    fi
+    ;;
   --squash )
     merge_mode="--squash"
     ;;
   --from )
     start_point=$2
     shift
     ;;
+  -- )
+    # terminate argument parsing
+    shift
+    argv+=("$@")
+    break
+    ;;
+  finish )
+    finish=true
+    ;;
   * )
     argv+=("$1")
     ;;
@@ -45,21 +72,17 @@ done
 
 concatargs() {
   str=$(IFS='-'; echo "$*")
-  branch="$branch_prefix"/$str
+  branch="$branch_prefix$branch_separator$str"
 }
 
-if test "${argv[0]}" = "finish"; then
-  test -z "${argv[1]}" && echo "$branch_prefix" "<name> required." 1>&2 && exit 1
-  branch="$branch_prefix"/"${argv[1]}"
+test -z "${argv[0]}" && echo "$branch_prefix" "<name> required." 1>&2 && exit 1
+
+concatargs "${argv[@]}"
+
+if "${finish}"
+then
   git merge ${merge_mode} "$branch" && git delete-branch "$branch"
 else
-  test -z "${argv[0]}" && echo "$branch_prefix" "<name> required." 1>&2 && exit 1
-  if test -n "${argv[1]}"; then
-    concatargs "${argv[@]}"
-  else
-    branch="$branch_prefix"/"${argv[0]}"
-  fi
-
   if [[ -n $remote ]] && [[ -z $start_point ]]
   then
     git create-branch -r "$remote" "$branch"

man/git-feature.1

@@ -1,56 +1,85 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "GIT\-FEATURE" "1" "November 2020" "" "Git Extras"
+.TH "GIT\-FEATURE" "1" "September 2023" "" "Git Extras"
 .
 .SH "NAME"
 \fBgit\-feature\fR \- Create/Merge feature branch
 .
 .SH "SYNOPSIS"
-\fBgit\-feature\fR [\-a|\-\-alias branch_prefix] [\-r|\-\-remote [remote_name]] <name>
+\fBgit\-feature\fR [\-a|\-\-alias \fIPREFIX\fR] [\-s|\-\-separator \fISEPARATOR\fR] [\-r|\-\-remote [REMOTE_NAME]] [\-\-from START_POINT] \fINAME\fR\.\.\.
 .
-.br
-\fBgit\-feature\fR [\-a|\-\-alias branch_prefix] finish [\-\-squash] <name>
+.P
+\fBgit\-feature\fR [\-a|\-\-alias \fIPREFIX\fR] [\-s|\-\-separator \fISEPARATOR\fR] finish [\-\-squash] \fINAME\fR\.\.\.
 .
 .SH "DESCRIPTION"
-Create/Merge the given feature branch
-.
-.SH "OPTIONS"
-<\-a|\-\-alias branch_prefix>
+Create or merge the given feature branch\. The feature branch name is made from the \fIPREFIX\fR, the \fISEPARATOR\fR, and the \fINAME\fR joined together\.
 .
 .P
-use \fBbranch_prefix\fR instead of \fBfeature\fR
+The default \fIPREFIX\fR is \fBfeature\fR and \fISEPARATOR\fR is \fB/\fR, which can be changed (see OPTIONS and GIT CONFIG for details)\.
 .
 .P
-<\-r|\-\-remote [remote_name]>
+The branch \fINAME\fR may be specified as multiple words which will be joined with \fB\-\fR\. If the branch name contains the word \fBfinish\fR or is another OPTION, \fB\-\-\fR should be passed to stop OPTION parsing\. See the EXAMPLES for details\.
 .
-.P
+.SH "OPTIONS"
+.
+.TP
+\fB\-a\fR \fIPREFIX\fR, \fB\-\-alias\fR \fIPREFIX\fR:
+.
+.IP
+The branch prefix to use, or \fBfeature\fR if not supplied\.
+.
+.TP
+\fB\-s\fR \fISEPARATOR\fR, \fB\-\-separator\fR \fISEPARATOR\fR:
+.
+.IP
+The separator to use for joining the branch prefix and the branch name, or \fB/\fR if not supplied\.
+.
+.TP
+\fB\-r\fR [REMOTE_NAME], \fB\-\-remote\fR [REMOTE_NAME]:
+.
+.IP
 Setup a remote tracking branch using \fBremote_name\fR\. If \fBremote_name\fR is not supplied, use \fBorigin\fR by default\.
 .
-.P
-<\-\-from [start_point]>
+.TP
+\fB\-\-from\fR START_POINT:
 .
-.P
-Setup a start point when the branch created\. If \fB\-\-from\fR is not supplied, use the current branch by default\.
+.IP
+Setup a start point when the branch created\. If \fB\-\-from\fR is not supplied, use the current branch by default\. This option will be ignored when \fBfinish\fRing a branch\.
 .
-.P
-<finish>
+.TP
+\fBfinish\fR:
 .
-.P
+.IP
 Merge and delete the feature branch\.
 .
-.P
-<\-\-squash>
+.TP
+\fB\-\-squash\fR:
 .
-.P
-Run a squash merge\.
+.IP
+Run a squash merge when \fBfinish\fRing the feature branch\.
 .
-.P
-<name>
+.TP
+\fINAME\fR:
 .
-.P
+.IP
 The name of the feature branch\.
 .
+.SH "GIT CONFIG"
+You can configure the default branch prefix and separator via git config options\.
+.
+.TP
+\fBgit\-extras\.feature\.prefix\fR:
+.
+.IP
+$ git config \-\-global add git\-extras\.feature\.prefix "prefix"
+.
+.TP
+\fBgit\-extras\.feature\.separator\fR:
+.
+.IP
+$ git config \-\-global add git\-extras\.feature\.separator "\-"
+.
 .SH "EXAMPLES"
 .
 .TP
@@ -107,6 +136,54 @@ $ (features/dependencies) git checkout master
 .br
 $ git features finish dependencies
 .
+.TP
+Use custom branch separator:
+.
+.IP
+$ git feature \-s \- dependencies
+.
+.br
+$ (feature\-dependencies) \.\.\.
+.
+.br
+$ (feature\-dependencies) git checkout master
+.
+.br
+$ git feature \-s \- finish dependencies
+.
+.TP
+Use custom branch prefix and separator from git config with multiple words:
+.
+.IP
+$ git config \-\-global \-\-add git\-extras\.feature\.prefix "features"
+.
+.br
+$ git config \-\-global \-\-add git\-extras\.feature\.separator "\."
+.
+.br
+$ git feature dependency tracking
+.
+.br
+$ (features\.dependency\-tracking) \.\.\.
+.
+.br
+$ (features\.dependency\-tracking) git checkout master
+.
+.br
+$ git feature finish dependency tracking
+.
+.TP
+Use a \fBgit\-feature\fR option flag as part of a branch name:
+.
+.IP
+$ git feature \-\- finish remote
+.
+.br
+\&\.\.\.
+.
+.br
+$ (feature/finish\-remote) git commit \-m "Some changes"
+.
 .SH "AUTHOR"
 Written by Jesús Espino <\fIjespinog@gmail\.com\fR>
 .
@@ -116,8 +193,11 @@ Modified by Mark Pitman <\fImark\.pitman@gmail\.com\fR>
 .br
 Modified by Carlos Prado <\fIcarlos\.prado@cpradog\.com\fR>
 .
+.br
+Modified by Austin Ziegler <\fIhalostatue@gmail\.com\fR>
+.
 .SH "REPORTING BUGS"
 <\fIhttps://github\.com/tj/git\-extras/issues\fR>
 .
 .SH "SEE ALSO"
-<\fIhttps://github\.com/tj/git\-extras\fR>
+<\fIhttps://github\.com/tj/git\-extras\fR>, git\-create\-branch(1), git\-delete\-branch(1)