Commit b96483fc authored by Adrian DC's avatar Adrian DC
Browse files

docs(readme): improve the documentation and parameters readability 

Signed-off-by: default avatarAdrian DC <radian.dc@gmail.com>
parent 9416c624

README.md

+132 −109
Changes for README.md: 132 added lines, 109 removed lines.
Original line number Diff line number Diff line
@@ -34,86 +34,102 @@ is the common and unique interface between GitLab CI and `gitlabci-local`. 


## Examples



| Commands                       | Purpose                                            |

| :----------------------------- | :------------------------------------------------- |

| gitlabci-local                 | Launch the jobs choices interactive menu           |

| gitlabci-local -p              | Launch the jobs pipeline automatically             |

| gitlabci-local -l              | Launch the job selection interactive menu          |

| gitlabci-local 'Dev'           | Launch jobs where the name contains a given string |

| gitlabci-local 'Job 1' --debug | Hold a finishing specific job for debugging        |

| gitlabci-local 'Job 1' --bash  | Prepare a bash environment for a specific job      |

| gcil                           | Shortcut alias to gitlabci-local                   |

<!-- prettier-ignore-start -->



```bash

gitlabci-local                   # Launch the jobs choices interactive menu

gitlabci-local -p                # Launch the jobs pipeline automatically

gitlabci-local -l                # Launch the job selection interactive menu

gitlabci-local 'Dev'             # Launch jobs where the name contains a given string

gitlabci-local 'Job 1' --debug   # Hold a finishing specific job for debugging

gitlabci-local 'Job 1' --bash    # Prepare a bash environment for a specific job

gcil                             # Shortcut alias to gitlabci-local

```



<!-- prettier-ignore-end -->



---



## Usage



| Command        |                                     |

| -------------- | ----------------------------------- |

| gitlabci-local | Main entrypoint to this project     |

| gcil           | Shortcut entrypoint to this project |



| Internal arguments  |                                                                                          |

| ------------------- | ---------------------------------------------------------------------------------------- |

| -h, --help          | Show this help message                                                                   |

| --version           | Show the current version                                                                 |

| --update-check      | Check for newer package updates                                                          |

| --settings          | Show the current settings path and contents                                              |

| --set GROUP KEY VAL | Set settings specific 'VAL' value to [GROUP] > KEY<br>or unset by using 'UNSET' as 'VAL' |



| Pipeline arguments |                                                                                                              |

| ------------------ | ------------------------------------------------------------------------------------------------------------ |

| -p, --pipeline     | Automatically run pipeline stages rather than jobs                                                           |

| -q, --quiet        | Hide jobs execution context                                                                                  |

| -c CONFIGURATION   | Path to the .gitlab-ci.yml configuration file or folder                                                      |

| -B, --no-before    | Disable before_script executions                                                                             |

| -A, --no-after     | Disable after_script executions                                                                              |

| -C COMMANDS        | Run specific commands instead of "scripts" commands                                                          |

| -n NETWORK         | Configure the network mode used (or define CI_LOCAL_NETWORK)<br>Choices: bridge, host, none. Default: bridge |

| -e ENV             | Define VARIABLE=value, pass VARIABLE or ENV file                                                             |

| -E ENGINE          | Force a specific engine (or define CI_LOCAL_ENGINE)<br>Default list: auto,docker,podman                      |

| -H, --host         | Run all jobs on the host rather than containers                                                              |

| --notify           | Enable host notifications of pipeline and jobs results                                                       |

| -r, --real-paths   | Mount real folder paths in the container (Linux / macOS only)                                                |

| -S, --sockets      | Mount engine sockets for nested containers<br>(Enabled by default with services: docker:\*dind)              |

| --ssh [SSH_USER]   | Bind SSH credentials to a container's user                                                                   |

| -v VOLUME          | Mount VOLUME or HOST:TARGET in containers                                                                    |

| -w WORKDIR         | Override the container's working path                                                                        |



| Debugging arguments |                                                   |

| ------------------- | ------------------------------------------------- |

| --bash              | Prepare runners for manual bash purposes          |

| --debug             | Keep runners active for debugging purposes        |

| --display           | Enable host DISPLAY forwarding features           |

| --shell SHELL       | Configure the default bash/debug shell entrypoint |



