Regeneration ♻️¶

Keep your project in sync and your sanity intact with the regenerate commands.

As your tool evolves, the gtb ensures your boilerplate infrastructure keeps up. Whether you've updated your manifest or refactored your code, regeneration is the key to maintaining a healthy project.

1. Regenerate Project¶

The regenerate project command is your primary tool for syncing your code with your manifest.

It reads the .gtb/manifest.yaml file and rebuilds all the cmd.go files, registration logic, and asset bundles.

go run main.go regenerate project

When to use it?¶

• After editing manifest.yaml: If you manually updated descriptions, flags, or command structures.
• After updating gtb: To pull in the latest features and bug fixes from the base library.
• To fix drift: If you suspect your registration files are out of sync with your intent.

Flags¶

• --path, -p: Path to the project root (default: current directory).
• --force: Danger Zone! Overwrites existing main.go implementation files. Use this only if you want to reset a command's logic to the default starter code. On a project still using the legacy flat docs layout, --force also migrates the docs to the Diátaxis layout (see below).
• --dry-run: Preview all changes without writing to disk (see below).

What it does¶

• Rebuilds cmd.go: Updates Cobra definitions, flags, and descriptions.
• Refreshes Assets: Re-bundles any static assets into the binary.
• Injects Imports: Ensures all subcommands are correctly imported and registered in parent commands.
• Manages Lifecycle Files: Creates or removes init.go based on the withInitializer value in the manifest for each command. If withInitializer is enabled but the Init<Name> stub is missing from main.go, it is appended automatically.
• Runs Linting: Automatically executes golangci-lint run --fix to ensure the generated code is squeaky clean.
• Conflict Detection: Checks if cmd.go files have been manually modified and prompts for confirmation before overwriting (unless --force is used).

Migrating docs to the Diátaxis layout¶

If the project still uses the legacy flat docs layout (docs/commands/, docs/packages/), regenerate project --force migrates it to the Diátaxis quadrant layout:

• Moves existing command pages into docs/reference/cli/ and package pages into docs/explanation/components/, preserving your hand-written content (pages are moved, not regenerated).
• Stamps docs_layout: diataxis on .gtb/manifest.yaml so future generation targets the new tree.
• Removes the old docs/commands/ and docs/packages/ trees.

Dry-Run Mode¶

Use --dry-run to preview what regenerate project would do without modifying any files:

go run main.go regenerate project --dry-run

This produces a summary of:

• Files to create: New files that would be generated.
• Files to modify: Existing files that would change, shown as unified diffs.

Under the hood, the dry-run materialises all generated files into a temporary directory, runs the same post-processing steps as a real regeneration (go mod tidy, golangci-lint run --fix), and diffs the result against your current project. This ensures the preview is accurate — including formatting and import tidying.

2. Regenerate Manifest¶

The regenerate manifest command works in the opposite direction. It scans your existing Go source code and rebuilds the manifest.yaml.

go run main.go regenerate manifest

When to use it?¶

• After manual refactoring: If you moved command files around manually and want the manifest to reflect the new structure.
• Recovering a lost manifest: If your manifest.yaml was deleted or corrupted, this can reconstruct it from your code.

Flags¶

• --path, -p: Path to the project root (default: current directory).

How it works¶

It parses your project's AST to find cobra.Command definitions and reconstructs the manifest — command names/descriptions/aliases/args, flag definitions, parent/child relationships, per-command options (withAssets, preRun hooks, withInitializer), and project-level properties. For the full extraction rules, see the regenerate command explanation.