Skip to content

USAGE.md

Latest commit

 

History

History
156 lines (107 loc) · 7.52 KB

USAGE.md

File metadata and controls

156 lines (107 loc) · 7.52 KB
Raw
layout default
title Usage
nav_order 3
permalink /usage

Usage

{: .no_toc }

Table of Contents

{: .no_toc .text-delta }

  • TOC {:toc}

Commands

ghrepocfg export [flags]
ghrepocfg apply [flags]
ghrepocfg version

There is no separate validate, diff, or check command. Configuration validation is automatic, apply --dry-run checks repository drift, and export --dry-run previews configuration-file changes.

Export

ghrepocfg export [--repo OWNER/REPO] [--config PATH] [--full] [--dry-run] [--strict]

export reads supported repository state and produces YAML.

  • A new destination receives every supported setting that can be safely read.
  • An existing destination preserves its management scope and refreshes only fields and collections already present.
  • --full replaces an existing management scope with all safely readable supported settings.
  • --dry-run compares against a file destination, prints what would change, writes nothing, and never prompts.
  • Without a file destination, YAML is written to stdout and diagnostics remain on stderr.

When no --config is supplied, export writes .ghrepocfg.yaml at the Git root only when the local checkout corresponds to the target repository. Otherwise it writes YAML to stdout.

Apply

ghrepocfg apply [--repo OWNER/REPO] [--config PATH] [--dry-run] [--strict] [-y]

apply strictly validates YAML, reads requested state, builds a plan for safely readable attributes, and displays that plan before changing anything.

  • With no drift, it reports No changes. and makes no mutation requests.
  • By default, one confirmation prompt covers the entire plan and defaults to no.
  • -y or --yes approves the plan without prompting.
  • --dry-run never prompts or mutates and returns exit code 2 when drift exists.
  • --json emits a structured plan when combined with --dry-run.

After approval, permission-denied writes are skipped with warnings and independent mutations continue. Other mutation errors remain failures. Strict mode stops on the first denied or failed write; successful earlier writes are not rolled back.

Partial Access and Strict Mode

Default export omits unreadable attributes from a new/full export. A scoped refresh retains their existing values and warns that they were not refreshed. Default apply skips unreadable attributes and permission-denied writes, continuing independent work. Unknown collections never become empty collections.

--strict is optional and off by default. Strict export fails before writing YAML or replacing a file if requested state is incomplete. Strict apply rejects incomplete reads before confirmation, stops on a denied/failed mutation, and reads back the managed configuration after applying. Remaining drift, unreadable verification state, or pending collaborator invitations cause exit 1. Code scanning setup is polled for up to 15 seconds within the command's two-minute deadline. Strict mode provides no transaction or rollback.

A strict dry run checks read completeness and known drift; it cannot prove future write access. JSON dry runs include complete and a skipped array of {path, reason} objects. An incomplete strict export dry run returns that diagnostic object without proposing a partial file update. Permission warnings always go to stderr.

Use --strict in CI when exit 0 must mean that all configured state was evaluated. In default mode, exit 0 may include skipped attributes, and exit 2 reports only known drift. See Permissions.

Flags

Flag Commands Description
-R, --repo OWNER/REPO export, apply Target repository
--config PATH export, apply YAML source or destination
--full export Replace the existing management scope with all safely readable supported settings
--dry-run export, apply Preview without writing or prompting
--strict export, apply Require complete reads; verify all managed values after apply (default: off)
-y, --yes apply Skip the confirmation prompt
--json export, apply Emit structured dry-run output
-v, --verbose export, apply Emit one level of additional diagnostics
-h, --help export, apply Print command usage

Repeated verbose flags do not create additional verbosity levels. There is no quiet flag.

Environment Variables

Variable Purpose Precedence
GHREPOCFG_REPO Target OWNER/REPO when --repo is absent 2
GHREPOCFG_CONFIG Configuration path when --config is absent 2
GH_TOKEN Authentication fallback when GitHub CLI credentials are unavailable 2
GITHUB_TOKEN Authentication fallback when GitHub CLI credentials and GH_TOKEN are unavailable 3
NO_COLOR Disable ANSI color when set to a non-empty value —

Environment variables are not expanded inside YAML. Configuration is literal: no templates, includes, inheritance, layering, substitution, or expression evaluation are supported.

Repository Resolution

The target repository is resolved in this order:

  1. --repo or -R
  2. GHREPOCFG_REPO
  3. a GitHub.com remote in the current Git repository

OWNER/REPO, standard GitHub HTTPS URLs, SCP-style SSH URLs, and ssh:// GitHub URLs are accepted. When multiple distinct GitHub repositories are configured as remotes, specify --repo explicitly.

Configuration Resolution

The path is resolved in this order:

  1. --config
  2. GHREPOCFG_CONFIG
  3. .ghrepocfg.yaml at the current Git root

For apply outside a Git checkout, the last fallback is .ghrepocfg.yaml in the working directory. Export uses stdout when no appropriate local destination exists.

Output Streams

  • Exported YAML intended for piping is written to stdout.
  • JSON dry-run output is written to stdout without human-readable contamination.
  • Warnings, diagnostics, prompts, and errors are written to stderr where appropriate.
  • Human-readable plans and apply success output are written to stdout.

Color Output

Interactive terminal output uses color to distinguish meaning:

  • cyan for repositories and setting paths;
  • green for additions, desired values, successful operations, and compliant results;
  • yellow for warnings and previous values;
  • red for removals, failures, and errors;
  • dim text for arrows, prompts, verbose context, and unmanaged settings.

Permission warnings use a yellow, bold warning: prefix followed directly by the affected attribute and reason, without an extra command label.

The final apply summary uses green, bold text and includes both applied and skipped counts; permission skips also produce warnings on stderr.

Color is enabled only when the corresponding output stream is an interactive terminal. Redirected and piped output remains plain. Set NO_COLOR to any non-empty value to disable ANSI color, following the NO_COLOR convention:

NO_COLOR=1 ghrepocfg apply --dry-run

TERM=dumb also disables styling. YAML and JSON output never contains ANSI escape sequences.

Exit Codes

Code Meaning
0 Completed; default mode may have explicit permission skips
1 Configuration, authentication, API, cancellation, mutation failure, or strict incompleteness
2 Repository drift from apply --dry-run, or file changes from export --dry-run

Use a compiled binary when testing exit codes. The go run launcher converts a child exit status such as 2 into its own failure status.

See Examples for complete workflows and Configuration Reference for every YAML attribute.