g2

A comprehensive, multifaceted command-line toolkit for Gentoo Linux overlays and package management.

Project overview

g2 is a powerful suite of tools built to assist developers and maintainers in working with Gentoo packages, overlays, and metadata efficiently. Designed initially for personal use, it has evolved into a robust project capable of generating static HTML sites representing repository dashboards, indexing packages for rapid client-side search, managing Manifests and checksums automatically, and applying linting checks to ensure code quality within the ebuild ecosystem.

It streamlines workflows by automating repetitive repository administration tasks—like dependency resolution, pkg_desc_index generation, and USE flag documentation parsing.

Useful links

Repository: https://github.com/arran4/g2
Go package docs: https://pkg.go.dev/github.com/arran4/g2

Installation

Building from source requires Go 1.26 or later. Published release binaries do not require a Go installation.

go install github.com/arran4/g2/cmd/g2@latest

Quick start

Generate a local static site for your overlay:

g2 overlay site generate -out my_site_dir .
g2 site serve -port 8080 .

Verify ebuild Manifests:

g2 manifest verify .

Modules & Commands

`manifest`

The manifest command group handles operations related to Manifest files.

Usage:

g2 manifest <subcommand> [flags]

Subcommands:

`upsert-from-url`

Updates or inserts a Manifest entry for a file downloaded from a URL. This command streams the file, calculates the specified checksums, and updates the Manifest file in the specified directory (or specific file path).

Usage:

g2 manifest [flags] upsert-from-url <url> <filename> <manifestFileOrDir>

Arguments:

<url>: The HTTP/HTTPS URL of the file to download.
<filename>: The filename to record in the Manifest (typically the distfile name).
<manifestFileOrDir>: The path to the Manifest file or the directory containing it (e.g., the ebuild directory).

Flags:

-blake2b (default: true): Calculate BLAKE2B checksum.
-blake2s (default: false): Calculate BLAKE2S checksum.
-md5 (default: false): Calculate MD5 checksum.
-rmd160 (default: false): Calculate RMD160 checksum.
-sha1 (default: false): Calculate SHA1 checksum.
-sha256 (default: false): Calculate SHA256 checksum.
-sha3_256 (default: false): Calculate SHA3-256 checksum.
-sha3_512 (default: false): Calculate SHA3-512 checksum.
-sha512 (default: true): Calculate SHA512 checksum.

Example:

To download a package, calculate SHA256 in addition to defaults, and update the Manifest in the current directory:

g2 manifest -sha256=true upsert-from-url https://example.com/software-1.0.tar.gz software-1.0.tar.gz .

`verify`

Verifies the Manifest against the actual ebuild files.

--fix: Fetches/checksums missing DIST entries and commits only after all prerequisite work succeeds.
--clean: Removes obsolete DIST entries as part of the same authoritative reconciliation when source resolution is complete.

Uncertain/incomplete source resolution causes destructive reconciliation (like --clean and --fix overwriting entries) to be refused without rewriting the Manifest.

Usage:

g2 manifest verify [--fix] [--clean] [location]

`clean`

Cleans up unused entries from the Manifest file, safely skipping directories containing any ebuild with incomplete or external sources (e.g., eclasses).

Usage:

g2 manifest clean [location]

`metadata`

Commands relating to modifying metadata.xml files.

Usage:

g2 metadata [flags] [location]

Flags:

-force: Force overwrite if type mismatches or other errors
-l, -longdescription <string>: Set long description
-m, -maintainer, -maintainer-add <email[:name[:type]]>: Add/Update maintainer
-maintainer-remove <email>: Remove maintainer
-u, -upstream-id, -upstream-add <type:id>: Add upstream remote ID
-upstream-remove <type:id>: Remove upstream remote ID
-use, -use-add <name:description>: Add/Update USE flag
-use-remove <name>: Remove USE flag

Example Usage:

Add a maintainer to metadata.xml:

g2 metadata -maintainer-add "dev@example.com:Developer Name:person" .

