Configuration¶

Package installation settings¶

The general settings and a list of repositories are defined in a YAML config file (default ~/.config/girsh_config.yaml). It can be created from template using the "--edit" option.

The configuration file should have the following structure:

girsh_config.yaml

general:
  # Optional: Base folder where binaries will be installed.
  # For non-root users, this should usually be "~/.local/bin"
  bin_base_folder: "/usr/local/bin"

  # Optional: Path to the cache file where installed versions and binary names
  # are stored. If not provided, it defaults to "~/.cache/girsh/girsh.yaml"
  installed_file: "/home/your_username/.installed/girsh/girsh.yaml"

  # Optional: Path to the download folder.
  # If not provided, it defaults to "~/.installed/girsh/downloads"
  download_dir: Path = "/my/custom/bin"

  # Optional: Regex pattern to select the release asset, defaults to ".*x86_64.*(gz|zip)$"
  package_pattern: ".*aarch64.*(gz|zip)$"

  # Optional: Package base folder (for multi-file packages)
  # If not provided, it defaults to "~/.local/share/girsh" or "/opt/girsh"
  package_base_folder: "/my/Packages"

  # Optional: proxy settings, can be overwritten with `--proxy` command line argument.
  proxy: proxy.example.com:8080

repositories:
  # Dictionary of git repositories from which the released binary should be installed
  owner/repository-name:
    # Optional: Comment about the installed package
    comment: This is an interesting tool
    # Optional: Regex pattern to select the release asset, defaults to ".*(gz|zip)"
    package_pattern: str = ".*amd_64.*gz"
    # Optional: Regex pattern to filter the extracted files to identify the binary.
    # Optional: Regex pattern to filter the extracted files to identify the binary.
    # If the same file name is present in multiple folders, include a (sub-)path.
    filter_pattern: "bin/my_binary$"
    # Optional: Renaming rule. If provided, the matching binary will be renamed
    # to this name before installation.
    binary_name: "my-renamed-binary"
    # Optional: Pin to specific version (git tag)
    version: v0.41.2
    # Optional: Release URL to fetch the latest release information. If not provided, it defaults to the GitHub API URL for the repository's latest release.
    release_url: https://update.code.visualstudio.com/api/releases/stable
    # Optional: Release payload pattern to extract the version from the release URL response
    version_pattern: ^\["([\d\.]+)"
    # Optional: Flag that the packe is not a single binary
    multi_file: true
    # Optional: Pre-update/uninstall commands
    pre_update_commands:
      - echo "Pre-update command 1"
      - "%confirm_default_no% Continue to install?"
      - "%stop_processes% my-renamed-binary"
    # Optional: Post-install/update commands
    post_update_commands:
      - echo "Post-update command 1"
      - echo "Post-update command 2"
    # Optional: Download URL template using `{version}` as a placeholder for the release tag
    download_url: https://package/download/{version}/linux-x64/stable

Custom Release Sources¶

By default, girsh fetches release information from GitHub's API. However, some projects may host their releases on different platforms or provide custom APIs. You can configure girsh to fetch release information from a custom URL by setting release_url and version_pattern.

release_url: The URL to fetch release information from. This should return a response (typically JSON or plain text) containing version information.
version_pattern: A regular expression pattern to extract version strings from the response. The pattern should capture the version in a group. girsh will sort the matched versions lexicographically and select the latest one.

Example for a custom API that returns a JSON array of versions:

release_url: https://api.example.com/releases
version_pattern: "([0-9]+\.[0-9]+\.[0-9]+)"

When both release_url and version_pattern are provided, girsh will use these instead of the GitHub API to determine the latest version.

Commands¶

Option to continue in case of failure¶

By default the installation or update for a repository will fail if one of the defined commands returns non-zero exit code. If the command is prefixed with a |, then errors for this command are ignored.

Example: |sh -c 'exit 42'

Option to run command in a shell¶

By default the command is executed as command sequence. If a shell is required, e.g. for using pipes or conditions, it can be enabled with the prefix *.

Example: *zellij kill-all-sessions || echo done

This option can be combined with the "continue on failure":

Example: |*my_command | grep dummy

Comments¶

Commands can be disabled as comment using # prefix, also within an explicit string.

Example:

pre_update_commands:
  -  #echo "Pre-update command 1"
  - "#%confirm_default_no% Continue to install?"

Macros¶

The pre- and post-update commands also support some macros. Macro commands must be at the beginning of the command string and are encapsulated with %, e.g. %my_macro%. The string after the macro command name is passed to the macro function and must be separated by one space from the macro command.

If the macro returns False, the command execution and further processing of the related repository is cancelled with an error.

Supported macros:
- %confirm_default_yes%
  - Prompts the user with a yes/no question and returns True if the user doesn't explicitly answers "n" (no).
  - Argument: Question string.
  - Example: %confirm_default_yes% Install program?
- %confirm_default_no%
  - Prompts the user with a yes/no question and returns True if the user explicitly answers "y" (yes).
  - Argument: Question string.
  - Example: %confirm_default_no% Kill program?
- %stop_processes%
  - Terminate all running processes for of given program.
  - Argument: program name
  - Example: %stop_processes% my_program