Add Zsh completion

Zsh completion is available in `completions/_git-elegant` file. It's configured to complete `git-elegant` command and `git` command (as the Git aliases need to have completion also). The installation script displays instructions for installation both Bash and Zsh completion as well as some recommendations. Also, Getting Started document has a significant update: - it starts from the installation and ends post-steps - the instructions are shorter now - completion recommendations are moved to the installation script #230
bees-hive · Feb 7, 2020 · 4df2738 · 4df2738
1 parent a6d7f6f
commit 4df2738
Show file tree

Hide file tree

Showing 3 changed files with 173 additions and 32 deletions.
diff --git a/completions/_git-elegant b/completions/_git-elegant
@@ -0,0 +1,95 @@
+#compdef git-elegant git
+#description enables Elegant Git completion
+#
+# It's recommended to use with the following Git completion file:
+# https://raw.githubusercontent.com/zsh-users/zsh/master/Completion/Unix/Command/_git
+
+_git-elegant (){
+    # update this function if either new commands or options are added
+    local curcontext='$curcontext' state line
+    typeset -A opt_args
+    _arguments -C ':command:->command' '*::option:->option'
+    local all_commands=(
+        'accept-work:applies a branch on top of \`master\` branch'
+        'acquire-git:configures a Git installation'
+        'acquire-repository:configures current repository'
+        'amend-work:amends some changes to the most recent commit'
+        'clone-repository:clones a repository and configures it'
+        'deliver-work:publishes current branch to a remote repository'
+        'init-repository:initializes a new repository and configures it'
+        'obtain-work:checkouts a remote branch matching by a name'
+        'polish-work:reapplies branch commits interactively'
+        'prune-repository:removes useless local branches'
+        'release-work:releases available work as a new annotated tag'
+        'save-work:commits current modifications'
+        'show-commands:prints available Elegant Git commands'
+        'show-release-notes:prints a release log between two references'
+        'show-work:shows a state of current work in progress'
+        'start-work:creates a new branch'
+    )
+
+    case ${state} in
+        command)
+            local options=(
+                '--help:displays help'
+                '--version:displays program version'
+                '--no-workflows:disables available workflows'
+            )
+            _describe 'first' all_commands -- options
+            ;;
+        option)
+            if [[ ${line[1]} == --no-workflows ]]; then
+                __ge_complete_commands_workflow
+            else
+                __ge_complete_commands
+            fi
+        ;;
+    esac
+}
+
+__ge_complete_commands_workflow() {
+    _arguments ':command:->command' '*::options:->options'
+    case ${state} in
+        command) _describe 'only commands' all_commands ;;
+        options) __ge_complete_commands ;;
+    esac
+}
+
+__ge_complete_commands () {
+    # update this function if a new command requires a competion
+    # default completion is empty
+    case ${line[1]} in
+        accept-work|obtain-work)    __ge_remotes ;;
+        show-release-notes)         __ge_show_release_notes ;;
+        *)  _arguments '--help' '--no-workflows'  ;;
+    esac
+}
+
+__ge_remotes() {
+    # completes first position with remote branches
+    local remotes=(
+        $(git for-each-ref --format='%(refname:strip=2)' refs/remotes 2>/dev/null || echo )
+    )
+    _arguments '--help' \
+               '--no-workflows' \
+               '1:branch:(${remotes[@]})'
+}
+
+__ge_show_release_notes_modes(){
+    local modes=(
+        'simple:prints the messages as a plain text (default one)'
+        'smart:prints the messages in a form of adopted for a git hosting'
+    )
+    _describe 'modes' modes
+}
+
+__ge_show_release_notes() {
+    local all=(
+         $(git for-each-ref --format '%(refname:short)' refs 2>/dev/null || echo )
+    )
+    _arguments '--help' \
+               '--no-workflows' \
+               '1:mode:__ge_show_release_notes_modes' \
+               '2:from:(${all[@]})' \
+               '3:to:(${all[@]})'
+}
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,34 +1,41 @@
-# Several important words
-You can install Elegant Git by either executing `bash` script or using `homebrew`. After the
-installation, please configure your environment by running
-[`git elegant acquire-git`](commands.md#acquire-git) and follow the instructions. To find out more,
-please read [the configuration approach](configuration.md).
+# Installation via Bash script
+Run the follwing command and follow the instructions
+```bash
+curl https://raw.githubusercontent.com/bees-hive/elegant-git/master/install.bash | $(which bash)
+```
+
+Elegant Git will be installed in `~/.elegant-git` directory. That's why if you want to remove
+the installation, just remove the directory.
+
+# Installation via Homebrew
+On macOS, you can install [Homebrew](https://brew.sh/) if you haven't already, then run
+```
+brew install git bees-hive/hive/elegant-git
+```
+The command will
+
+- install Git as it has to be installed with Homebrew for enabling Bash/Zsh completion
+- install Elegant Git
+- configure Bash completion for both Git and Elegant Git
+
+P.S. If you need Zsh completion for all Git commands, consider using
+<https://raw.githubusercontent.com/zsh-users/zsh/master/Completion/Unix/Command/_git>
+(see </~https://github.com/bees-hive/elegant-git/blob/master/install.bash> for the details).
+
+# Post-installation actions
+Configure your environment by running [`git elegant acquire-git`](commands.md#acquire-git)
+and follow the instructions. To find out more, please read
+[the configuration approach](configuration.md).
 
 You can access Elegant Git in CLI using any of
 ```bash
 git <command>
 git elegant <command>
 git-elegant <command>
 ```
-where `<command>` is one of the available commands which are described on [commands](commands.md)
-page or are printed in a terminal by running `git elegant`.
+where `<command>` is one of the commands described on the [commands](commands.md) page or
+printed in a terminal after running `git elegant`.
 
 Also, please use [`git elegant clone-repository`](commands.md#clone-repository) or 
 [`git elegant init-repository`](commands.md#init-repository) instead of regular `clone` or `init` 
 Git's commands in order to get Elegant Git working by default.
-
-# `bash` installation
-Run `curl https://raw.githubusercontent.com/bees-hive/elegant-git/master/install.bash | $(which bash)`
-and follow the provided instructions to install the tool. `${HOME}/.elegant-git` directory will host
-all required files. That's why if you want to remove installation, you need to remove this directory
-only (`rm -r ${HOME}/.elegant-git`).
-
-Elegant Git's BASH completion does not work without regular Git BASH completion. If you don't have
-it, please follow </~https://github.com/bobthecow/git-flow-completion/wiki/Install-Bash-git-completion>
-in addition to Elegant Git's configuration.
-
-# Homebrew installation
-On macOS, you can install [Homebrew](https://brew.sh/) if you haven't already, then run
-`brew install git` (we must install Git with Homebrew in order to have a working BASH completion)
-and `brew install bees-hive/hive/elegant-git` (please visit
-</~https://github.com/bees-hive/homebrew-hive> if you need details).
diff --git a/install.bash b/install.bash
@@ -24,8 +24,9 @@ copy(){
 update-path() {
     local INSTALL_PATH=${1}
     cat <<TEXT
-You need to add Elegant Git to the PATH by adding to
-a "~/.bashrc" or "~/.bash_profile" file:
+You need to add Elegant Git to the PATH by adding the folowing line
+to relevant shell configuration file ('~/.bashrc', '~/.bash_profile',
+'~/.zshrc', etc.):
 
     export PATH=${INSTALL_PATH}/bin:\$PATH
 
@@ -38,12 +39,52 @@ TEXT
 
 update-completion() {
     local INSTALL_PATH=${1}
-    local COMPLETION_FILE="${INSTALL_PATH}/completions/git-elegant.bash"
+    local BASH_COMPLETION="${INSTALL_PATH}/completions/git-elegant.bash"
+    local ZSH_COMPLETION="${INSTALL_PATH}/completions/_git-elegant"
     cat <<TEXT
-You need to add loading of BASH completion file to
-a "~/.bashrc" or "~/.bash_profile" file:
 
-    [ -f ${COMPLETION_FILE} ] && . ${COMPLETION_FILE}
+Completion installation
+=======================
+
+Bash competion
+--------------
+You need to load a Bash completion file from a relevant shell
+configuration file ('~/.bashrc', '~/.bash_profile', etc.) by
+adding the following line:
+
+    [ -f ${BASH_COMPLETION} ] && source ${BASH_COMPLETION}
+
+Elegant Git's Bash completion does not work without regular Git
+completion. If you don't have it, please install it following
+/~https://github.com/bobthecow/git-flow-completion/wiki/Install-Bash-git-completion.
+
+Zsh completion
+--------------
+1. link completion file into a completion directory
+
+    mkdir -p ~/.zsh/completion
+    ln -s ${ZSH_COMPLETION} ~/.zsh/completion/
+
+2. include the completion directory in your '$fpath'
+
+    fpath=(~/.zsh/completion \${fpath})
+
+3. make sure compinit is loaded or do it by adding in '~/.zshrc:'
+
+    autoload -Uz compinit && compinit -i
+
+4. (optional) consider using
+https://raw.githubusercontent.com/zsh-users/zsh/master/Completion/Unix/Command/_git
+as Git completion file that provides great completions for Git commands and plugins
+Elegant Git's completion file.
+
+    curl -L https://raw.githubusercontent.com/zsh-users/zsh/master/Completion/Unix/Command/_git \\
+        > ~/.zsh/completion/_git
+
+
+P.S.
+----
+Please restart terminal session in order to activate completion.
 
 TEXT
 }
@@ -78,9 +119,7 @@ main() {
     else
         update-path ${INSTALL_PATH}
     fi
-    if ! complete -p git-elegant 1>/dev/null 2>&1; then
-        update-completion ${INSTALL_PATH}
-    fi
+    update-completion ${INSTALL_PATH}
 }
 
 main $@