Add functionality for CLI options and existing env variables. Make github the default host.

Author: lu0

README.md

@@ -3,27 +3,98 @@
 
 This script clones a subdirectory of a github/gitlab repository.
 
-# Usage
-## Quick test
-Test the script with the example config file.
-By the end of the execution, you will see a `tmp` directory containing the subfolder of the example repository.
+- [Install](#install)
+- [Using the comand line options](#using-the-comand-line-options)
+  - [Clone from public repositories](#clone-from-public-repositories)
+  - [Clone from private repositories](#clone-from-private-repositories)
+- [Using a configuration file](#using-a-configuration-file)
+  - [Configuration variables](#configuration-variables)
+    - [Mandatory variables](#mandatory-variables)
+    - [Variables for **private repositories**](#variables-for-private-repositories)
+    - [Optional variables](#optional-variables)
+
+# Install
+Clone this repository
 ```zsh
-./git-partial-clone.sh --file example.conf
+sudo apt install -y git
+git clone https://github.com/lu0/git-partial-clone.git
 ```
-## Install
 Install the script and autocompletion rules.
 ```zsh
-./install.sh
+cd git-partial-clone/ && ./install.sh
 ```
-Then you can execute the script from any directory with your custom config file and use `TAB` to autocomplete the CLI options.
+Then you can call the command `git-partial-clone` from any directory and use `TAB` to autocomplete the CLI options.
+
+# Using the comand line options
+Run with the `--help` flag to see the complete list of options (recommended). Or read the following sections to clone using the most common options.
+```
+$ git-partial-clone -h
+
+Clone a subdirectory of a github/gitlab repository.
+
+USAGE:
+   git-partial-clone   [OPTIONS] ARGUMENTS
+   git-partial-clone   # Or assume config variables in shell.
+
+OPTIONS:
+            --help     Show this manual.
+
+   Using a config file:
+       -f | --file     Path to the configuration file.
+
+   CLI options (mandatory):
+       -o | --owner    Author (owner) of the repository.
+       -r | --repo     Name of the repository.
+
+   CLI options (optional):
+       -h | --host     github (default) or gitlab.
+       -s | --subdir   Subfolder to be cloned.
+
+       -t | --token    Path to your access token (for private repos).
+       -u | --user     Your username (for private repos).
+
+       -b | --branch   Branch to be fetched.
+       -d | --depth    Number of commits to be fetched.
+```
+
+## Clone from public repositories
+Provide the mandatory options `--repo`, `--owner` and the subdirectory (`--subdir`) you want to clone.
+
+The following example clones a subfolder of my [vscode-settings](https://github.com/lu0/vscode-settings/tree/master/json/snippets) repository.
 ```zsh
-git-partial-clone --file path/to/your/config/file.conf
+git-partial-clone --owner=lu0 --repo=vscode-settings --subdir=json/snippets
 ```
 
-# Configuration
+You can also clone the entire repository, although this is not the intended use.
+```zsh
+git-partial-clone --owner=lu0 --repo=vscode-settings
+```
+
+## Clone from private repositories
+You will need to generate an access token in order to clone private repositories, as password authentication is deprecated.
+
+- Github: [github.com/settings/tokens](https://github.com/settings/tokens).
+- Gitlab: [gitlab.com/-/profile/personal_access_tokens](https://gitlab.com/-/profile/personal_access_tokens).
+
+Save your token in a file and provide its path with the `--token` option, then provide your username with the `--user` option.
+
+The following example would clone a subfolder of a private repository.
+```zsh
+git-partial-clone --owner=owner --repo=repo --subdir=path/to/subdir \
+    --token=/path/to/your/token/file --user=username_with_access
+```
+
+# Using a configuration file
+Using a configuration file will give you more control over the objects you're cloning. You can test this functionality with the provided configuration file:
+```zsh
+git-partial-clone --file=example.conf
+```
+By the end of the execution, you will see a `tmp` directory containing the subfolder of the example repository.
+
+## Configuration variables
 Fill in the config file ([`template.conf`](./template.conf)) with the information of the repository you're cloning. You can see the example file [here](./example.conf).
 
-## Mandatory variables
+### Mandatory variables
 
 - `GIT_HOST`:
     - `github` if the repository is hosted on Github.
@@ -36,21 +107,13 @@ Fill in the config file ([`template.conf`](./template.conf)) with the informatio
     - **Subdirectory of the repository you want to clone**.
     - Omit it to clone the entire repository.
 
-## Mandatory variables for **private repositories**
-You will need to generate an access token in order to clone private repositories, as password authentication is deprecated.
-
-- Github: [github.com/settings/tokens](https://github.com/settings/tokens).
-- Gitlab: [gitlab.com/-/profile/personal_access_tokens](https://gitlab.com/-/profile/personal_access_tokens).
-
-Once you have a token, store it in a file.
-
+### Variables for **private repositories**
 - `TOKEN_PATH`:
     - Path to the file containing the access token.
 - `GIT_USER`:
     - Username with access to the repository.
 
-## Optional variables
-The following variables give you more control over the objects you're cloning.
+### Optional variables
 - `BRANCH`:
     - The branch to be fetched.
     - Omit it to pull all of the branches and switch to the default one.

completion-rules.sh

@@ -1,5 +1,5 @@
 #
-# Bash completion file for the git-partial-clone script
+# Bash completion extension file for the git-partial-clone script
 #
 # Copyright (c) 2021 Lucero Alvarado 
 #   https://github.com/lu0/git-partial-clone
@@ -10,25 +10,55 @@ _git-partial-clone()
 {
     local cur prev
     local words cword
-    _init_completion || return
 
+    # Complete by using _split_longopt()
+    _init_completion -s || return
+
+    # Try to stop option suggestion if -(-f)ile was provided
     local i use_config_file
     for ((i = cword - 1; i > 0; i--)); do
-        [[ ${words[i]} == --file ]] \
+        { [[ ${words[i]} == --file* ]] || [[ ${words[i]} == -f ]] ;} \
             && use_config_file=true && break
     done
 
-    case $prev in
+    case "${prev}" in
         --file | -!(-*)f)
             # Suggest files with .conf extension
-            _filedir '?()conf'
+            _expand "$cur" && _filedir '?()conf'
+            return
+            ;;
+        --host | -!(-*)h)
+            # Suggest tested hosts
+            COMPREPLY=( $(compgen -W '
+                github gitlab
+                ' -- "$cur" ) )
+            return 0
+            ;;
+        --token | -!(-*)t)
+            # Autocomplete for any file/directory
+            _expand "$cur" && _filedir
+            return
+            ;;
+        --owner | -o | --repo | -r | --subdir | -s | \
+        --user | -u | --branch | -b | --depth | -d )
+            # Suggest nothing :P
+            return
+            ;;
+        --help*)
             return
             ;;
     esac
 
-    # Suggest options contained in the 'usage' section of the script
+    # Suggest options contained in the 'usage'
+    #   section of the git-partial-clone script
+    # If the option is long, suggest it with a leading '='
+    # unless it is the --help option
     [[ ! $use_config_file ]] \
-        && COMPREPLY=($(compgen -W '$(_parse_help "$1")' -- "$cur"))
+        && COMPREPLY=($(compgen -W '
+                $(_parse_help "$1" \
+                    | while read opt; do echo ${opt}\=; done \
+                    | sed "s/--help=/--help/g")
+            ' -- "$cur"))
 }
-complete -F _git-partial-clone git-partial-clone
+complete -o nosort -o nospace -F _git-partial-clone git-partial-clone
 

example.conf

@@ -15,7 +15,7 @@ REMOTE_PARTIAL_DIR=json/snippets
 TOKEN_PATH=
 GIT_USER=
 
-BRANCH=
+BRANCH=master
 COMMIT_DEPTH=3
 
 PARENT_DIR=tmp