dev: redesign + variant derivation

[oahshtsua]

This PR proposes changes to the existing CLI model and introduces additional functionality for variation derivation. The previous tool already provided support for associating feature metadata with changes, but this work restructures that workflow and expands it with explicit variant derivation support.

Metadata annotation functionality and variant derivation is introduced through a new cli git-vms. This redesign aligns the workflow more closely with standard Git usage and keeps operations primarily local to the repository.

Overview

$ git vms

Usage: git-vms <COMMAND>

Commands:
  init    Initialize variation management support in the git repository
  add     Associate feature metadata and stage files to the git index
  commit  Commit staged changes with feature metadata
  derive  Derive a variant with the features specified in fog.toml
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Idea

The core idea remains the same: associate feature metadata with changes and use that metadata to improve the git cli experience and explore possibility for variant derivation.

Commands

init

Initializes variation management support in the repository. It introduces a configuration file varcs.toml at the root of the repo and also initializes metadata tracking for staged files.

The rationale behind the command was to introduce a way to keep variant definitions version controlled and improve observability and collaboration in shared repo.

# git-varcs configuration file
# You can define variants and associate features here

[variants.simple]
name = "simple-calculator"
features = ["core", "simple"]

[variants.scientific]
name = "scientific-calculator"
features = ["core", "scientific"]

add

Stages files while associating them with a feature.

git vms add --feature <feature_name> <file>

Unlike the previous implementation, this version supports only one feature per change. This was done to enforce small, well-scoped commits and to help avoid ambiguity in feature ownership for feature derivation. Supporting multiple features is possible but it requires validation rules in variant definitions.

commit

Creates a commit with embedded feature metadata.

git vms commit -m "message"

Unlike the previous implementation that relied on the existing git commit command with pre-commit hooks, this subcommand to git vms embeds metadata directly into the commit message. It also introduces a "change id" for tracking logical changes across history.

The rationale behind this change was to avoid issues with hooks (fragility, portability, interoperability). Keeping metadata co-located with the change itself reduces the additional states that we need to maintain and ensures compatibility with commands like rebase, cherry-pick and also simplifies syncing. The "change id" can be used to track a commit through its evolution across branches (eg. when cherry picked).

derive

Derives a variant defined in varcs.toml.

git vms derive [--refresh] <variant>

Implementation

1. Traverse repository files
2. For each file:
   • read line-by-line
   • use git blame to identify the originating commit
3. Keep lines whose commits match selected features
4. Remove all others
5. Reconstruct a new Git tree and commit it as a variant branch

Limitations

The limitations a purely commit based approach exist. Commits represent changes, not features. Even when features appear isolated, they can rely on import, shared utilities and so on. Also, a project can have cross-cutting refactoring that affect multiple independent features. Operations like moves, renames and formatting changes can collapse carefully curated feature boundaries in commit history.