Add a USE flag description:

g2 metadata -use-add "custom-flag:Enables a custom feature" .

`ebuild`

Tools for working with .ebuild files.

Usage:

g2 ebuild <subcommand>

Subcommands:

init <template_name>: Initialize an ebuild from a template.
templates: Manage ebuild templates.
sh-parse-to-json <ebuild_file>: Parse an ebuild using the shell parser and output JSON.
as-json <ebuild_file>: Parse an ebuild using the native parser and output JSON.
explain <ebuild_file>: Output a human-readable summary of an ebuild.
check <ebuild_file>: A lightweight structural validator for ebuild files (alias: lint).
deps <ebuild_file>: Extract and format dependency fields.
query <ebuild_file> --key <key> [--format lines]: Query specific fields from a parsed ebuild.
check-exists <ebuildDir> <version>: Determine if any revision of a given version exists, returning exit code 0 if found and 1 if not.
next-revision [--inspect <new_ebuild_file>] <ebuildDir> <version>: Generate the next revision name and optionally inspect contents for changes.

Example Usage:

Query a specific field from an ebuild:

g2 ebuild query my-package-1.0.ebuild --key SRC_URI --format lines

Parse an ebuild natively into JSON format:

g2 ebuild as-json my-package-1.0.ebuild

Initialize a new ebuild from the generic template:

g2 ebuild init generic my-new-package-1.0.ebuild

`overlay site generate`

Generates a static site for a single overlay.

Usage:

g2 overlay site generate [-out <dir>] [-clear] [<location>]

Arguments:

<location>: Path to the overlay directory, or a Git URL (defaults to .).

Flags:

-out: Output directory for the generated site (default: site_out).
-clear: Clear output directory before generation.
-fast-git-modtime: Use fast (O(1)) but potentially less reliable go-git file log lookup.
-recent-duration: Duration to consider an update 'recent' (e.g., 3mo, 14d, 72h) (default "3mo").

When the overlay contains news items, the generated news dashboard includes RSS 2.0 and Atom feeds at news/index.rss and news/index.atom. Aggregated sites also provide combined feeds there, while each repository has its own feeds under repos/<repository>/news/.

Example:

g2 overlay site generate -out my_site_dir .

`overlay ebuild`

Tools to modify the overlay with ebuilds.

Usage:

g2 overlay ebuild <subcommand>

Subcommands:

move [--date YYYY-MM-DD] <from> <to>: Record a package move in profiles/updates.
slotmove [--date YYYY-MM-DD] <package> <from> <to>: Record a slot move in profiles/updates.
install [-category <string>] <ebuild.ebuild> [overlay_path] [-- <files...>]: Install an ebuild into the overlay, optionally providing a specific category or additional files for the files/ directory. Automatically triggers manifest, cache, use desc, and pkg_desc_index generation.

Example:

Install a package into a specific category with some files:

g2 overlay ebuild install -category sys-apps my-app-1.0.ebuild . -- app.conf app.service

`overlays site generate`

Generates an aggregated static site for multiple remote repositories from a repositories.xml file.

Usage:

g2 overlays site generate [-out <dir>] [-clear] <repositoriesFile>

Arguments:

<repositoriesFile>: Path or URL to a Gentoo repositories.xml file, or - for stdin.

`site serve`

Serves the generated static site locally for previewing.

Usage:

g2 site serve [-port <int>] [path_to_overlay]

Example:

g2 site serve -port 8080 .

`lint`

Checks the repository for errors such as ebuild IUSE variables missing in metadata.xml, missing md5-cache files, orphaned Manifest entries, and invalid repository layout.

Usage:

g2 lint [flags] [<location>] [<target_package>...]

Subcommands:

g2 lint list: Lists all available lint rules.
g2 lint repo [flags] [<location>]: Lints an entire repository.
g2 lint package [flags] [<location>] <target_package>...: Lints specific packages or categories.
g2 lint query [flags] [<location>] <query>: Lints packages matching a query (e.g. '>=app-misc/foo-v3::guru').

