### Version Overrides Style Guide

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

This example demonstrates the recommended structure for version overrides, prioritizing clarity and ease of updates over excessive DRY principles.

```yaml
# Define only settings which don't depend on versions.
# e.g. repo_owner, repo_name, description.
version_constraint: "false"
version_overrides:
  - version_constraint: semver("<= 3.0.0")
    # Oldest setting
    # ...
  - version_constraint: semver("<= 4.0.0")
    # ...
  - version_constraint: semver("<= 5.0.0")
    # ...
  - version_constraint: "true"
    # Latest setting
    # ...
```

--------------------------------

### Install Development Tools with aqua

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Installs development tools for aqua-registry using the aqua CLI. Ensure aqua is installed and configured.

```sh
aqua i -l
```

--------------------------------

### Check Docker Installation

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Verifies that the Docker command is installed and working correctly. This is a prerequisite for running tests in containers.

```sh
docker version
```

--------------------------------

### Auto-generate Tool Package Example

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

An example of using `argd s` to auto-generate code for a tool package named `cli/cli`.

```sh
argd s cli/cli
```

--------------------------------

### Rust Platform Replacements (Recommended)

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

For Rust packages, prefer 'musl' for Linux and 'msvc' for Windows if both are supported, as shown in this example.

```yaml
replacements:
  linux: unknown-linux-musl
  windows: pc-windows-msvc
```

--------------------------------

### Select package type order

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

When choosing a package type, follow this order of preference: github_release, github_content, github_archive, http, go_install, go_build. For example, use github_release over http for GitHub Releases.

```text
1. github_release
1. github_content
1. github_archive
1. http
1. go_install
1. go_build
```

--------------------------------

### Filter Versions by Prefix in Registry Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Example of filtering versions by specifying a `version_prefix` in `aqua-generate-registry.yaml`. This example targets versions under the 'cmd/protoc-gen-go-grpc/' path.

```yaml
name: grpc/grpc-go/protoc-gen-go-grpc
version_prefix: cmd/protoc-gen-go-grpc/
```

--------------------------------

### Example of cmdx new failing to push

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/troubleshooting.md

This example shows the error message when `cmdx new` fails to push a commit because the `origin` remote is not set to the user's fork.

```console
$ cmdx new pre-commit/pre-commit
# ...
+ git push origin feat/pre-commit/pre-commit
remote: Permission to aquaproj/aqua-registry.git denied to ***.
fatal: unable to access 'https://github.com/aquaproj/aqua-registry/': The requested URL returned error: 403
```

--------------------------------

### Install Prettier Globally

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Installs the Prettier code formatter globally using npm. This is a requirement for formatting YAML files in the aqua-registry project.

```sh
npm i -g prettier
```

--------------------------------

### Verify package with argd t

Source: https://github.com/aquaproj/aqua-registry/blob/main/GEMINI.md

Before submitting a Pull Request, verify the package installation using `argd t <package>`. Include the command and a snippet of its output in the PR description to provide evidence of testing.

```sh
argd t <package>
```

--------------------------------

### Example of New Style Version Constraints

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/guide.md

Illustrates the modern format for version constraints and overrides in Aqua registry configurations. Use this style for new or updated package definitions.

```yaml
version_constraint: "false" # Root version_constraint is "false"
version_overrides:
  - version_constraint: semver("<= 0.1.0") # Version constraints use <, <= not >, >= (basically <=)
    # ...
  # ...
  - version_constraint: "true" # End with "true" for latest version configuration
    # ...
```

--------------------------------

### Execute Package in Linux Container via `argd con`

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/run_tool.md

Use this command to connect to a Linux container and execute packages within it. Ensure you have `argd` installed and configured.

```console
$ argd con
+ bash scripts/connect.sh
[INFO] Connecting to the container aqua-registry (linux/arm64)
```

--------------------------------

### Filter Versions by Regex in Registry Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Example of filtering versions using `version_filter` in `aqua-generate-registry.yaml`. This example excludes versions that start with 'varcon-'.