| Jobs arguments    |                                                                                                   |

| ----------------- | ------------------------------------------------------------------------------------------------- |

| --all             | Enable all jobs by default in selections                                                          |

| --defaults        | Use default variables for .local:configurations                                                   |

| -f, --force       | Force the action (use with --pull)                                                                |

| -i, --ignore-case | Ignore case when searching for names                                                              |

| -m, --manual      | Allow manual jobs to be used                                                                      |

| --no-color        | Disable colors outputs with 'NO_COLOR=1'<br>(or default settings: [themes] > no_color)            |

| --no-console      | Disable console launch in bash/debug modes<br>(or default settings: [runner] > no_console)        |

| --no-git-safeties | Disable automated Git safeties configuration<br>(or default settings: [runner] > no_git_safeties) |

| --no-script-fail  | Fail on missing 'script' nodes of jobs<br>(or default settings: [runner] > no_script_fail)        |

| -R, --no-regex    | Disable regex search of names                                                                     |

| --no-verbose      | Hide jobs verbose outputs                                                                         |

| --scripts         | Dump parsed jobs entrypoint scripts                                                               |

| -t TAGS           | Handle listed tags as manual jobs<br>Default list: deploy,local,publish                           |



| Features arguments |                                            |

| ------------------ | ------------------------------------------ |

| -d, --dump         | Dump parsed .gitlab-ci.yml configuration   |

| -s, --select       | Force jobs selection from enumerated names |

| -l, --list         | Select one job to run (implies --manual)   |

| --pull             | Pull container images from all jobs        |

| --rmi              | Delete container images from all jobs      |



| Positional arguments |                                                                                                           |

| -------------------- | --------------------------------------------------------------------------------------------------------- |

| names                | Names of specific jobs (or stages with --pipeline)<br>Regex names are supported unless --no-regex is used |

<!-- prettier-ignore-start -->



```yaml

usage: gitlabci-local [-h] [--version] [--update-check] [--settings] [--set GROUP KEY VAL] [-p] [-q] [-c CONFIGURATION] [-B] [-A] [-C COMMANDS] [-n NETWORK] [-e ENV] [-E ENGINE]

                      [-H] [--notify] [-r] [-S] [--ssh [SSH_USER]] [-v VOLUME] [-w WORKDIR] [--bash | --debug] [--display] [--shell SHELL] [--all] [--defaults] [-f] [-i] [-m]

                      [--no-color] [--no-console] [--no-git-safeties] [--no-script-fail] [-R] [--no-verbose] [--scripts] [-t TAGS] [-d | -s | -l | --pull | --rmi]

                      [names ...]



gitlabci-local: Launch .gitlab-ci.yml jobs locally (aliases: gcil)



internal arguments:

  -h, --help           # Show this help message

  --version            # Show the current version

  --update-check       # Check for newer package updates

  --settings           # Show the current settings path and contents

  --set GROUP KEY VAL  # Set settings specific 'VAL' value to [GROUP] > KEY

                       # or unset by using 'UNSET' as 'VAL'



pipeline arguments:

  -p, --pipeline       # Automatically run pipeline stages rather than jobs

  -q, --quiet          # Hide jobs execution context

  -c CONFIGURATION     # Path to the .gitlab-ci.yml configuration file or folder

  -B, --no-before      # Disable before_script executions

  -A, --no-after       # Disable after_script executions

  -C COMMANDS          # Run specific commands instead of "scripts" commands

  -n NETWORK           # Configure the network mode used (or define CI_LOCAL_NETWORK)

                       # Choices: bridge, host, none. Default: bridge

  -e ENV               # Define VARIABLE=value, pass VARIABLE or ENV file

  -E ENGINE            # Force a specific engine (or define CI_LOCAL_ENGINE)

                       # Default list: auto,docker,podman

  -H, --host           # Run all jobs on the host rather than containers

  --notify             # Enable host notifications of pipeline and jobs results

  -r, --real-paths     # Mount real folder paths in the container (Linux / macOS only)

  -S, --sockets        # Mount engine sockets for nested containers

                       # (Enabled by default with services: docker:*dind)

  --ssh [SSH_USER]     # Bind SSH credentials to a container's user

  -v VOLUME            # Mount VOLUME or HOST:TARGET in containers

  -w WORKDIR           # Override the container's working path



debugging arguments:

  --bash               # Prepare runners for manual bash purposes

  --debug              # Keep runners active for debugging purposes

  --display            # Enable host DISPLAY forwarding features

  --shell SHELL        # Configure the default bash/debug shell entrypoint



jobs arguments:

  --all                # Enable all jobs by default in selections

  --defaults           # Use default variables for .local:configurations

  -f, --force          # Force the action (use with --pull)

  -i, --ignore-case    # Ignore case when searching for names

  -m, --manual         # Allow manual jobs to be used

  --no-color           # Disable colors outputs with 'NO_COLOR=1'

                       # (or default settings: [themes] > no_color)

  --no-console         # Disable console launch in bash/debug modes

                       # (or default settings: [runner] > no_console)

  --no-git-safeties    # Disable automated Git safeties configuration

                       # (or default settings: [runner] > no_git_safeties)

  --no-script-fail     # Fail on missing 'script' nodes of jobs

                       # (or default settings: [runner] > no_script_fail)

  -R, --no-regex       # Disable regex search of names

  --no-verbose         # Hide jobs verbose outputs

  --scripts            # Dump parsed jobs entrypoint scripts

  -t TAGS              # Handle listed tags as manual jobs

                       # Default list: deploy,local,publish



features arguments:

  -d, --dump           # Dump parsed .gitlab-ci.yml configuration

  -s, --select         # Force jobs selection from enumerated names

  -l, --list           # Select one job to run (implies --manual)

  --pull               # Pull container images from all jobs

  --rmi                # Delete container images from all jobs



positional arguments:

  names                # Names of specific jobs (or stages with --pipeline)

                       # Regex names is supported unless --no-regex is used

```



