Skip to content

USER_GUIDE.md

Latest commit

 

History

History
379 lines (258 loc) · 11.7 KB

USER_GUIDE.md

File metadata and controls

379 lines (258 loc) · 11.7 KB
Raw

MetaStackr Detailed User Guide

Welcome to the MetaStackr User Guide. This document provides end-to-end instructions for developers, repository maintainers, and DevOps engineers managing multi-repo workflows with git-meta and the metastackrd daemon.

Table of Contents

  1. Concepts & Terminology
  2. CLI Command Reference (git-meta)
  3. Developer Workflow Scenario
  4. Backend Administration (metastackrd)
  5. Extensions & IDE Plugins
  6. Troubleshooting & Partial Failure Recovery

Concepts & Terminology

  • Meta-Repository (Meta-Repo): A parent Git repository containing multiple submodules configured via .gitmodules.
  • Submodule / Child Repo: An independent Git repository tracked inside the meta-repo at a specific commit pointer.
  • Meta PR: A GitHub pull request opened against the root meta-repository.
  • Child PR: A GitHub pull request opened against a child repository matching the feature branch of the Meta PR.
  • Cascade Merge: An automated, topological merge protocol that merges child PRs in parallel depth batches before bumping submodule pointers in dependent repositories and finally merging the Meta PR.

CLI Command Reference (git-meta)

Make sure git-meta is in your system PATH (run make install to copy to /usr/local/bin).

git meta status

Displays local submodule drift (uncommitted changes, unpushed commits) side-by-side with remote PR approval and CI statuses.

git meta status [--server <server-url>]

Output Example:

⚡ MetaStackR Status

Meta Repo: org/meta-repo | Branch: feature/auth-v2

 Submodule Path      |  Local Branch  |  Local Drift   |  Child PR  |  Review      |  CI State 
------------------------------------------------------------------------------------------
 sub/auth-service    | feature/auth-v2| DIRTY          | #42        | ✅ APPROVED  | ✅ SUCCESS
 sub/ui-app          | feature/auth-v2| CLEAN          | #18        | ⏳ PENDING   | ⏳ PENDING

Backend Meta PR Status: SYNCING (Lock Version: 3)

git meta checkout

Safely creates or switches branches across the parent meta-repo and all tracked submodules.

# Switch to existing branch
git meta checkout feature/my-feature

# Create and switch to new branch across all submodules
git meta checkout -b feature/my-feature

git meta commit

Creates coordinated atomic commits across all modified submodules and updates the parent meta-repo commit pointers in a single operation.

# Auto-stages and commits all dirty submodules & updates parent pointers
git meta commit -m "<commit-message>"

# Only commits changes already staged in the index (plus updated submodule pointers)
git meta commit -m "<commit-message>" --staged

git meta push

Enforces bottom-up pushing. It inspects all submodules, pushes dirty submodule commits to their respective remote origins first, and only updates parent meta-repo commit pointers once all submodules are pushed.

git meta push

Why Bottom-Up? If you push a meta-repo commit pointer without pushing the submodule origin first, other developers will get broken/dangling commit references (fatal: reference is not a tree). git meta push eliminates this risk.

git meta create-pr (Alias: git meta pr)

Opens or creates GitHub Pull Requests across all modified submodules and the parent meta-repo in a single command. It uses a hybrid strategy: automatically creating PRs via gh CLI or GitHub API if available, or opening PR compare pages in your default web browser as a fallback.

# Automatically create PRs across all modified repos
git meta create-pr --title "feat: user billing integration"

# Short alias to open compare pages in web browser
git meta pr --web

git meta sync

Fetches origin/main, fast-forwards/rebases local submodules, and aligns root pointers to keep your multi-repo workspace synchronized.

git meta sync

git meta rebase

Conducts a two-phase rebase: rebases child submodules first against the target upstream branch, then updates parent meta-repo references.

git meta rebase <upstream-branch>

git meta retry-merge

Triggers a retry of the cascade merge engine on a Meta PR that entered FAILED_PARTIAL status (due to a transient network issue or resolved merge conflict).

git meta retry-merge --pr <pr-number> [--server <server-url>]

git meta install-hooks

Installs post-checkout and pre-commit Git hooks into your workspace's .git/hooks directory to automatically warn developers about detached HEAD states or unaligned submodule branches.

git meta install-hooks

git meta init

Initializes and onboards a repository to MetaStackr by registering with the backend server, installing local Git hooks, and setting up GitHub webhooks.

git meta init [--server <server-url>] [--url <webhook-url>] [--secret <secret>] [--allow-code-pull]

git meta setup-webhook

Automates repository webhook registration with GitHub.

git meta setup-webhook [--url <webhook-url>] [--secret <secret>]

git meta agents

Prints machine-readable guidelines and operation rules for AI coding agents operating in MetaStackr workspaces.

git meta agents [--json]

git meta version

Prints the current semantic version of the git-meta CLI binary.