```yaml
name: crate-ci/typos
version_filter: not (Version startsWith "varcon-")
```

--------------------------------

### Filter Assets in Registry Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Example of filtering assets using `all_assets_filter` in `aqua-generate-registry.yaml`. This example excludes assets containing 'rollouts-controller' or 'rollout-controller'.

```yaml
name: argoproj/argo-rollouts
all_assets_filter: not ((Asset matches "rollouts-controller") or (Asset matches "rollout-controller"))
```

--------------------------------

### Test Multiple Package Versions

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/pkg_yaml.md

When a package has `version_overrides`, include both the latest and older versions in `pkg.yaml` to ensure proper installation of older versions.

```yaml
packages:
  - name: scaleway/scaleway-cli@v2.12.0
  - name: scaleway/scaleway-cli
    version: v2.4.0
```

--------------------------------

### Remove Installed Package from Containers

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Removes a specific installed package and its associated checksums from the containers. This is helpful for testing package installations in isolation.

```sh
argd rmp [<package>]
```

--------------------------------

### Format Package YAML Files with Prettier

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Formats YAML files within the `pkgs/<package name>/` directory using Prettier. This command requires Prettier to be installed globally.

```sh
prettier -w pkgs/<package name>/*.yaml
```

--------------------------------

### Remove Containers

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Removes all containers used by `argd` for scaffolding and testing. This is useful for starting with a clean environment.

```sh
argd rm
```

--------------------------------

### List Assets for a Repository and Version

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/error_handling.md

Use `argd lsa` to list available assets for a given repository and version. This is helpful when troubleshooting missing assets.

```bash
$ argd lsa suzuki-shunsuke/pinact v3.0.0
multiple.intoto.jsonl
pinact_3.0.0_checksums.txt
pinact_3.0.0_checksums.txt.pem
pinact_3.0.0_checksums.txt.sig
pinact_darwin_amd64.tar.gz
pinact_darwin_arm64.tar.gz
pinact_linux_amd64.tar.gz
pinact_linux_arm64.tar.gz
pinact_windows_amd64.zip
pinact_windows_arm64.zip
```

--------------------------------

### Initialize Aqua Registry Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Use this command to create an initial `aqua-generate-registry.yaml` file for a specified package name.

```sh
aqua gr --init <package name>
```

--------------------------------

### Initialize Custom Configuration File

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Generate a template configuration file named `aqua-generate-registry.yaml` for `argd s` customization. This is the first step before modifying the configuration.

```sh
aqua gr -init <package name>
```

--------------------------------

### Scaffold new packages with argd

Source: https://github.com/aquaproj/aqua-registry/blob/main/GEMINI.md

Use the `argd s` command to scaffold new packages, especially for `github_release` and `cargo` types. This ensures proper generation of configuration files, avoiding manual errors and ensuring support for various versions and platforms.

```sh
argd s "<owner>/<repo>"      # e.g. argd s cli/cli
```

```sh
argd s -l 1 "<package>"
```

--------------------------------

### Rust Platform Replacements (Avoid)

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Avoid using 'gnu' for Linux and Windows platform replacements if 'musl' or 'msvc' are available.

```yaml
replacements:
  linux: unknown-linux-gnu
  windows: pc-windows-gnu
```

--------------------------------

### Scaffold and Test Package Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Scaffolds configuration files (`registry.yaml`, `pkg.yaml`) for a given package and tests them in containers. It uses GitHub Releases data and can be time-consuming if a repository has many releases.

```sh
argd s [-c <config file path>] [-B] [-cmd <command name>] <package name>
```

--------------------------------

### Display argd Help Information

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Shows the help message for the `argd` command-line tool, which is used for various development tasks in aqua-registry.

```sh
argd help
```

--------------------------------

### Scaffold GitHub Release or Cargo Packages

Source: https://github.com/aquaproj/aqua-registry/blob/main/CLAUDE.md

Use the `argd s` command to scaffold new packages for GitHub releases or Cargo. This command helps generate initial configuration files, preventing manual errors and ensuring compatibility with older versions and uncommon platforms.