<!-- prettier-ignore-end -->



---
@@ -135,38 +151,43 @@ inside a `.local` node to ease default parameters definitions. 


Supported local values for a `.local` node are:



| Keys and types         | Descriptions                                                                                          |

| ---------------------- | ----------------------------------------------------------------------------------------------------- |

| `after: bool`          | Enable or disable `after_script` executions (see `-A`)                                                |

| `all: bool`            | Enable all jobs by default in selections (see `--all`)                                                |

| `bash: bool`           | Prepare runners for manual bash purposes (see `--bash`)                                               |

| `before: bool`         | Enable or disable `before_script` executions (see `-B`)                                               |

| `configurations: dict` | See [User configurations with '.local:configurations'](#user-configurations-with-localconfigurations) |

| `debug: bool`          | Keep runners active for debugging purposes (see `--debug`)                                            |

| `defaults: bool`       | Use default variables for `.local:configurations` (see `--defaults`)                                  |

| `display: bool`        | Enable host `DISPLAY` forwarding features (see `--display`)                                           |

| `engine: str`          | Force a specific engine (see `-E`)                                                                    |

| `env: list[str]`       | Define `VARIABLE=value`, pass `VARIABLE` or `ENV` file (see `-e`)                                     |

| `image: dict\|str`     | Override container image's `name` and/or `entrypoint`                                                 |

| `include: dict`        | Map `include: project:` names to local paths                                                          |

| `manual: bool`         | Allow manual jobs to be used (see `--manual`)                                                         |

| `names: list[str]`     | Names of specific jobs (or stages with `--pipeline`) (see `names`)                                    |

| `network: str`         | Configure the network mode used (see `--network`)                                                     |

| `no_console: bool`     | Disable console launch in bash/debug modes (see `--no-console`)                                       |

| `no_regex: bool`       | Disable regex search of names (see `--no-regex`)                                                      |

| `no_verbose: bool`     | Hide jobs verbose outputs (see `--no-verbose`)                                                        |

| `notify: bool`         | Enable host notifications of pipeline and jobs results (see `--notify`)                               |

| `pipeline: bool`       | Automatically run pipeline stages rather than jobs (see `-p`)                                         |

| `quiet: bool`          | Hide jobs execution context (see `-q`)                                                                |

| `real_paths: bool`     | Mount real folder paths in the container (see `-r`)                                                   |

| `shell: str`           | Configure the default bash/debug shell entrypoint (see `--shell`)                                     |

| `sockets: bool`        | Mount engine sockets for nested containers (see `-S`)                                                 |

| `ssh: bool\|str`       | Bind SSH credentials to a container's user (see `--ssh`)                                              |

| `tags: list[str]`      | Handle listed tags as manual jobs (see `--tags`)                                                      |

| `variables: dict[str]` | Define `KEY: VALUE` variables for local jobs                                                          |

| `version: str`         | Define a minimum version for `gitlabci-local` recommended for this file                               |

| `volumes: bool`        | Mount `VOLUME` or `HOST:TARGET` in containers (see `-v`)                                              |

| `workdir: bool`        | Override the container's working path (see `-w`)                                                      |

<!-- prettier-ignore-start -->



```yaml

.local:

  after: bool            # Enable or disable `after_script` executions (see `-A`)

  all: bool              # Enable all jobs by default in selections (see `--all`)

  bash: bool             # Prepare runners for manual bash purposes (see `--bash`)

  before: bool           # Enable or disable `before_script` executions (see `-B`)

  configurations: dict   # See [User configurations with '.local:configurations'](#user-configurations-with-localconfigurations)

  debug: bool            # Keep runners active for debugging purposes (see `--debug`)

  defaults: bool         # Use default variables for `.local:configurations` (see `--defaults`)

  display: bool          # Enable host `DISPLAY` forwarding features (see `--display`)

  engine: str            # Force a specific engine (see `-E`)

  env: list[str]         # Define `VARIABLE=value`, pass `VARIABLE` or `ENV` file (see `-e`)

  image: dict|str        # Override container image's `name` and/or `entrypoint

  include: dict          # Map `include: project:` names to local paths

  manual: bool           # Allow manual jobs to be used (see `--manual`)

  names: list[str]       # Names of specific jobs (or stages with `--pipeline`) (see `names`)

  network: str           # Configure the network mode used (see `--network`)

  no_console: bool       # Disable console launch in bash/debug modes (see `--no-console`)

  no_regex: bool         # Disable regex search of names (see `--no-regex`)

  no_verbose: bool       # Hide jobs verbose outputs (see `--no-verbose`)

  notify: bool           # Enable host notifications of pipeline and jobs results (see `--notify`)

  pipeline: bool         # Automatically run pipeline stages rather than jobs (see `-p`)

  quiet: bool            # Hide jobs execution context (see `-q`)

  real_paths: bool       # Mount real folder paths in the container (see `-r`)

  shell: str             # Configure the default bash/debug shell entrypoint (see `--shell`)

  sockets: bool          # Mount engine sockets for nested containers (see `-S`)

  ssh: bool|str          # Bind SSH credentials to a container's user (see `--ssh`)

  tags: list[str]        # Handle listed tags as manual jobs (see `--tags`)

  variables: dict[str]   # Define `KEY: VALUE` variables for local jobs

  version: str           # Define a minimum version for `gitlabci-local` recommended for this file

  volumes: bool          # Mount `VOLUME` or `HOST:TARGET` in containers (see `-v`)

  workdir: bool          # Override the container's working path (see `-w`)

```



<!-- prettier-ignore-end -->



Examples for each of these can be found in the `local` unit tests: [tests/local](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/local/.gitlab-ci.yml)

and [tests/includes](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/includes/.gitlab-ci.project.yml)
@@ -230,6 +251,7 @@ The following variables are also defined by `gitlabci-local`: 
- `CI_LOCAL_USER_HOST_USERNAME`: The host user's username value



  </div>



</details>



---
@@ -308,7 +330,7 @@ or to disable the automated updates daily check (`[updates] > enabled`) 


The `settings.ini` file location and contents can be shown with the following command:



```yml

```bash

gitlabci-local --settings

```
@@ -335,6 +357,7 @@ an environment variable `NO_COLOR=1` can be defined to disable colors. 
you shoud uninstall both packages first before updating



  </div>



</details>



---
@@ -345,7 +368,7 @@ an environment variable `NO_COLOR=1` can be defined to disable colors. 
  <summary>Expand .gitlab-ci.yml template documentation</summary>

  <div style="padding-left: 30px">



```yml

```yaml

# Global configurations



include: FILE_PATH