Configuration

Table of contents

1. Overview
2. Top-Level Structure
3. Command Configuration
4. Params Configuration
   1. Example Params
5. Target Configuration
   1. Transform Behavior
6. Git Configuration
7. Example Configuration

Overview

The repver tool uses a configuration file to define commands and their parameters. This file is typically named .repver and should be located in the root of your repository. This file is in YAML format and contains commands that are invoked when running the repver command with the --command=<name> argument.

Top-Level Structure

Attribute	Type	Required	Description
commands	array	Yes	An array of command definitions

Command Configuration

Each command is defined with the following attributes:

Attribute	Type	Required	Description
name	string	Yes	Unique alphanumeric identifier (1-30 characters)
params	array	No	Optional parameter validation definitions
targets	array	Yes	List of files and patterns to modify
git	object	No	Git automation options

Params Configuration

The params section allows you to define validation patterns for command-line parameters. This enables parameter validation and provides named capture groups that can be used in transforms for flexible value replacement.

Attribute	Type	Required	Description
name	string	Yes	Parameter name, must match the --param-<name> argument
pattern	string	Yes	Regex pattern to validate the parameter value. Must start with ^ and end with $. Can contain named capture groups (e.g., (?P<major>\d+)) for use in transforms.

Example Params

params:
- name: "version"
  pattern: "^(?P<major>0|[1-9]\\d*)\\.(?P<minor>0|[1-9]\\d*)\\.(?P<patch>0|[1-9]\\d*)$"

This pattern validates semantic versions like 1.26.0 and extracts major, minor, and patch components.

Target Configuration

Each target specifies a file to modify and the pattern to match:

Attribute	Type	Required	Description
path	string	Yes	Path to the target file relative to repository root
pattern	string	Yes	Regex pattern to match lines in the file. Must start with ^ and end with $. All capture groups must be named using (?P<name>...) syntax.
transform	string	No	Template for transforming parameter values using named groups from params. Uses `` syntax to reference extracted groups.

Transform Behavior

When transform is specified, the replacement value for the target’s pattern is generated by substituting named groups extracted from the params pattern. This allows different targets to receive different representations of the same input parameter.

For example, with a param pattern that extracts major, minor, and patch from version 1.26.0:

• Transform . produces 1.26
• Transform .. produces 1.26.0

If no transform is specified, the raw parameter value is used directly.

Git Configuration

The optional git section automates Git operations after file modifications:

Attribute	Type	Required	Description
create_branch	boolean	No	Create a new branch before making changes
branch_name	string	Yes*	Name for the new branch. Supports `` placeholders. *Required if create_branch is true.
commit	boolean	No	Commit the changes after modification
commit_message	string	Yes*	Commit message. Supports `` placeholders. *Required if commit is true.
push	boolean	No	Push the branch to the remote repository
remote	string	Yes*	Git remote name (e.g., origin). *Required if push is true.
pull_request	string	No	Create a pull request. Values: NO (default), GITHUB_CLI
return_to_original_branch	boolean	No	Switch back to the original branch after operations. Requires create_branch to be true.
delete_branch	boolean	No	Delete the new branch locally after operations. Requires return_to_original_branch to be true.

Example Configuration

Here’s an example .repver configuration that updates Go version references in a repository, creates a branch, commits the changes, pushes to the remote, and opens a pull request:

commands:
 - name: "goversion"
   params:
   - name: "version"
     pattern: "^(?P<major>0|[1-9]\\d*)\\.(?P<minor>0|[1-9]\\d*)\\.(?P<patch>0|[1-9]\\d*)$"
   targets:
   - path: "go.mod"
     pattern: "^go (?P<version>.*) // GOVERSION$"
     transform: "."
   - path: ".github/workflows/build-go.yml"
     pattern: "^          go-version: '(?P<version>.*)' # GOVERSION$"
     transform: ".."
   git:
     create_branch: true
     branch_name: "repver/go-v"
     commit: true
     commit_message: "Update Go version to "
     push: true
     remote: "origin"
     pull_request: "GITHUB_CLI"
     return_to_original_branch: true
     delete_branch: true