```sh
argd s "<owner>/<repo>"      # e.g. argd s cli/cli
```

--------------------------------

### Generate Package with Custom Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Run `argd s` with a custom configuration file (`aqua-generate-registry.yaml`) to generate package code. This command respects the filters defined in the configuration file.

```sh
argd s -c aqua-generate-registry.yaml
```

--------------------------------

### Scaffold Other Package Types

Source: https://github.com/aquaproj/aqua-registry/blob/main/CLAUDE.md

For package types other than GitHub release or Cargo, use `argd s -l 1` to generate a stub configuration. This is recommended over manual creation to ensure comprehensive coverage of versions and platforms.

```sh
argd s -l 1 "<package>"
```

--------------------------------

### Allow Local Registry Policy

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/run_tool.md

Before executing packages using local definitions or configurations, you must allow the local registry policy. Run this command in your terminal.

```sh
aqua policy allow
```

--------------------------------

### Generate Tool Package with Custom Configuration

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

When the default auto-generation is insufficient, use this command to generate code with a custom configuration file. This allows fine-tuning of version and asset filtering.

```sh
argd s -c "<configuration file>" "<package name>"
```

--------------------------------

### Generate Template for Unsupported Package Types

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

For package types other than `github_release` and `cargo`, use the `-l 1` flag to generate only a template. You will need to manually complete the configuration.

```sh
argd s -l 1 "<package name>"
```

--------------------------------

### Avoid Short Syntax for Old Versions

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/pkg_yaml.md

Do not use the short syntax `<package name>@<version>` for old versions in `pkg.yaml` to prevent the `aqua-registry-updater` from automatically updating them.

```yaml
packages:
  - name: scaleway/scaleway-cli@v2.12.0
  - name: scaleway/scaleway-cli
    version: v2.4.0
```

```yaml
packages:
  - name: scaleway/scaleway-cli@v2.12.0
  - name: scaleway/scaleway-cli@v2.4.0
```

--------------------------------

### Configure Global Config with aqua-all.yaml

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/run_tool.md

Set the `$AQUA_GLOBAL_CONFIG` environment variable to include `aqua-all.yaml` from the current directory. This allows execution of all packages defined in `aqua-all.yaml`.

```sh
export AQUA_GLOBAL_CONFIG=$PWD/aqua-all.yaml:$AQUA_GLOBAL_CONFIG
```

--------------------------------

### Import Package Definition in aqua.yaml

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/run_tool.md

Import a package's definition file (`pkg.yaml`) into your `aqua.yaml` to make it available for execution. This method is for local development and should not be committed.

```yaml
packages:
  # ...
  - import: pkgs/<package>/pkg.yaml
```

--------------------------------

### Lint Package Definitions with Conftest

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/lint.md

Use this command to lint all `pkg.yaml` and `registry.yaml` files within a specific package directory. This is useful after creating or updating package definitions.

```sh
conftest test --combine pkgs/suzuki-shunsuke/pinact/*
```

--------------------------------

### Connect to a Container

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Connects to a specified container using `docker exec`. This is useful for debugging issues within the containerized environment where tests are run. Defaults to Linux and the host's architecture.

```sh
argd con [<os>] [<arch>]
```

--------------------------------

### List GitHub Release Assets

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Lists the asset names for a specific GitHub Release of a given repository and version. This is helpful for diagnosing problems with asset name matching in package configurations.

```sh
argd lsa <owner/repo> <version>
```

--------------------------------

### Ensure Packages are Not Empty

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/pkg_yaml.md

Packages in `pkg.yaml` should not be empty. An empty `packages` list can occur if version fetching fails.

```yaml
packages: []
```

--------------------------------

### Cargo package naming convention

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

For crates hosted on crates.io, the recommended package name format is crates.io/<crate name> to ensure compatibility with aqua commands.

```text
crates.io/<crate name>
```

--------------------------------

### Auto-generate Tool Package

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