Flags:

-enable-layout-lint: Enable repository layout linting (checks for stray files, unlisted categories, honoring .g2igno 10BC8 re).
-allow-github-api: Allow fetching upstream Gentoo categories via GitHub API for layout linting.
-upstream-repo-path <path>: Path to upstream repository on disk for layout linting (overrides GitHub API).
-format <string>: Output format: text, json, or github-actions (default text).
-severity <string>: Only show warnings of this severity (error, warning, notice, info).
-fail-severity <string>: Fail on this severity and worse (error, warning, notice, info, default warning).
-only-source <string>: Only show warnings from this source (g2, pkgcheck).
-only-tag <string>: Only show warnings with this tag.
-disable-rule <string>: Comma-separated list of rule IDs to ignore (case-insensitive).
-ignore-tag <string>: Comma-separated list of tags to ignore.

Example:

g2 lint /var/db/repos/my-overlay
g2 lint --enable-layout-lint .
g2 lint package . app-misc/foo
g2 lint query '>=app-misc/foo-1.0'

`use`

Manage and discover USE flags, use.desc, and use.local.desc.

Usage:

g2 use <subcommand>

Subcommands:

discover [location]: Discover USE flags from ebuilds and metadata.xml to regenerate use.desc, use.local.desc, and metadata.xml.
desc-add <name> <description>: Add a USE flag description to use.desc.
desc-remove <name>: Remove a USE flag description from use.desc.
desc-edit <name> <description>: Edit a USE flag description in use.desc.
desc-list: List all USE flag descriptions from use.desc.
local-desc-add <pkg> <name> <description>: Add a USE local flag description to use.local.desc.
local-desc-remove <pkg> <name>: Remove a USE local flag description from use.local.desc.
local-desc-edit <pkg> <name> <description>: Edit a USE local flag description in use.local.desc.
local-desc-list: List all USE local flag descriptions from use.local.desc.

Example Usage:

Discover and populate USE flags automatically:

g2 use discover .

List all local USE descriptions:

g2 use local-desc-list

`cache`

Manage md5-dict cache files.

Usage:

g2 cache <subcommand>

Subcommands:

verify: Verify complete supported metadata/md5-cache entries.
generate [target-packages...]: Generate complete supported cache entries. Optionally specify package atoms to only generate cache for them.
set-method <method>: Set the cache method in layout.conf.
list-methods: List available cache methods.
clean [location]: Clean up unused cache entries.
reconcile: Generate, conservatively clean, then verify cache entries.

generate, verify, and reconcile accept --mode=ci (the default) or --mode=strict, --repo=PATH, --master-repo=name=PATH[,name=PATH], and --repos-conf=PATH. CI mode uses only the repository and master repositories supplied through those options. A required eclass that could only be in an unavailable declared master is reported as a skipped check by verification; ordinary repository read, parse, and eclass-read failures are errors. Supply all declared masters to make CI verification complete. Strict mode resolves declared masters through the supplied repos.conf (or the system Portage configuration) and fails if required context cannot be established.

Cache entries contain supported parsed metadata, the ebuild MD5, and the transitive _eclasses_ closure resolved through the repository stack. A successful verification has checked every required entry. “Completed with explicitly skipped checks” means CI could not establish the named master context; it is not full verification. The parser does not execute ebuilds, so metadata it cannot reliably derive is treated as an error rather than silently accepted as canonical. In particular, eclasses which contribute cache variables or contain unresolved cache-variable expressions require Portage evaluation. When authoritative INHERITED evaluation is available, it drives local repository/master eclass hashing without static semantic interpretation.

Dynamic evaluation is achieved by invoking portageq metadata / ebuild <category/package-pvr::repo-name> <keys...>, which requires the repository to be properly qualified and an active Portage profile to be configured on the host. In CI mode, missing evaluation context yields an explicit skipped/unverified behavior, while in strict mode it causes a failure. Actual evaluation, configuration, or repository failures result in errors across both modes.

