idosal/git-mcp: Advanced Usage and Configuration Guide

# .git-mcp.yml

# Global settings can be defined at the top level
settings:
  # Stop execution if any command fails in a repository
  stop_on_error: true

repositories:
  # Simple path definition
  - path: ./projects/shared-ui-library
    tags: ["frontend", "library"]

  - path: ./projects/user-service
    tags: ["backend", "service"]

  - path: ./projects/auth-service
    tags: ["backend", "service"]

  - path: ./projects/main-webapp
    tags: ["frontend", "app"]

# Define custom, reusable commands
commands:
  # A command to run tests in all repositories
  run-tests:
    - "npm test"
    - "echo 'Tests completed successfully!'"

  # A command to create a new feature branch
  new-feature:
    # Use a placeholder for the branch name
    - "git checkout -b feature/{{ .arg1 }}"

# Automate actions with hooks
hooks:
  pre-commit:
    - "npm run lint -- --fix"
    - "echo 'Linting complete for' $(basename $(pwd))"
  post-push:
    - "echo 'Successfully pushed changes to origin!'"

git mcp custom new-feature my-new-login-flow

This will execute `git checkout -b feature/my-new-login-flow` in all configured repositories. It’s a powerful way to enforce consistent branching strategies across your team.

Automating Quality with `hooks`

Hooks are scripts that run before or after key `git-mcp` actions (`commit`, `push`).

• `pre-commit`: Runs before the commit is made. It's your gatekeeper. If any command in this hook fails, the commit is aborted for that repository. Our example runs a linter, ensuring code quality before it ever enters the commit history.
• `post-commit`: Runs after a successful commit. Useful for logging or cleanup.
• `pre-push` / `post-push`: Same concept, but surrounding the `push` action. `pre-push` is perfect for running a final integration test suite, while `post-push` can be used to trigger a CI/CD pipeline or send a Slack notification.

Advanced Command-Line Fu: Filtering and Targeting

A great configuration file is only half the battle. Your real day-to-day power comes from combining it with command-line flags.

Filtering with Tags: `--include` and `--exclude`

This is where your tagging strategy pays off. Need to push an update that only affects backend services?

# Only run the push command on repositories tagged 'backend'
git mcp push --include backend

What if you want to update all frontend components, but not the shared library for now?

# Target 'frontend' repos but exclude the 'library'
git mcp push --include frontend --exclude library

This precision prevents accidental changes and lets you orchestrate complex deployments with confidence.

The Power of `--dry-run`: Your Safety Net

Before you run a potentially widespread command, especially one you're not 100% sure about, use `--dry-run`. It simulates the entire process, showing you which repositories will be affected and what commands will be run, without actually executing them.

git mcp commit -m "refactor: improve logging" --include service --dry-run

This command will tell you, "I am going to run `git commit...` in `user-service` and `auth-service`," but it won't actually do it. Make this flag your best friend.

Practical Workflow: A Microservices Update Scenario

Let's tie it all together. Imagine you've updated your `shared-ui-library` and now you need to update the `main-webapp` to use the new version and deploy the changes.

1. Commit the library changes:

   cd projects/shared-ui-library
   # ...make your changes...
   git add .
   git commit -m "feat(ui): add new button component v1.1.0"
   git push
   # You might also publish to npm here: npm publish
   

2. Create a new feature branch on the web app:

   # We only need to branch in the main app
   git mcp custom new-feature update-ui-library --include app
   

3. Update dependencies and make code changes in `main-webapp`:

   cd projects/main-webapp
   npm install shared-ui-library@1.1.0
   # ...update code to use the new component...
   

4. Commit the update across all relevant frontend apps:

   Using `git-mcp`, we ensure our commit message is consistent and triggers our pre-commit hook (linting).

   git mcp commit -m "feat: integrate shared-ui-library v1.1.0" --include app
   

5. Push with confidence:

   Finally, push the changes. Our `post-push` hook will give us a confirmation message.

   git mcp push --include app
   

What was once a multi-step, error-prone process is now a clear, semi-automated workflow, all orchestrated by `git-mcp`.

git-mcp vs. The World: A Quick Comparison

How does `git-mcp` stack up against other multi-repo management methods? It occupies a sweet spot of simplicity and power.

Feature	git-mcp	Custom Shell Scripts	git-repo (Google)
Configuration	Declarative YAML (`.git-mcp.yml`)	Imperative Bash/PowerShell code	Declarative XML (manifest.xml)
Ease of Setup	Very High (single binary + YAML file)	Low (requires scripting knowledge, maintenance)	Medium (requires Python, more setup)
Filtering/Targeting	Excellent (built-in tags, include/exclude)	Manual (must be coded by hand)	Good (project groups, but less flexible)
Hooks	Excellent (built-in pre/post hooks)	Manual (must be coded by hand)	Limited (relies on external hooks)
Best For	Small to medium teams, microservices, library suites	Simple, one-off tasks or highly specific needs	Very large-scale projects (e.g., Android OS)

Key Takeaways: Your Path to Multi-Repo Zen

By moving beyond basic commands, you can elevate `git-mcp` from a simple alias to a full-fledged workflow automation tool. Here are the key takeaways:

• The `.git-mcp.yml` is your command center. Invest time in structuring it well.
• Use `tags` extensively. They are the foundation for all advanced targeting and filtering.
• Automate quality with `hooks`. Run linters, tests, and code formatters automatically to maintain high standards with low effort.
• Define `custom commands` to enforce conventions and simplify complex, repetitive sequences.
• Always, always use `--dry-run` before executing a new or complex command to prevent mistakes.

Stop fighting your repositories and start orchestrating them. By embracing these advanced `git-mcp` features, you'll save countless hours, reduce errors, and bring a new level of sanity to your multi-repo projects.