Use this command to auto-generate the code for a new tool package. It supports `github_release` and `cargo` types by default.

```sh
argd s "<tool name>"
```

--------------------------------

### Use aliases for compatibility

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Use aliases only for maintaining compatibility, typically when a package repository is transferred. Search words can be added for easier package discovery.

```yaml
name: kubernetes-sigs/controller-tools/controller-gen
search_words:
  - kubebuilder
```

--------------------------------

### Search for existing PRs

Source: https://github.com/aquaproj/aqua-registry/blob/main/GEMINI.md

Before opening a new Pull Request, search for existing PRs related to the package to avoid duplicates. This command uses the GitHub CLI to list PRs for the specified repository.

```sh
gh pr list --repo aquaproj/aqua-registry --search "<package>" --state all
```

--------------------------------

### Do not add .exe to .files[].name on Windows

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

On Windows, the .exe extension is appended by default. Avoid explicitly adding .exe to the file name.

```yaml
files:
  - name: pinact
```

```yaml
files:
  - name: pinact.exe
```

--------------------------------

### Trim Spaces in Description

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Descriptions should not have leading or trailing spaces. Use this format for trimming.

```yaml
description: A command-line tool that makes git easier to use with GitHub
```

```yaml
description: "  A command-line tool that makes git easier to use with GitHub  "
```

--------------------------------

### Omit .exe when src is .exe

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

When the source file already has the .exe extension, omit it from the 'src' attribute to avoid duplication.

```yaml
files:
  - name: pinact
```

```yaml
files:
  - name: pinact
    src: pinact.exe
```

--------------------------------

### Lint Package YAML Files

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Lints the `pkg.yaml` and `registry.yaml` files for packages using `conftest`. This ensures adherence to defined standards.

```sh
conftest test pkgs/<package name>/*.yaml
```

--------------------------------

### Use `overrides` instead of `format_overrides`

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

The 'overrides' field should be used for platform-specific format adjustments instead of the deprecated 'format_overrides'.

```yaml
format: tar.gz
overrides:
  - goos: windows
    format: zip
```

```yaml
format: tar.gz
format_overrides:
  - goos: windows
    format: zip
```

--------------------------------

### Specify Command Name in registry.yaml

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/error_handling.md

When the command name differs from the package name, explicitly define the `name` in the `files` configuration within `registry.yaml`.

```yaml
files:
  - name: gh
```

--------------------------------

### Check git remote repositories

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/troubleshooting.md

Use this command to check the current remote repositories configured for your local git repository.

```sh
git remote -v
```

--------------------------------

### Update registry.yaml

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Merges all `registry.yaml` files from the `pkgs/**/` directories and updates the main `registry.yaml` in the repository. This command should be run after modifying individual package registry files.

```sh
argd gr
```

--------------------------------

### Specify Command Source Path in registry.yaml

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/error_handling.md

If the command executable is located in a subdirectory within an archive, specify its relative path using the `src` field in the `files` configuration.

```yaml
files:
  - name: gh
    src: gh_{{trimV .Version}}_{{.OS}}_{{.Arch}}/bin/gh
```

--------------------------------

### Test Package in Containers

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/tool.md

Tests a specified package within containers. If the current branch is named `feat/<package name>`, the package name can be omitted. Successful tests update the `registry.yaml` file.

```sh
argd t [<package name>]
```

--------------------------------

### YAML Language Server Comment

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

A YAML language server comment is necessary at the top of pkgs/**/registry.yaml files to enable schema validation.

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/aquaproj/aqua/main/json-schema/registry.json
```

--------------------------------

### Regenerate Package Code for Latest Version

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/guide.md

Command to regenerate package code for the latest version. Useful when updating existing packages or when auto-generation is needed for specific package types.

```sh
aqua gr -l 1 "<package name>"
```

--------------------------------

### Add upstream remote

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/troubleshooting.md

Use this command to add the `upstream` remote, pointing to the original `aquaproj/aqua-registry` repository. This is useful for pulling changes from the main repository.

```sh
git remote add upstream https://github.com/aquaproj/aqua-registry
```

--------------------------------

### Remove Spaces in Template Delimiters

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Ensure there are no spaces within the template delimiters {{ and }}.

```yaml
asset: tfcmt_{{.OS}}_{{.Arch}}.tar.gz
```

```yaml
asset: tfcmt_{{ .OS }}_{{ .Arch }}.tar.gz
```

--------------------------------

### Omit `files[].src` when `format` is `raw`

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

If the 'format' is set to 'raw', the 'src' field within 'files' is not required and should be omitted.

```yaml
format: raw
files:
  - name: swagger
