repo-forge

repo-forge is a Python-powered standards automation toolkit for applying a shared repository workflow across multiple repos.

It solves repetitive setup by rendering generic templates (docs, issue forms, and GitHub Actions workflows) into target repositories using placeholder values from a local settings file.

What it does

• Keeps reusable templates in templates/
• Replaces {{TOKENS}} with project-specific values
• Applies templates to one or many sibling repositories
• Supports dry-run and strict token validation modes
• Adds overwrite guardrails with optional --override
• Generates a local markdown diff report by default

Quick start

1. Initialize local settings:

python3 forge.py --init-settings

2. Edit settings.json (local-only file; ignored by git).

3. Preview changes:

python3 forge.py --dry-run --strict

4. Apply templates:

python3 forge.py --yes --strict

5. Overwrite existing differing files only when intentional:

python3 forge.py --yes --strict --override

Folder layout

workspace/
  repo-forge/
  target-repo-a/
  target-repo-b/

Example targets for Journals are already included in example-settings.json.

Template tokens

All placeholders in template files use this shape:

{{TOKEN_NAME}}

Example: {{PROJECT_NAME}}, {{DEVELOPMENT_BRANCH}}, {{PROJECT_BOARD_TITLE}}.

Notes

• settings.json is intentionally untracked.
• Existing files in targets are protected by default if they differ from rendered templates.
• Use --override to overwrite existing differing files.
• A markdown diff report is written to .repo-forge/diff-report.md by default.
• Disable report generation with --no-diff-report or set a custom path with --diff-report.
• The tool does not run git commits automatically.

License

Apache-2.0 (see templates/LICENSE).