Frequently Asked Questions

General

Why doesn’t gitmux push directly to my destination branch?

That’s dangerous. Pull requests provide an audit trail and allow review before merging. gitmux creates a unique feature branch for each sync (e.g. update-from-<branch>-<sha>-rebase-strategy-theirs).

Can I use a local directory as the source?

Yes. Local paths are faster but using URLs ensures you don’t miss upstream updates.

Can I run gitmux multiple times?

Yes. gitmux is designed for repeated runs. Each run creates a new PR with the latest changes from the source.

Who is gitmux for?

• Monorepo extractors — Fork a subset into a standalone repo
• Gist upgraders — Turn a GitHub gist into a full repository
• History preservers — Redo a copy-paste with proper git history
• Git power users — Explore rebase strategies and conflict resolution
• Automation bots — Keep downstream mirrors in sync via PRs

Conflicts

What if there are merge conflicts?

gitmux uses the rebase strategy specified by -X (default: theirs). With theirs, source changes are preferred. For complex conflicts, use -i for manual resolution.

Can I manage the rebase manually?

Yes! Use -i for interactive rebase. gitmux will give you a cd command to enter the workspace. Complete the rebase and push to the remote named destination.

Path Mapping

Can I migrate multiple directories at once?

Yes. Use the -m flag multiple times:

./gitmux.sh \
  -r source -t dest \
  -m 'src:pkg/src' \
  -m 'tests:pkg/tests' \
  -s

All paths are processed in a single operation, creating one branch and one PR.

How do I handle colons in path names?

Use \: to escape literal colons:

-m 'path\:with\:colons:destination'

Can I reassemble a file’s history across renames?

Yes. If a file was renamed over time, map each of its historical paths to the same destination with repeated -m. gitmux allows two mappings to share a destination as long as their sources differ (it warns that it’s treating them as rename lineage):

./gitmux.sh \
  -r source -t dest \
  -m 'old/name.py:dot.py' \
  -m 'new/name.py:dot.py' \
  -s

Author Rewriting

How do I remove AI-generated attribution from commits?

Use --coauthor-action claude to remove Claude/Anthropic attribution while preserving human co-authors:

./gitmux.sh \
  -r source -t dest \
  --author-name "Your Name" \
  --author-email "you@example.com" \
  --coauthor-action claude \
  -s

Use --coauthor-action all to remove all co-author trailers.

What’s the difference between author and committer?

In git:

• Author = who wrote the code
• Committer = who applied the commit

They’re often the same person, but differ in scenarios like cherry-picking or rebasing. Use --author-* to change who wrote the code; use --committer-* to change who committed it.

Can I set author/committer options via environment variables?

Yes:

Option	Environment Variable
--author-name	GITMUX_AUTHOR_NAME
--author-email	GITMUX_AUTHOR_EMAIL
--committer-name	GITMUX_COMMITTER_NAME
--committer-email	GITMUX_COMMITTER_EMAIL
--coauthor-action	GITMUX_COAUTHOR_ACTION

Troubleshooting

How can I preview what gitmux will do before running it?

Use --dry-run (or -D). This shows you the source/destination, which commits would be affected, what author/committer changes would be made, and which co-author trailers would be removed — all without modifying anything.

How do I see more detailed output?

Use -v for verbose output (debug level), or set --log-level debug for maximum detail. Log levels from most to least verbose: debug, info (default), warning, error.

Why are all my commit dates the day I ran gitmux?

By default gitmux preserves each commit’s original authorship date as its committer date, so the extracted history keeps its real timeline. If your commits all show today’s date, committer-date preservation was turned off — set PRESERVE_COMMITTER_DATES=true (the default) to keep the original dates.

Why did gitmux fail before doing any work?

gitmux runs pre-flight checks to validate permissions and access before starting long-running operations. This prevents wasted time from failures late in the process.

Check the error message for what’s missing (e.g., repository access, branch existence). Use --skip-preflight to bypass these checks if you know what you’re doing.

How do I get faster performance?

Install git-filter-repo:

brew install git-filter-repo      # macOS
apt install git-filter-repo       # Debian/Ubuntu
pip install git-filter-repo       # Any platform

gitmux auto-detects and uses it when available for ~10x speedup. See Filter Backend for details.

The temp workspace wasn’t cleaned up

Use -k to intentionally keep the workspace for debugging. Otherwise, this might indicate gitmux was interrupted. The workspace location is printed in the output — you can safely delete it manually.