Application Configuration

A part of the aspects of git ws can be configured at various levels. Programmatically, the AppConfig class can be used to retrieve and set configuration values. On the command line, the git ws config command with its various sub-commands provides the same capabilities.

git ws config

Get and set application configuration options.

Usage: git-ws config [OPTIONS] COMMAND [ARGS]...

  Read and modify configuration values.

Options:
  -h, --help  Show this message and exit.

Commands:
  delete  Remove the OPTION from the configuration.
  files   Show the location of the configuration files.
  get     Get the value of a configuration OPTION.
  list    List all configuration options.
  set     Set the configuration OPTION to the given VALUE.

The config sub-command can be used to retrieve and modify configuration values for the system wide, per user and workspace configuration.

Configuration values can be stored in three locations:

• System wide configuration applies to all users on a given system.

• User configuration applies to the current user.

• Finally, workspace configuration applies only to the current workspace.

The values from these locations are merged (in the given order), i.e. the system configuration has the lowest priority and can be overridden by the user configuration which in turn can be overridden by the workspace configuration.

In addition to persistently set options in these configuration files, options also can be overridden by setting appropriate environment options. For example, to override the color_ui option, one can set the environment variable GIT_WS_COLOR_UI.

To interact with the configuration, a set of sub-commands are available. By default, these commands either operate on the merged configuration options or (in case of commands that modify configurations) on the configuration files from highest to lowest priority (i.e. if one runs such a command from within a workspace, the workspace configuration file is modified, otherwise, the user configuration file is written). This can be changed by using the options --system, --user or --workspace to read from or write to a specific file.

git ws config delete

Delete an option.

Usage: git-ws config delete [OPTIONS] OPTION

  Remove the OPTION from the configuration.

  This removes the specified option from the selected configuration file. If
  no configuration file is explicitly selected, this will operate on the
  workspace configuration if ran from within a workspace. Otherwise, this will
  operate on the user configuration.

Options:
  --system     Operate on system wide configuration.
  --user       Operate on user configuration.
  --workspace  Operate on workspace specific configuration.
  -h, --help   Show this message and exit.

This deletes the given option from the configuration such that the implicit default will be used instead:

# Delete the color_ui option:
git ws config delete color_ui

git ws config files

Get the location of the configuration files.

Usage: git-ws config files [OPTIONS]

  Show the location of the configuration files.

  This prints the location of the configuration files used. By default, all
  paths are shown. The selection can be reduced by appropriate commands.

Options:
  -f, --format [text|json]  The format to use for showing values.
  --system                  Operate on system wide configuration.
  --user                    Operate on user configuration.
  --workspace               Operate on workspace specific configuration.
  -h, --help                Show this message and exit.

This prints the locations of the configuration files. The location of these files are system dependent, so this command is useful to learn where to put configuration files on a concrete system:

git ws config files
## Should print something like:
# system: /etc/xdg/GitWS/config.toml
# user: /home/User/.config/GitWS/config.toml
# workspace: /home/User/Projects/my-workspace/.git-ws/config.toml

git ws config get

Read a single configuration option.

Usage: git-ws config get [OPTIONS] OPTION

  Get the value of a configuration OPTION.

  This prints the value of the specified option. If selected, the value of a
  specific configuration file will be read. Otherwise, the computed value of
  the configuration option is shown.

  The computed configuration value is created by merging the system, user and
  workspace configuration files in that order. On top, environment variables
  of the form GIT_WS_XXX (where XXX is the name of an option) can be used to
  override settings from the configuration files.

  Note that option also can be a user specific option from one of the
  configuration files that is not otherwise consumed by GitWS itself.

Options:
  --system                  Operate on system wide configuration.
  --user                    Operate on user configuration.
  --workspace               Operate on workspace specific configuration.
  -f, --format [text|json]  The format to use for showing values.
  -h, --help                Show this message and exit.

This reads and prints the value of the given configuration option.

git ws config get color_ui
## Should print e.g.:
# True

git ws config list

Read all configuration values.

Usage: git-ws config list [OPTIONS]

  List all configuration options.

  This prints all configuration options. If selected, only the options from a
  specific configuration file will be shown. Otherwise, the computed list of
  configuration values is shown.

  The computed  configuration is created by merging the system, user and
  workspace configuration files in that order. On top, environment variables
  of the form GIT_WS_XXX (where XXX is the name of an option) can be used to
  override settings from the configuration files.

  Note that the listing might contain extra arguments if specified in one of
  the configuration files.

Options:
  -f, --format [text|json]  The format to use for showing values.
  --system                  Operate on system wide configuration.
  --user                    Operate on user configuration.
  --workspace               Operate on workspace specific configuration.
  -h, --help                Show this message and exit.

This reads and prints all configuration options, including a short description for each option:

git ws config list
## Should print something like:
# # The path (relative to the project's root folder) to the manifest file.
# manifest_path = git-ws.toml
#
# # If set to true, the output the tool generates will be colored.
# color_ui = True
#
# # The groups to operate on.
# groups

git ws config set

Set a configuration option.

Usage: git-ws config set [OPTIONS] OPTION VALUE

  Set the configuration OPTION to the given VALUE.

  This sets an option to the given value. If no specific configuration file is
  selected, then this will update the workspace configuration if run from
  within a workspace. Otherwise, the user configuration will be updated.

Options:
  --system          Operate on system wide configuration.
  --user            Operate on user configuration.
  --workspace       Operate on workspace specific configuration.
  --ignore-unknown  Set the option, even if it is not known to the
                    application. Note that this bypasses any type checking.
  -h, --help        Show this message and exit.

This command sets the given option to the specified value. By default, if an unknown option is given, the command terminates with an error. Using the --ignore-unknown option, writing any option can be enforced.

# Setting a standard option:
git ws config set color_ui True

## Setting a custom option requires a special flag:
git ws config set --ignore-unknown my_option "Hello world!"