{"id":50767016,"url":"https://github.com/akaihola/git-knit","last_synced_at":"2026-06-11T14:32:16.675Z","repository":{"id":347471474,"uuid":"1127764510","full_name":"akaihola/git-knit","owner":"akaihola","description":"Manage a merged \"working branch\" from feature branches. NOTE: VIBE-CODED PROTOTYPE!","archived":false,"fork":false,"pushed_at":"2026-01-11T12:05:25.000Z","size":183,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T08:22:22.646Z","etag":null,"topics":["ai-generated","git","git-extension"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akaihola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-04T14:53:38.000Z","updated_at":"2026-02-26T21:13:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/akaihola/git-knit","commit_stats":null,"previous_names":["akaihola/git-knit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/akaihola/git-knit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akaihola%2Fgit-knit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akaihola%2Fgit-knit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akaihola%2Fgit-knit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akaihola%2Fgit-knit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akaihola","download_url":"https://codeload.github.com/akaihola/git-knit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akaihola%2Fgit-knit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34204179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-generated","git","git-extension"],"created_at":"2026-06-11T14:32:15.920Z","updated_at":"2026-06-11T14:32:16.668Z","avatar_url":"https://github.com/akaihola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# git-knit\n\n[![Built with Claude Code](https://img.shields.io/badge/Built_with-Claude_Code-6f42c1?logo=anthropic\u0026logoColor=white)](https://claude.ai/code)\n\n\u003e This project is developed by an AI coding agent ([Claude Code](https://claude.ai/code)), with human oversight and direction.\n\n\u003e Work on multiple Open Source contributions simultaneously in a unified view, then route each change to its own PR-ready branch.\n\n---\n\n## ⚠️ EXPERIMENTAL PROTOTYPE - USE WITH CAUTION\n\n![Status: Prototype](https://img.shields.io/badge/Status-Experimental%20Prototype-red?style=for-the-badge)\n\n**git-knit is currently a rough, vibe-coded prototype and should be treated as UNTRUSTED SOFTWARE.**\n\n### What This Means:\n\n- **No Guarantee of Correctness:** Code has not been thoroughly reviewed or tested in production\n- **Experimental Status:** Core features may change, break, or work unexpectedly\n- **Risk of Data Loss:** Always back up your repository before using git-knit\n- **Use Locally Only:** Do not use on branches you care deeply about without comprehensive testing first\n\n### Before Using:\n\n1. ✅ Back up your repository\n2. ✅ Test on a small, non-critical project first\n3. ✅ Review the source code to understand what commands do\n4. ✅ Report issues and unexpected behavior\n\n### Planned:\n\nA thorough human code review is planned to validate design and implementation. Until then, **assume this is experimental and untrusted software**.\n\n---\n\n**Problem:** Contributing to Open Source often means juggling multiple branches. You want to fix three bugs and add a feature, but need to see and test all changes together. You want to submit separate PRs (because maintainers love focused changes), but you also need to iterate on those PRs after submission. Some work isn't ready to push yet, but you still need it in your local testing environment.\n\n**Solution:** `git-knit` lets you create a merged \"working branch\" that combines all your feature branches. Make changes in one place, test the complete system, then route each commit to its intended branch. Refine your PRs with force pushes, keep private work local, all while maintaining clean, focused PRs ready for maintainers.\n\n---\n\n## Quick Start\n\n```bash\n# Install\npip install git-knit\n\n# You're working on an OSS project with 3 issues to fix\n# Create separate branches for each fix\ngit checkout -b fix-authentication main\ngit checkout -b fix-memory-leak main\ngit checkout -b add-user-profile main\n\n# Create a working branch that merges all of them\ngit knit init dev main fix-authentication fix-memory-leak add-user-profile\n# Now on 'dev' branch with all fixes merged\n\n# Make changes, test everything together...\n# Oops, forgot to handle edge case in auth module\n# Edit auth.py...\n\n# Route this fix to the correct PR branch\ngit knit commit fix-authentication \"handle edge case in auth validation\"\n# Changes are now on fix-authentication, dev is rebuilt\n\n# Submit your PRs\ngit push origin fix-authentication\ngit push origin fix-memory-leak\n\n# Later: fix-reviewer-comment on fix-authentication\ngit knit commit fix-authentication \"address reviewer feedback\"\ngit push origin fix-authentication --force\n# PR updated, dev still has all your work\n```\n\n---\n\n## Why git-knit?\n\nYou're a responsible Open Source contributor. You know maintainers prefer focused, non-stacked PRs. But your workflow needs more flexibility:\n\n| Your Need                                   | Traditional Git                          | git-knit                                       |\n| ------------------------------------------- | ---------------------------------------- | ---------------------------------------------- |\n| **Work on multiple contributions together** | Switch branches constantly, lose context | One working branch, all changes visible        |\n| **Submit separate PRs**                     | Cherry-pick commits manually             | `git knit commit` routes automatically         |\n| **Iterate on submitted PRs**                | Messy rebasing, lost work                | Edit in working branch, route back, force push |\n| **Keep work private**                       | Can't test with private work             | Include private branches, don't push them      |\n| **Quick local testing**                     | Merge test branches, then unmerge        | Working branch always reflects all work        |\n| **Maintainer responsiveness**               | Wait for feedback between PRs            | Iterate independently, submit when ready       |\n\n**Perfect for:**\n\n- 🐛 Fixing multiple related bugs\n- ✨ Adding features that depend on each other\n- 📚 Refactoring that touches multiple areas\n- 🧪 Testing contributions together before submitting\n- 🔄 Iterating on PRs based on reviewer feedback\n\n---\n\n## How It Works\n\n### The Problem\n\n```bash\n# You want to fix 3 bugs and add a feature\n# You create 4 branches\ngit checkout -b fix-auth main\ngit checkout -b fix-ui main\ngit checkout -b fix-api main\ngit checkout -b add-feature main\n\n# But you can only work on one branch at a time\n# Switching between branches = losing context\n# Testing all fixes together = manual merges each time\n# Refine a fix = switch, commit, switch back, rebase...\n```\n\n### The git-knit Solution\n\n```\nmain (upstream)\n  ├─ fix-auth           (PR-ready)\n  ├─ fix-ui             (PR-ready)\n  ├─ fix-api            (PR-ready)\n  └─ add-feature        (private, not pushed)\n\ndev (working branch)\n  = main + merge(fix-auth) + merge(fix-ui) + merge(fix-api) + merge(add-feature)\n  ↑\n  Work here! All changes visible together\n```\n\n```bash\n# Initialize the merged view\ngit knit init dev main fix-auth fix-ui fix-api add-feature\n# Switched to branch 'dev'\n\n# Make changes, test everything together\n# Edit files, run tests, see all 4 contributions working\n\n# Made a fix for auth module\ngit knit commit fix-auth \"handle edge case\"\n# Changes now on fix-auth, dev rebuilt\n\n# Made a fix for UI (not ready for PR yet)\ngit knit commit fix-ui \"improve responsiveness\"\n# Changes now on fix-ui, dev rebuilt (but you haven't pushed fix-ui)\n\n# Time to submit some PRs\ngit push origin fix-auth\ngit push origin fix-api\n\n# Reviewer asks for change on fix-auth\ngit knit commit fix-auth \"address reviewer feedback\"\ngit push origin fix-auth --force\n# PR updated, dev still has all your work\n```\n\n---\n\n## Installation\n\n```bash\n# pip (recommended)\npip install git-knit\n\n# uv (faster)\nuv tool install git-knit\n\n# From source\ngit clone https://github.com/user/git-knit\ncd git-knit\npip install -e .\n```\n\n### Verify Installation\n\n```bash\ngit-knit --version\n# git-knit 0.1.0\n\ngit knit --help\n# Shows all available commands\n```\n\n### Optional: Git-spice for Stacked PRs\n\nIf you occasionally need stacked PRs (PR B depends on PR A):\n\n```bash\n# Install git-spice\npip install git-spice\n\n# git-knit automatically uses it when available\n# Makes restacking dependent PRs effortless\n```\n\n---\n\n## Core Concepts\n\n### Working Branch\n\nA special branch that merges all your feature branches:\n\n```bash\ngit knit init dev main fix-a fix-b fix-c\n# Creates 'dev' branch = main + fix-a + fix-b + fix-c\n```\n\n**Why use it:**\n\n- See all changes together\n- Test complete system\n- Work in one place\n- Easy to context-switch between contributions\n\n### Commit Routing\n\nMove changes from working branch to their target branch:\n\n```bash\n# Make changes in dev\n# Route to specific PR branch\ngit knit commit fix-auth \"handle edge case\"\n```\n\n**What happens:**\n\n1. Changes are committed directly to `fix-auth`\n2. `fix-auth` is merged back into `dev`\n3. Working branch reflects all work again\n\n### Multiple Working Branches\n\nDifferent contexts for different work:\n\n```bash\n# Full stack for local development\ngit knit init dev main fix-a fix-b fix-c fix-d\n\n# Partial stack for quick testing\ngit knit init quick main fix-a\n\n# Keep both - switch between them as needed\ngit checkout dev  # All work\ngit checkout quick  # Quick tests\n```\n\n---\n\n## Common Workflows\n\n### Workflow 1: Fix Multiple Bugs\n\n```bash\n# You found 3 bugs to fix\n# Create separate branches\ngit checkout -b fix-bug-1 main\ngit checkout -b fix-bug-2 main\ngit checkout -b fix-bug-3 main\n\n# Initialize working branch\ngit knit init work main fix-bug-1 fix-bug-2 fix-bug-3\n\n# Make changes, test all fixes together\n# Edit files, run tests, see all bugs fixed\n\n# Route each fix\ngit knit commit fix-bug-1 \"resolve null pointer\"\ngit knit commit fix-bug-2 \"fix race condition\"\ngit knit commit fix-bug-3 \"handle edge case\"\n\n# Submit PRs\ngit push origin fix-bug-1\ngit push origin fix-bug-2\ngit push origin fix-bug-3\n```\n\n### Workflow 2: Stacked Features (with git-spice)\n\n```bash\n# Feature B depends on Feature A\ngit checkout -b feature-a main\ngit checkout -b feature-b feature-a\n\ngit knit init dev main feature-a feature-b\n\n# Make changes, route appropriately\ngit knit commit feature-a \"add base functionality\"\ngit knit commit feature-b \"extend feature\"\n\n# Push stacked PRs\ngit push origin feature-a\ngit push origin feature-b\n# git-spice handles the stacking\n```\n\n### Workflow 3: Keep Work Private Until Ready\n\n```bash\n# One fix is ready, one feature needs more work\ngit knit init dev main fix-bug feature-wip\n\n# Make bug fix, route it\ngit knit commit fix-bug \"critical bug fix\"\n\n# Submit bug fix PR\ngit push origin fix-bug\n\n# Keep iterating on feature-wip\n# Don't push it until ready\ngit knit commit feature-wip \"improve implementation\"\ngit knit commit feature-wip \"add tests\"\n\n# Finally ready\ngit push origin feature-wip\n```\n\n### Workflow 4: Iterate on Submitted PRs\n\n```bash\n# Submitted PRs for fix-a and fix-b\ngit knit init dev main fix-a fix-b\n\n# Reviewer asks for change on fix-a\ngit knit commit fix-a \"address reviewer feedback\"\ngit push origin fix-a --force\n\n# Another review on fix-b\ngit knit commit fix-b \"optimize per reviewer\"\ngit push origin fix-b --force\n\n# Your working branch always reflects the latest state\n# No rebase hell, no lost work\n```\n\n### Workflow 5: Move Misrouted Commit\n\n```bash\n# Oops, committed to wrong branch\ngit knit commit fix-a \"this should be in fix-b\"\n\n# Move it to correct branch\ngit knit move fix-b \"this should be in fix-b\"\n# Searches commit by message, moves it\n```\n\n---\n\n## Command Reference\n\n### `git knit init \u003cworking-branch\u003e \u003cbase-branch\u003e [branch...]`\n\nInitialize a new merged working branch.\n\n```bash\ngit knit init dev main fix-a fix-b fix-c\n```\n\n**Parameters:**\n\n- `working-branch`: Name for your merged view (e.g., `dev`, `work`)\n- `base-branch`: Base branch to start from (usually `main` or `master`)\n- `branch...`: Feature branches to include (can be empty)\n\n**What it does:**\n\n1. Creates working branch from base branch\n2. Stores configuration in Git config\n3. Merges all feature branches into working branch\n4. Checks out working branch\n\n---\n\n### `git knit commit \u003ctarget-branch\u003e [message]`\n\nRoute uncommitted changes to a target branch.\n\n```bash\n# Made changes in dev\ngit knit commit fix-a \"fix critical bug\"\n```\n\n**Parameters:**\n\n- `target-branch`: Which branch gets this commit\n- `message`: Commit message (prompts if omitted)\n\n**What it does:**\n\n1. Commits changes to target branch\n2. Merges target branch back into working branch\n3. Working branch reflects all work again\n\n**When to use:** You made changes that belong to a specific PR branch.\n\n---\n\n### `git knit add \u003cbranch\u003e [--working-branch \u003cname\u003e]`\n\nAdd a branch to the knit.\n\n```bash\ngit knit add fix-d\n# Adds fix-d to current working branch's knit\n```\n\n**What it does:**\n\n1. Adds branch to knit configuration\n2. Merges it into working branch\n\n**When to use:** Created a new feature branch and want to include it.\n\n---\n\n### `git knit remove \u003cbranch\u003e [--working-branch \u003cname\u003e]`\n\nRemove a branch from the knit.\n\n```bash\ngit knit remove fix-b\n# Removes fix-b, rebuilds working branch without it\n```\n\n**What it does:**\n\n1. Removes branch from knit configuration\n2. Rebuilds working branch with remaining branches\n\n**When to use:** Branch was merged upstream or no longer needed.\n\n---\n\n### `git knit move \u003ctarget-branch\u003e \u003ccommit-ref\u003e`\n\nMove a committed change to a different branch.\n\n```bash\n# Move by commit message\ngit knit move fix-b \"this should be in fix-b\"\n\n# Move by commit hash prefix\ngit knit move fix-b a1b2c\n```\n\n**What it does:**\n\n1. Finds the commit\n2. Cherry-picks it to target branch\n3. Restacks dependent branches (if git-spice available)\n4. Rebuilds working branch\n\n**When to use:** Committed to wrong branch or need to reorganize.\n\n---\n\n### `git knit rebuild [--working-branch \u003cname\u003e]`\n\nForce rebuild working branch from scratch.\n\n```bash\ngit knit rebuild\n# Clean rebuild of current working branch\n```\n\n**What it does:**\n\n1. Deletes working branch\n2. Recreates from base\n3. Merges all feature branches\n\n**When to use:** Merge got corrupted or you want clean state.\n\n---\n\n### `git knit restack [--working-branch \u003cname\u003e]`\n\nRestack dependent branches using git-spice.\n\n```bash\ngit knit restack\n# Runs: gs stack restack\n```\n\n**When to use:** Dependent branches need rebasing after upstream changes.\n\n---\n\n### `git knit status [--working-branch \u003cname\u003e]`\n\nShow current knit configuration.\n\n```bash\ngit knit status\n# Shows all working branches\n\ngit knit status --working-branch dev\n# Shows specific working branch details\n```\n\n**Output:**\n\n```\ngit-knit Working Branches\n========================\n\ndev:\n  Base Branch:      main\n  Feature Branches: fix-a, fix-b, fix-c\n\nquick:\n  Base Branch:      main\n  Feature Branches: fix-a\n\nCurrent Branch:     dev\nIs Clean:           yes\n```\n\n---\n\n## Best Practices\n\n### 1. Organize by Logical Groupings\n\n```bash\n# All UI fixes in one working branch\ngit knit init ui-work main fix-ui-a fix-ui-b fix-ui-c\n\n# All API fixes in another\ngit knit init api-work main fix-api-a fix-api-b\n```\n\n### 2. Separate Submitted from Private Work\n\n```bash\n# Branches ready for PRs\ngit checkout -b pr-ready-a main\ngit checkout -b pr-ready-b main\n\n# Work still in progress\ngit checkout -b wip-feature main\n\ngit knit init work main pr-ready-a pr-ready-b wip-feature\n# Only push pr-ready branches, keep wip local\n```\n\n### 3. Use Meaningful Commit Messages\n\n```bash\ngit knit commit fix-auth \"resolve authentication timeout\"\ngit knit commit add-profile \"add user profile page\"\n# Makes move operations easier to use\n```\n\n### 4. Enable git-rerere for Conflict Resolution\n\n```bash\ngit config --global rerere.enabled true\ngit config --global rerere.autoupdate true\n# Remembers conflict resolutions, reapplies automatically\n```\n\n### 5. Keep Working Branches Small\n\n```bash\n# Good: 3-5 related branches\ngit knit init work main fix-a fix-b fix-c\n\n# Avoid: 20+ branches (slow rebuilds)\n# Split into multiple working branches instead\n```\n\n---\n\n## Troubleshooting\n\n### \"Knit not initialized\"\n\n**Problem:** You haven't set up git-knit yet.\n\n**Solution:**\n\n```bash\ngit knit init \u003cwork\u003e \u003cbase\u003e [branches...]\n```\n\n### \"Merge conflict with branch 'fix-a'\"\n\n**Problem:** Git couldn't auto-resolve conflicts.\n\n**Solution:**\n\n```bash\n# Resolve conflicts manually\n# Edit conflicted files\ngit add .\ngit merge --continue\n\n# Or enable rerere to prevent this\ngit config --global rerere.enabled true\n```\n\n### \"git-spice not found, skipping restack\"\n\n**Problem:** Optional dependency missing.\n\n**Solution:** This is fine! git-knit works without git-spice. Install if you want stacked PR support:\n\n```bash\npip install git-spice\n```\n\n### \"Branch 'fix-a' does not exist\"\n\n**Problem:** Feature branch referenced in knit doesn't exist.\n\n**Solution:**\n\n```bash\n# Remove it from knit\ngit knit remove fix-a\n\n# Or create the branch\ngit checkout -b fix-a main\n```\n\n### \"Working tree has uncommitted changes\"\n\n**Problem:** You have unsaved changes.\n\n**Solution:**\n\n```bash\n# Commit or stash them\ngit knit commit fix-a \"your message\"\n# or\ngit stash\n```\n\n---\n\n## FAQ\n\n**Q: Can I use git-knit with existing branches?**\nA: Yes! Just run `git knit init` with your existing branch names. It'll merge them into a working branch.\n\n**Q: What happens if I delete a feature branch?**\nA: Run `git knit remove \u003cbranch\u003e` first to update knit metadata, then delete the branch normally.\n\n**Q: Can I have multiple working branches?**\nA: Yes! Each `git knit init` creates an independent working branch. Great for organizing work by context.\n\n**Q: Do I need git-spice?**\nA: No. git-knit works standalone. git-spice is optional for stacked PR workflows.\n\n**Q: What if maintainer rebases upstream?**\nA: Your feature branches will be behind. Rebase them individually, then `git knit rebuild` to update working branch.\n\n**Q: Can I use git-knit with git submodules?**\nA: Yes. Git operations work normally with submodules. You may need to run `git submodule update` after rebuilds.\n\n**Q: How is this different from git-stacked-diffs?**\nA: git-stacked-diffs is for stacked PR workflows only. git-knit is broader: work on multiple independent contributions together, then route to separate PR branches. You don't need stacks unless you want them.\n\n**Q: Can I contribute to a repo that uses conventional commits?**\nA: Absolutely. git-knit doesn't change your commit messages. Just use conventional commit format in your messages:\n\n```bash\ngit knit commit fix-auth \"fix(auth): handle timeout edge case\"\n```\n\n---\n\n## Contributing\n\nContributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone and setup\ngit clone https://github.com/user/git-knit\ncd git-knit\nuv sync --all-extras\n\n# Run tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=git_knit\n```\n\n### Project Status\n\n**Version:** 0.1.0 (Alpha)\n\n**Stability:** Core features are tested and working. API may change.\n\n**Roadmap:**\n\n- [ ] Git integration (symlink for `git knit` command)\n- [ ] Interactive commit routing (fuzzy search)\n- [ ] Visual branch graph display\n- [ ] Integration tests with real repos\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n---\n\n## Links\n\n- 📖 [Full Specification](specification.md)\n- 🚀 [PyPI Package](https://pypi.org/project/git-knit/)\n- 🐛 [Report Issues](https://github.com/user/git-knit/issues)\n- 💬 [Discussions](https://github.com/user/git-knit/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakaihola%2Fgit-knit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakaihola%2Fgit-knit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakaihola%2Fgit-knit/lists"}