Configuration & Advanced Settings

GitLegends offers flexible configuration options to tailor default behaviors to your needs. You can use a YAML configuration file, environment variables, or rely on built-in defaults. This section describes the configuration keys, their meaning, and how to override them.

Default Settings

Out of the box, GitLegends has the following default settings (these are defined internally and can be overridden):

# config/defaults.yaml (built-in defaults)
base_branch: main         # Default base branch name for new repos and merges
remote_name: origin       # Default remote name to use for pushing
visibility: private       # Default visibility for new repos (private or public)
owner: null               # Default GitHub owner (null means use authenticated user by default)
author:
  name: ""                # Default author name for commits (if blank, will be determined via GitHub CLI or git config)
  email: ""               # Default author email for commits (if blank, will be determined similarly)
token_env: GITHUB_TOKEN   # Environment variable name that holds GitHub token (if needed by gh CLI)
# dry_run: false          # (Defaults to false; can be enabled to simulate commands)

These defaults mean:

• Unless specified, main is the branch that commands will consider as the base branch.
• The remote is assumed to be origin.
• New repositories are private by default.
• The owner (GitHub namespace) defaults to whatever your GitHub CLI is logged in as (you can override this).
• Author name/email are usually retrieved from your environment or GitHub profile if not set.
• token_env is the name of the env var for the GitHub token (this typically is GITHUB_TOKEN or GH_TOKEN by default).
• dry_run if set to true (via config or env var) would globally activate dry-run mode (no commands executed, just logged).

Configuration File (YAML)

You can create a YAML file (for example, legends.yaml or any name you like) to override these defaults. Then run GitLegends with the --config <path> option to load that file.

Example YAML config (hypothetical):

base_branch: main
remote_name: origin
visibility: public
owner: my-org-name
author:
  name: "Jane Doe"
  email: "jane.doe@example.com"
token_env: GH_TOKEN
dry_run: false

If you save this as legends.yaml, you would run your commands like:

legends --config legends.yaml create-repo myproject --date "2025-01-01" ...

This would apply your config, making the default visibility public, default owner “my-org-name”, setting author details, etc., unless you override them with CLI flags.

Config Precedence

It’s important to note the hierarchy of configuration:

1. Command-line flags – Highest precedence. Anything you explicitly specify in a command (like --public or --owner X) will override all other config sources.
2. Environment variables – Next, environment vars (described below) can override defaults.
3. YAML config file – If provided (via --config), it comes next.
4. Built-in defaults – Lowest priority, used if none of the above specify a particular setting.

In summary, CLI > Env > YAML > Defaults.

Environment Variables

GitLegends recognizes several environment variables that can influence its behavior. These can be used instead of or in addition to a config file, and are useful for CI environments or user-specific defaults.

Here are the environment variables and what they correspond to:

• GHB_BASE_BRANCH – Sets the default base branch name (overrides base_branch in config).
• GHB_REMOTE – Sets the default remote name (overrides remote_name).
• GHB_VISIBILITY – Overrides default visibility for new repos ("private" or "public").
• GHB_OWNER – Sets the default GitHub owner (username or org) for new repos.
• GHB_TOKEN_ENV – If set, overrides the token environment variable name (defaults to GITHUB_TOKEN). This is a bit meta: for example, you could set GHB_TOKEN_ENV=MY_TOKEN and GitLegends will then look for MY_TOKEN in the environment when running gh commands.
• GHB_DRY_RUN – If set to "1", "true", "yes", or "on", it will enable dry-run mode by default (so you don’t accidentally execute commands).
• Git Identity variables: GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL – If you set these in your environment, they will be used as the name/email for commits. Otherwise, GitLegends tries to auto-resolve your name/email via the GitHub CLI or falls back to your global git config. In most cases you won’t need to set these, but they are available for override.

When you run a GitLegends command, it loads the config in this order:

1. First, it reads the YAML file if --config is specified (or a default config file if the tool has one defined, though usually you specify).
2. It then applies environment variables, which override or supplement the config.
3. Finally, any command-line options you provide trump both.

If something is misconfigured, GitLegends may raise a ConfigError. For example, if you set visibility to something other than "private" or "public", it will complain.

Using Dry-Run for Safety

If you want to see what GitLegends would do without actually creating repos, pushing commits, or opening PRs, you can use the global --dry-run flag on any command (or set GHB_DRY_RUN=true in your env or dry_run: true in config). In dry-run mode, GitLegends will print the git/gh commands it would execute, but it will not make any changes. This is highly recommended when you are testing your timeline of events for the first time, just to ensure everything is correct.

Example:

legends --dry-run commit --branch feature-x --date "2025-05-01T10:00:00" --message "feat: x"

You’ll see output logging like:

git checkout feature-x
git commit -m "feat: x"
gh pr create ... (etc)

This confirms the sequence without affecting your repo or GitHub.

Advanced: Customizing Commit Messages or Templates

GitLegends comes with some templated messages for commits, PR titles, bodies, and merge commits. These are mostly internal (found in the templates/ directory of the source). For example, the default merge commit message template is:

{prefix}

{title}

where prefix might be “Merge pull request #123 from branch-name” and title might be “Merge branch-name”.

Currently, customizing these templates would require modifying the source or contributing changes; there isn’t a user-facing mechanism to supply custom templates via config. However, you can always override messages for specific actions via command-line options (like providing --message for merge commits, or editing the commit messages afterward if needed). If you have specific needs for message formats (say to comply with a commit convention), you could adjust them in your fork or open a feature request.

Configuration Example Scenario

Imagine you are routinely using GitLegends for multiple projects within your GitHub organization “AcmeCorp”. You always want new repos public and under AcmeCorp, and your main branch is named “main”. You could set environment variables in your shell profile:

export GHB_OWNER=AcmeCorp
export GHB_VISIBILITY=public
export GHB_BASE_BRANCH=main

Now every time you run GitLegends, you can omit --owner and --public because those defaults will kick in. You could similarly create a config YAML with those values and always pass --config yourconfig.yaml, but environment vars might be simpler in this case.