IDEPEND is fully supported.

Optional real-Gentoo acceptance procedure

A manual validation procedure is supported for executing on an authentic Gentoo host:

Ensure the target repository is registered in Portage under its declared repo-name, with masters available.
Select an active profile.
Choose a representative dynamic ebuild, e.g. using llvm_gen_dep.
Optionally run portageq metadata / ebuild <category/package-pvr::repo-name> BDEPEND IDEPEND INHERITED ... and confirm materialized values natively.
Execute g2 cache generate --mode=strict for the specific repository/package context.
Run g2 lint.
Run strict cache verification against the same context (g2 cache verify --mode=strict).
Re-run generation/verification unchanged to verify idempotency.

Pass Criteria:

No raw $(...) survives within canonical dependency metadata.
Dynamic BDEPEND/IDEPEND values are appropriately materialized.
Authoritative INHERITED yields the correct eclass hashes.
Lint successfully accepts the generated cache.
Verify accurately reports the generated entry as matching.
Repeated execution performs no cache mutations.

Limitations and Future Scope (Issue #564)

The initial phase of Portage-backed cache evaluation currently implements the isolated generation boundaries. The following features remain scoped for future implementation:

Active-profile applicability, including broader master/eclass precedence and transitive inheritance coverage.
Full metadata drift and reconcile coverage.
Automation of the optional real-Gentoo acceptance procedure (if acceptance automation replaces the manual process).
Propagation across all CLI boundaries: Integrating the evaluation boundary beyond only the initial cache metadata layer (see #557).
INHERIT canonical serialization: Depending on design, INHERIT serialization behavior (currently intentionally ignored in serialization output) might require adjustments.

Example:

Generate the ebuild cache for the current overlay: g2 cache generate parses and statically evaluates repository ebuilds into md5-dict entries. The process fails-closed for correctness: literal list multiline metadata is safely normalized to space-separated values. Unsupported multiline scalar metadata (e.g. multi-line DESCRIPTION) or dynamic ebuild execution (like unresolved shell or eclass function outputs) requires an active Portage (portageq) environment. In CI mode, missing Portage context is reported explicitly as an authorized skip rather than an error or false verification, leaving existing cache entries intact. Strict mode enforces hermetic availability and fails if the required evaluation context is missing.

g2 cache generate

g2 cache reconcile

Generate the ebuild cache for specific packages:

g2 cache generate app-admin/sudoers-emerge app-test/app

`pkg-desc-index`

Tools relating to generating and verifying pkg_desc_index.

Usage:

g2 pkg-desc-index <subcommand>

Subcommands:

generate [location]: Generate pkg_desc_index file from the repository.
verify [location]: Verify existing pkg_desc_index file matches the repository.

Example:

Generate the package description index for the current overlay:

g2 pkg-desc-index generate .

`package`

Commands relating to packages and search indexing.

Usage:

g2 package <subcommand>

Subcommands:

search: Search packages.
index-overlay: Index a single overlay.
index-repositories: Index multiple repositories from an xml file.
index: Index local repositories.
update: Update the local index from a remote zip file.
deprecated: Commands relating to deprecated packages.
masked: Commands relating to masked packages within a repository.

Masks Command

The g2 masks command provides tools for inspecting and modifying user-level and repository-level package mask configuration (/etc/portage/package.mask and package.unmask).

g2 masks list [<filter>]: List all currently masked and unmasked packages across user config files and repository profiles/package.mask entries. An optional filter (like ::guru or sci-libs/onnxruntime) can be provided.
g2 masks audit [--config-root <path>] [--repos-conf <path>] [--profile <path>] [--repository <name=path>] [--format text|json]: Audit active user package.unmask entries without modifying configuration or executing ebuilds.
g2 masks mask <package>: Add a package to the user's package.mask configuration. If package.mask is a directory, it creates or appends to a g2.conf file inside it. (e.g. g2 masks mask sci-libs/onnxruntime::guru)
g2 masks unmask <package>: Add a package to the user's package.unmask configuration. If package.unmask is a directory, it creates or appends to a g2.conf file inside it. (e.g. g2 masks unmask sci-libs/onnxruntime::guru)
g2 masks reset <package>: Remove all mentions of a package from the user's package.mask and package.unmask configurations, sweeping through configuration directories as well.

The audit reports required, non-matching, no-change, duplicate/shadowed, or indeterminate for each entry, including its source file and line, matching version count, and an explanation. Required entries show versions that would become masked and the mask's source. JSON output includes entries, summary counts, and warnings; progress messages go to stderr.

g2 masks audit
g2 masks audit --config-root /path/to/portage --profile /path/to/repo/profiles/selected --format json
g2 masks audit --config-root /path/to/portage --profile /path/to/profile --repository overlay=/path/to/overlay

By default, the audit reads repos.conf and make.profile under --config-root. Repeat --repository name=path to replace repository discovery, including every required master. Input directories are traversed in lexical order; dotfiles and filenames ending in ~ or .bak are ignored.

Classification is based on available ebuild versions, repository masks (including a single declared master), the active profile's parent cascade, and user mask/unmask rules. Exact negative rules and -* resets are supported. Repositories must declare their masters policy in metadata/layout.conf; use masters = for an independent repository. Portage profile extensions require an explicit portage-1 profile format.

Unsupported atoms (including package-name globs and USE constraints), complex multiple-master/shared-profile inheritance, unavailable profiles, and unknown slot metadata produce indeterminate diagnostics. Slot metadata is used only when it can be established from literal, unconditional ebuild assignments without inheritance or shell execution. Keyword acceptance, licenses, and installed packages are outside this audit.

Each entry is evaluated independently. Do not remove all duplicate/shadowed entries together: two rules may cover each other. Re-audit after each removal. The command offers no apply/remove option.

`pipeline`

Evaluate declarative data extraction pipeline expressions to safely fetch, parse, and filter URLs, HTML, JSON, and XML using a lightweight, deterministic operator chain. This provides a clean, auditable alternative to embedded scripting runtimes for automated workflow builders (such as arrans_overlay_workflow_builder) without requiring base64 encoding or eval workarounds.

Usage:

g2 pipeline [flags] <pipeline_string>

Flags:

-s <KEY>=<VALUE>: Apply a variable substitution for ${KEY} in the pipeline string. Can be specified multiple times. Missing required variables will cause a hard failure with non-zero exit code.

Supported Operators:

get(url): Fetches an HTTP/HTTPS URL with User-Agent g2/pipeline.
json(path): Parses JSON string input and navigates dot-separated paths (e.g. releases.0.tag).
xml: Parses XML string input for subsequent XPath queries.
rss: Parses RSS XML feeds and emits <item> entries as a list.
atom: Parses Atom XML feeds and emits <entry> entries as a list.
xpath(query): Executes an XPath query against parsed XML documents.
regex(pattern): Evaluates a regular expression against scalar or list elements. Extracts first capture group if defined, otherwise full match.
trim: Strips leading and trailing whitespace from scalar strings (leaves list inputs unchanged).
html_links: Extracts and resolves all <a href> URLs from HTML content relative to the fetched URL.
replace('old', 'new'): Replaces substrings in scalar strings (leaves list inputs unchanged). Both arguments must be fully quoted strings (single or double quotes with support for escaped quotes, escaped backslashes, and commas within strings).
url.basename: Extracts the filename or path basename from a scalar URL string (leaves list inputs unchanged).
link: Extracts the link URL from an RSS or Atom XML item.
first: Selects the first item from a list.
last: Selects the last item from a list.
single, exactly_one: Enforces strict cardinality that the stage yields exactly one item.

Stdout and Cardinality Semantics:

Zero results without strict cardinality: Exits cleanly with status 0 and produces no stdout.
Single scalar result: Emitted to stdout followed by a newline.
Multiple results: Emitted to stdout with each result on its own line (newline-separated).
Strict cardinality (single / exactly_one):
- If zero items are produced, exits non-zero with an actionable error on stderr.
- If multiple ambiguous items are produced, exits non-zero with an actionable error on stderr.
- An empty scalar string "" represents zero cardinality under strict checks and exits non-zero.
- Legitimate zero/falsy values such as JSON numeric 0, boolean false, and string "0" or "false" are preserved and succeed as valid single results.
Readable security model: Expressions are written directly as human-readable shell pipeline arguments without needing base64 wrappers, dynamic evaluation, or shell subshell escapes.

Examples:

Fetch a release download page, resolve HTML links relative to the URL, filter for linux deb packages, and ensure exactly one package is found:

g2 pipeline "get(https://example.com/downloads) | html_links | regex(.*linux[.]deb$) | exactly_one"

Extract the download URL filename basename:

g2 pipeline "get(https://example.com/downloads) | html_links | regex(.*linux[.]deb$) | exactly_one | url.basename"

Extract the latest tag from a JSON API using dot-notation:

g2 pipeline "get(https://api.example.com/repos/tool/releases) | json(0.tag_name) | trim | exactly_one"

Extract all release archive links from an Atom feed (line-separated output):

g2 pipeline "get(https://example.com/releases.atom) | atom | link | regex(v(.*)\\.tar\\.gz)"

Extract and normalize version strings using substitutions and strict replacement:

g2 pipeline -s TAG=v1.2.3 -s RELEASE_FILENAME=app-1.2.3.tar.gz \
    "get(https://example.com/releases/${TAG}/${RELEASE_FILENAME}) | regex(app-(.*)\\.tar\\.gz) | replace('+', '.') | exactly_one"

Execute XPath query against an XML document:

g2 pipeline "get(https://example.com/project.xml) | xml | xpath(//download/url) | first | trim"

`eclass`

Commands relating to eclasses.

Usage:

g2 eclass <subcommand>

Subcommands:

list: List available eclasses.
install: Install an eclass from gentoo stable.
explain: Human-readable summary output of an eclass.
remove: Remove an eclass.

`arch`

Commands relating to architectures.

Usage:

g2 arch <subcommand> [options]

Subcommands:

list-add: Add or edit an architecture in arch.list.
list-remove: Remove an architecture from arch.list.
list-ls: List all architectures in arch.list.
desc-add: Add or edit an architecture in arches.desc.
desc-remove: Remove an architecture from arches.desc.
desc-ls: List all architectures in arches.desc.

`profile`

Commands relating to profiles.

Usage:

g2 profile <subcommand>

Subcommands:

list: List profiles.
describe: Describe a profile.

`conf`

Commands relating to portage configuration.

Usage:

g2 conf all [--repo <path>] [--profile <profile_path>] [--make-conf <make.conf_path>] [--config-root <config_root_path>]

Outputs a complete overview of the system's Portage configuration, parsing variables from make.conf and the active profile's make.defaults cascade.

`conf overlay`

Manage repository-scoped local Portage policies (masks and unmasks) beneath /etc/portage (or --config-root).

g2 conf overlay list [--repos-conf <path>] [--config-root <path>]: List configured, enabled repositories from repos.conf.
g2 conf overlay <repo> list [--config-root <path>] [--repos-conf <path>]: List package masks and unmasks scoped to the selected repository across all Portage configuration files.
g2 conf overlay <repo> mask <atom> [--config-root <path>] [--repos-conf <path>]: Add a repository-qualified mask to the local Portage configuration (package.mask).
g2 conf overlay <repo> unmask <atom> [--config-root <path>] [--repos-conf <path>]: Add a repository-qualified unmask to the local Portage configuration (package.unmask).
g2 conf overlay <repo> mask-reset <atom> [--config-root <path>] [--repos-conf <path>]: Remove a repository-scoped mask rule from local Portage configuration.
g2 conf overlay <repo> unmask-reset <atom> [--config-root <path>] [--repos-conf <path>]: Remove a repository-scoped unmask rule from local Portage configuration.

GitHub Action

You can use the g2 GitHub Action to integrate g2 into your CI/CD workflows. It automatically downloads and installs g2 for use in your workflow steps.

arran4/g2-action@v1 installs a published g2 release. Its version input accepts latest or an explicit release tag such as v0.0.103; merging a fix does not update the binary until a release containing it is published. To deploy a particular fix, select its release tag explicitly and check the action's Found release tag log entry.

Example Usage

name: Example workflow
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install g2
        uses: arran4/g2-action@v1
        with:
          # Optional: specify a version. Defaults to 'latest'
          version: 'latest'

      - name: Use g2
        run: |
          g2 lint .

      - name: Use g2 Action
        uses: arran4/g2-action@v1.2
        with:
          # Optional: specify an action
          action: 'lint .'
          # Optional: skip installation if already installed
          mode: 'run'

Search Features

g2 site features a fully integrated browser-side search accessible from the main dashboard. Search indexes are emitted automatically to search/data. Users can query package names, descriptions, use flags, and numerous field filters (category, license, mask, version, depends, etc.). Advanced queries support boolean logic (AND, OR, NOT), grouping (), and sequence matching ('sequence of words'). Gentoo version ordering is natively supported for range queries like version:>1.2.3.

Flags:

-format <string>: Output format: text or json (default text).
-severity <string>: Only show warnings of this severity (Error, Warning, Notice, Info).
-fail-severity <string>: Fail on this severity and worse (Error, Warning, Notice, Info, default Warning).
-only-source <string>: Only show warnings from this source (g2, pkgcheck).
-only-tag <string>: Only show warnings with this tag (e.g., site-quality, metadata.xml).

Example JSON Output:

g2 lint -format=json /var/db/repos/my-overlay

`lint list`

Lists all available lint rules.

Usage:

g2 lint list

Agent Skills

g2 supports an agent-skill subcommand system to let users install, inspect, update, remove, and manage AI agent skills that teach coding agents (like Claude, Cursor, Copilot) how to use this CLI correctly.

Installation Syntax

Skills can be installed from a local path:

g2 skill install ./skills/g2

Scopes and Agents

By default, skills are installed into the project scope (the current working directory) under .agents/skills.

You can modify the scope and agent target using flags:

# Install to the global user home directory (~/.agents/skills/g2)
g2 skill install --scope user ./skills/g2

# Install specifically for a given agent tool (e.g. ~/.cursor/skills/g2)
g2 skill install --scope user ./skills/g2 --agent cursor

Managing Skills

List installed skills:

g2 skill list --scope all

Inspect an installed skill's metadata:

g2 skill inspect g2

Update an installed skill (uses source checksums to detect manual modifications):

g2 skill update g2

# Overwrite local modifications
g2 skill update --force g2

Remove a skill:

g2 skill remove g2

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd/g2		cmd/g2
doc		doc
lints		lints
pipeline		pipeline
skills/g2		skills/g2
templates		templates
test-repo		test-repo
testdata		testdata
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
arches.go		arches.go
arches_test.go		arches_test.go
authors.go		authors.go
authors_test.go		authors_test.go
benchmark_test.go		benchmark_test.go
cache.go		cache.go
cache_policy.go		cache_policy.go
cache_preservation_strict_test.go		cache_preservation_strict_test.go
cache_test.go		cache_test.go
cache_test_utils.go		cache_test_utils.go
categories.go		categories.go
cmd_runner.go		cmd_runner.go
cmd_runner_test.go		cmd_runner_test.go
ebuild.go		ebuild.go
ebuild_bench_test.go		ebuild_bench_test.go
ebuild_builder.go		ebuild_builder.go
ebuild_builder_test.go		ebuild_builder_test.go
ebuild_deduplicate.go		ebuild_deduplicate.go
ebuild_deduplicate_bench_test.go		ebuild_deduplicate_bench_test.go
ebuild_deduplicate_regression_test.go		ebuild_deduplicate_regression_test.go
ebuild_deduplicate_test.go		ebuild_deduplicate_test.go
ebuild_parser.go		ebuild_parser.go
ebuild_parser_test.go		ebuild_parser_test.go
ebuild_test.go		ebuild_test.go
ebuild_txtar_test.go		ebuild_txtar_test.go
eclass_resolver.go		eclass_resolver.go
eclass_resolver_test.go		eclass_resolver_test.go
feeds.go		feeds.go
glsa.go		glsa.go
glsa_test.go		glsa_test.go
go.mod		go.mod
go.sum		go.sum
httputil.go		httputil.go
info_pkgs.go		info_pkgs.go
info_pkgs_test.go		info_pkgs_test.go
info_vars.go		info_vars.go
info_vars_test.go		info_vars_test.go
layout_conf.go		layout_conf.go
layout_conf_test.go		layout_conf_test.go
license_groups.go		license_groups.go
license_groups_test.go		license_groups_test.go
manifest.go		manifest.go
manifest_clean.go		manifest_clean.go
manifest_clean_test.go		manifest_clean_test.go
manifest_test.go		manifest_test.go
manifestutil.go		manifestutil.go
manifestutil_test.go		manifestutil_test.go 10000
mask_audit.go		mask_audit.go
mask_audit_load.go		mask_audit_load.go
mask_audit_test.go		mask_audit_test.go
metadata.go		metadata.go
metadata_comments_test.go		metadata_comments_test.go
metadata_extra_txtar_test.go		metadata_extra_txtar_test.go
metadata_test.go		metadata_test.go
metadata_txtar_test.go		metadata_txtar_test.go
mirrors.go		mirrors.go
mirrors_test.go		mirrors_test.go
models_txtar_test.go		models_txtar_test.go
news.go		news.go
news_parser.go		news_parser.go
news_parser_test.go		news_parser_test.go
package_deprecated.go		package_deprecated.go
package_deprecated_bench_test.go		package_deprecated_bench_test.go
package_deprecated_test.go		package_deprecated_test.go
package_mask.go		package_mask.go
package_mask_test.go		package_mask_test.go
pad_bench_test.go		pad_bench_test.go
pkg_desc_index.go		pkg_desc_index.go
pkg_desc_index_test.go		pkg_desc_index_test.go
portage_context.go		portage_context.go
portage_context_test.go		portage_context_test.go
projects.go		projects.go
projects_test.go		projects_test.go
qa_policy.go		qa_policy.go
qa_policy_test.go		qa_policy_test.go
readme.md		readme.md
repos_conf.go		repos_conf.go
repos_conf_test.go		repos_conf_test.go
repositories.go		repositories.go
repositories_test.go		repositories_test.go
required_use.go		required_use.go
required_use_test.go		required_use_test.go
resolver.go		resolver.go
resolver_make_conf.go		resolver_make_conf.go
resolver_make_conf_test.go		resolver_make_conf_test.go
resolver_test.go		resolver_test.go
site.go		site.go

Latest commit

History

Folders and files

Repository files navigation

g2

Project overview

Useful links

Installation

Quick start

Modules & Commands

manifest

upsert-from-url

verify

clean

metadata

ebuild

overlay site generate

overlay ebuild

overlays site generate

site serve

lint

use

cache

Optional real-Gentoo acceptance procedure

Limitations and Future Scope (Issue #564)

pkg-desc-index

package

Masks Command

pipeline

eclass

arch

profile

conf

conf overlay

GitHub Action

Example Usage

Search Features

lint list

Agent Skills

Installation Syntax

Scopes and Agents

Managing Skills

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`manifest`

`upsert-from-url`

`verify`

`clean`

`metadata`

`ebuild`

`overlay site generate`

`overlay ebuild`

`overlays site generate`

`site serve`

`lint`

`use`

`cache`

`pkg-desc-index`

`package`

`pipeline`

`eclass`

`arch`

`profile`

`conf`

`conf overlay`

`lint list`