git meta version [--json]
# Or using the root flag:
git meta --version

git meta completion

Generates shell autocompletion scripts for git meta and git-meta across bash, zsh, fish, and powershell.

# Zsh (add to ~/.zshrc):
source <(git meta completion zsh)

# Bash (add to ~/.bashrc):
source <(git meta completion bash)

# Fish (add to ~/.config/fish/config.fish):
git meta completion fish | source

Developer Workflow Scenario

Step 1: Create a Feature Branch

cd /path/to/meta-repo
git meta checkout -b feature/user-billing

Step 2: Make Changes Across Submodules

Make changes inside submodules (sub/billing-api, sub/frontend) and commit locally within each submodule:

cd sub/billing-api
git commit -am "feat: add stripe integration"
cd ../frontend
git commit -am "feat: add checkout form"
cd ../..

Step 3: Check Local Drift

git meta status

Step 4: Perform Bottom-Up Push

git meta push

Step 5: Open Meta PR & Child PRs

Automatically create or open pull requests on GitHub for all modified submodules (sub/billing-api, sub/frontend) and meta-repo using a single command:

git meta pr --title "feat: user billing integration"

MetaStackr will synthesize the tree and maintain a single GitHub Check Run named meta-repo/sync.

Backend Administration (metastackrd)

Database Schema & Optimistic Locking

metastackrd requires PostgreSQL (v14+). The daemon executes embedded SQL migrations automatically on start up.

Key Database Tables:

  • meta_prs: Meta PR status and lock_version.
  • child_prs: Child PR states, review state, CI state, merged SHAs.
  • child_pr_dependencies: DAG relationship edges.
  • merge_audit_logs: Audit trail of merge events and saga operations.

GitHub Webhooks Setup

  1. In your GitHub organization or repository settings, navigate to Webhooks $\rightarrow$ Add webhook.
  2. Set Payload URL to https://your-domain.com/webhooks/github.
  3. Set Content type to application/json.
  4. Enter your secret in Secret and set WEBHOOK_SECRET on metastackrd.
  5. Select events:
    • Pull requests
    • Pull request reviews
    • Check runs
    • Workflow runs

Privacy-by-Default (Opt-In Code Access)

By default, metastackrd operates on branch metadata and Git SHAs without caching, pulling, or cloning repository source code files. This guarantees that your source code remains completely private.

To authorize local code access features, toggle allow_code_pull to true when registering your tracked repository (via git meta init --allow-code-pull or in repository onboarding configuration):

# repository configuration example
name: MetaStackrConfig
allow_code_pull: false  # Change to true to opt-in to code analysis

What you get if you opt in:

  1. Static Import Analysis: Allows the server to inspect source files to automatically build and sort topological dependency DAGs based on code imports.
  2. Local Merge Dry-Runs: Executes dry-run merges on the server to catch file conflicts early and flag FAILED_DRIFT before pushing updates to GitHub.
  3. Advanced Line-Level Diff Warnings: Generates detailed warnings inside GitHub Check Runs highlighting exact code-level alignment mismatches.

Extensions & IDE Plugins

MetaStackr includes browser extensions and IDE plugins located in the extensions/ directory.

Build All Extensions

You can package all extensions at once using the root Makefile target:

make build-extensions

Chrome Extension

Located in extensions/chrome/. It integrates directly into GitHub Pull Request UI pages to show live submodule tree status and trigger cascade merges.

Development / Unpacked Loading:

  1. Open Chrome and navigate to chrome://extensions.
  2. Enable Developer mode in the top right toggle.
  3. Click Load unpacked and select the extensions/chrome directory.

Packaging for Distribution:

make build-chrome
# Output: metastackr-chrome.zip

VS Code Extension

Located in extensions/vscode/. It registers a unified Source Control Manager (SCM) provider, status bar item, and commands (metastackr.commit, metastackr.checkout, metastackr.sync).

Build & Package (.vsix):

make build-vscode
# Output: metastackr-vscode.vsix

Install in VS Code:

code --install-extension metastackr-vscode.vsix

JetBrains Plugin

Located in extensions/jetbrains/. Built using Kotlin and Gradle for IntelliJ IDEA, PyCharm, WebStorm, and GoLand.

Build Plugin Archive:

make build-jetbrains
# Output: extensions/jetbrains/build/distributions/

Troubleshooting & Partial Failure Recovery

If a child PR fails to merge (e.g. merge conflict):

  1. MetaStackr halts the cascade merge immediately.
  2. The Meta PR status is set to FAILED_PARTIAL. Previously merged child PRs on base branches are NOT force-reverted.
  3. The exact error is logged to merge_audit_logs.
  4. The developer resolves the conflict in the failing child PR and merges it manually or updates the PR branch.
  5. The developer runs git meta retry-merge --pr <PR_NUMBER>. MetaStackr will detect already-merged child PRs, skip them, and resume the cascade merge from the unmerged node.