```

```yaml
format: raw
files:
  - name: swagger
    src: swagger_{{.OS}}_{{.Arch}} # unneeded
```

--------------------------------

### Omit .files[].src if same as .files[].name

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

If the source file name is the same as the target file name, you can omit the 'src' attribute.

```yaml
files:
  - name: pinact
```

```yaml
files:
  - name: pinact
    src: pinact
```

--------------------------------

### Avoid Conditional Statements in Templates

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Refrain from using 'if' or 'for' statements directly within template definitions for assets.

```yaml
asset: foo.{{.Format}}
format: tar.gz
overrides:
  - goos: windows
    format: zip
```

```yaml
asset: 'foo.{{if eq .GOOS "windows"}}zip{{else}}tar.gz{{end}}'
```

--------------------------------

### Omit repo_owner and repo_name when redundant

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

When repo_owner and repo_name are explicitly set, you can omit them if they are redundant with the package's repository.

```yaml
repo_owner: weaveworks
repo_name: eksctl
```

```yaml
repo_owner: weaveworks
repo_name: eksctl
name: weaveworks/eksctl
link: https://github.com/weaveworks/eksctl
files:
  - name: eksctl
```

--------------------------------

### Fix git remote URL

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/troubleshooting.md

Use this command to change the URL of the `origin` remote to your fork of the repository. Replace `<your fork>` with your GitHub username.

```sh
git remote set-url origin https://github.com/<your fork>
```

--------------------------------

### Delete Generated Branch

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/add_package.md

If you need to retry the `argd s` command and have already generated a branch, use these commands to delete the old branch before generating a new one. This is safe before submitting a Pull Request.

```sh
git checkout main
git branch -D "feat/<package name>"
```

--------------------------------

### Remove Trailing Characters from Description

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Avoid using characters like '.' at the end of a description.

```yaml
description: A command-line tool that makes git easier to use with GitHub
```

```yaml
description: A command-line tool that makes git easier to use with GitHub.
```

--------------------------------

### Clone and update upstream aqua repository

Source: https://github.com/aquaproj/aqua-registry/blob/main/GEMINI.md

Clone the upstream `aqua` repository to have offline access to its documentation and schemas. This is useful for referencing registry configuration fields and JSON schemas.

```sh
mkdir -p .ai
if [ ! -d .ai/aqua ]; then
  git clone https://github.com/aquaproj/aqua .ai/aqua
fi
git -C .ai/aqua pull origin main
```

--------------------------------

### Avoid Emojis in Descriptions

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Descriptions should not contain emojis to prevent rendering issues in various environments.

```yaml
description: CLI and Go library for CODEOWNERS files
```

```yaml
description: 🔒 CLI and Go library for CODEOWNERS files
```

--------------------------------

### Disable Checksum Verification in Aqua Registry

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/error_handling.md

Use this configuration to disable checksum verification when the checksum file is incorrect or when checksums are not needed. This setting controls whether Aqua downloads and verifies checksum files.

```yaml
checksum:
  enabled: false
```

--------------------------------

### Remove Unneeded Quotes from Strings

Source: https://github.com/aquaproj/aqua-registry/blob/main/docs/registry_yaml.md

Avoid unnecessary quotes around string values in the YAML.

```yaml
description: A command-line tool that makes git easier to use with GitHub
```

```yaml
description: "A command-line tool that makes git easier to use with GitHub"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.