# gitgrip Improvement Ideas
This file captures friction points, feature ideas, and bugs discovered while using `gr`.
Items here should be reviewed before creating GitHub issues.
> **Note**: Historical entries may reference `cr` (the old command name). The current command is `gr`.
> **Merge Conflicts**: When rebasing feature branches, you may encounter merge conflicts in this file when other PRs also add entries. This is expected behavior. To resolve:
>
> 1. Use `git rebase --skip` to skip documentation-only commits from other branches
> 2. Or manually merge both sets of entries
> 3. The alternative would be to use a dedicated documentation file, but we accept this tradeoff for now
>
> See issue #143 for context.
---
### PR Creation Timeout Issue
**Discovered**: 2025-12-05 during codi.md documentation PR
**Problem**: `gr pr create` consistently times out (~30s) even when:
- `gh auth status` shows authenticated user with `repo` scope
- Git operations work (push, status, diff)
- Other `gr` commands work normally
**Reproduction**:
```bash
gr pr create -t "title" --push # times out
gr pr create -t "title" # times out
```
**Workaround**:
```bash
cd codi && gh pr create --title "docs: clarify codi/codi-private setup" --body "..." --base main
```
**Potential causes**:
- Browser-based auth flow required
- Token refresh issue in this environment
- Missing `--body` flag causing interactive prompt
---
## Completed
### Feature: Shell autocompletions ✓
**Completed**: 2026-01-31
Added `gr completions <shell>` command using clap_complete crate.
- Supports: bash, zsh, fish, elvish, powershell
- Usage: `gr completions bash > ~/.local/share/bash-completion/completions/gr`
- Or eval: `eval "$(gr completions bash)"`
---
### Feature: E2E PR testing on GitLab ✓
**Completed**: 2026-01-31
- Added `test_gitlab_full_pr_workflow` test
- Fixed GitLab token parsing to find "Token found:" pattern from glab
- Changed GitLab API auth from PRIVATE-TOKEN to Bearer auth (works for OAuth2 tokens from glab)
- Azure DevOps tests added but require user to complete interactive browser login once
---
### Fix: Griptree worktree operations ✓
**Completed**: 2026-01-31
- Fixed "fatal: this operation must be run in a work tree" errors in griptrees
- Changed all git CLI calls to use `repo.workdir()` instead of `repo.path().parent()`
- `repo.path()` returns `.git/worktrees/<name>` for worktrees, which broke git commands
- `repo.workdir()` correctly returns the actual working directory for both regular repos and worktrees
- Affected commands: `gr sync`, `gr add`, `gr commit`, `gr push`, `gr status`, etc.
---
## Pending Review
### Missing: `gr sync` shows which repos failed ✓
**Status**: ✅ **COMPLETED** - Implemented in PR #131 (v0.5.6)
**Discovered**: 2026-02-01
**Problem**: `gr sync` reports "X failed" with no details about which repositories failed or why.
**Solution**: Now shows per-repo status with clear indicators:
```
Syncing 8 repositories...
✓ tooling: synced
✓ codex: synced
⚠ opencode: not cloned
✗ private: failed - Failed to fetch: authentication required
```
---
### Missing: `gr push` shows which repos failed ✓
**Status**: ✅ **COMPLETED** - Implemented in PR #141 (v0.5.6)
**Discovered**: 2026-02-01
**Problem**: `gr push` reports "X failed, Y skipped" with no details about which repositories failed or were skipped.
**Solution**: Now shows detailed results with per-repo status:
```
Pushing 8 repositories...
✓ tooling: pushed to feat/my-feature
✓ codex: pushed to feat/my-feature
⚠ opencode: skipped (no changes)
✗ private: failed - authentication required
```
---
### Feature: Reference repos (read-only repos excluded from branch/PR operations) ✓
**Status**: ✅ **COMPLETED** - Implemented in PR for v0.5.4
**Discovered**: 2026-02-01 during Rust migration planning
**Problem**: When adding reference implementations to a workspace (e.g., `opencode`, `codex`, `crush`), these repos are only for reading/learning - we never plan to edit them or create PRs. Previously `gr branch` created branches across all repos, and `gr pr create` would try to create PRs in all repos with the branch.
**Solution**: Added `reference: true` flag in manifest to mark repos as read-only:
```yaml
repos:
opencode:
url: https://github.com/anomalyco/opencode.git
path: ./ref/opencode
reference: true # Excluded from branch/PR operations
```
**Behavior**: Reference repos still sync and show in status (with `[ref]` indicator) but are skipped in branch/checkout and PR operations.
---
### Feature: `gr status` should show ahead/behind main ✓
**Status**: ✅ **COMPLETED** - Implemented in PR for v0.5.3
**Discovered**: 2026-01-31
**Problem**: `gr status` showed local uncommitted changes but didn't show how the current branch compares to main/upstream. This made it hard to know if you need to rebase before creating a PR or if main has moved ahead.
**Solution**: Added "vs main" column showing ahead/behind status:
```
Repo Branch Status vs main
------------ --------------- ------ -------
tooling feat/new-api ~3 ↑2 ↓5
frontend feat/new-api ✓ ↑4
backend main ✓ -
- `↑N` = N commits ahead of default branch (your changes)
- `↓N` = N commits behind default branch (need to rebase/merge)
- `-` = on default branch, no comparison needed
- `↑N ↓M` = both ahead and behind (diverged)
---
### Missing: Single-repo branch creation from existing commit
**Discovered**: 2026-01-29 during centralized griptree metadata implementation
**Problem**: Accidentally committed to `main` instead of a feature branch. Needed to create a feature branch from the current commit, then reset main to origin/main. `gr branch` creates branches across ALL repos, which isn't appropriate for fixing a single-repo mistake.
**Workaround**:
```bash
cd gitgrip
git branch feat/centralized-griptree-metadata # Create branch at HEAD
git reset --hard HEAD~1 # Reset main
git checkout feat/centralized-griptree-metadata # Switch to feature
```
**Suggested**: Add `--repo` support for branch creation in a single repo:
```bash
gr branch feat/x --repo tooling # Already supported, but doesn't handle "move commit" scenario
```
Or add a "move last commit to new branch" helper.
### Missing: Non-interactive `gr pr create --body` ✓
**Status**: ✅ **COMPLETED** - Implemented
**Discovered**: 2026-01-29 during PR creation
**Problem**: `gr pr create -t "title"` prompted interactively for the PR body. This blocked automation and required falling back to raw `gh pr create` with `--body` flag.
**Solution**: Added `-b/--body` flag to `gr pr create`:
```bash
gr pr create -t "title" -b "body content"
```
### Missing: `gr commit --amend` support
**Discovered**: 2026-01-29 during sync fix + repo add implementation
**Problem**: Needed to amend a commit after review found minor issues (unused import, misleading comment). Had to use `git commit --amend --no-edit` directly.
**Workaround**: `gr add <files> && git commit --amend --no-edit`
**Suggested**: Add `--amend` flag to `gr commit`
### Missing: `gr pr checks` command
**Discovered**: 2026-01-29 during PR review workflow
**Problem**: To check CI status across all repos with PRs, must run `gh pr checks <number>` separately for each repo. No way to see combined check status across all linked PRs.
**Workaround**:
```bash
gh pr checks 47 --repo laynepenney/gitgrip
# Repeat for each repo with a PR...
```
**Suggested**: Add `gr pr checks` command that:
1. Shows check status for all linked PRs in the current branch
2. Aggregates pass/fail/pending status across repos
3. Blocks/warns if any checks are failing
**Example output**:
```
PR Checks for branch: feat/my-feature
Repo PR Check Status
─────────────────────────────────────────────
tooling #47 build ✓ pass
tooling #47 test ✓ pass
tooling #47 sync-status ⏭ skipped
frontend #123 build ✓ pass
frontend #123 deploy-preview ⏳ pending
Summary: 4 passed, 1 pending, 0 failed
```
**Related**: Issue #30 (cr pr checks) was created previously but not yet implemented.
### Feature: `gr forall` should default to changed repos only
**Discovered**: 2026-01-29 during workflow discussion
**Problem**: `gr forall -c "pnpm test"` runs in ALL repos, even ones with no changes. This wastes time running tests in repos that haven't been modified. Running in all repos should be opt-in, not the default.
**Current behavior**:
```bash
gr forall -c "pnpm test" # Runs in ALL repos (wasteful)
gr forall -c "pnpm test" --repo tooling # Must manually specify repos
```
**Suggested**: Default to repos with changes, require `--all` for all repos:
```bash
# Only run in repos with changes (NEW DEFAULT)
gr forall -c "pnpm test"
# Explicitly run in ALL repos
gr forall -c "pnpm test" --all
# Only repos with staged changes
gr forall -c "pnpm build" --staged
# Only repos with commits ahead of main
gr forall -c "pnpm lint" --ahead
```
**Use cases**:
1. Run tests only in modified repos before committing (default)
2. Run build only in repos that changed (default)
3. CI/CD that needs all repos uses `--all`
4. Pre-push hooks automatically only check affected repos
**Implementation notes**:
- Default = has uncommitted changes OR commits ahead of default branch
- `--staged` = only repos with staged changes
- `--ahead` = only repos with commits ahead of default branch
- `--all` = all repos (current behavior, becomes opt-in)
**Breaking change**: Yes, but safer default. Could warn for one version.
---
## Session Reports
### PR merge check runs fix (2026-02-01)
**Task**: Fix #93 - gr pr merge doesn't recognize passing GitHub checks
**Overall Assessment**: gr workflow was smooth, minor friction with PR creation body flag.
#### What Worked Well ✅
1. **`gr branch`** - Created feature branch across all repos seamlessly
2. **`gr add`** - Staged changes correctly in tooling repo
3. **`gr commit`** - Committed with descriptive message
4. **`gr pr create`** (via gh) - Created PR successfully
#### Issues Created
| #63 | fix: gr pr create command times out |
#### Raw Commands Used (Friction Log)
| `gh pr create --body` | `gr pr create` lacks `--body` flag for PR body | #58 |
#### Minor Friction (No Raw Commands Needed)
| `gr sync` - 1 failed | "7 synced, 1 failed" with no details on which repo failed | New friction point |
| `gr push` - 2 failed | "5 pushed, 2 failed, 1 skipped" with no error details | New friction point |
---
### Multi-Platform Support Implementation (2026-01-29)
**Overall Assessment**: `gr` worked smoothly for this feature. No raw `git` or `gh` commands were needed.
#### What Worked Well ✅
1. **`gr branch`** - Created feature branch across all repos
2. **`gr add`, `gr commit`, `gr push`** - Smooth workflow for iterative commits
3. **`gr pr create`** - Created PR correctly
4. **`gr pr merge --force`** - Merged successfully
5. **`gr checkout main && gr sync`** - Clean return to main after merge
#### Issues Created
| #34 | feat: Add Bitbucket platform support |
| #35 | feat: Use GitHub Check Runs API for better status checks |
| #36 | feat: Add retry logic with exponential backoff |
| #37 | feat: Add rate limiting handling |
| #39 | feat: improve check status messaging in gr pr merge |
#### Minor Friction (No Raw Commands Needed)
| Check status messaging | `gr pr merge` showed "checks not passing" when check was actually SKIPPED. Issue #39 created. |
---
### Homebrew Tap Addition (2026-01-29)
**Task**: Add homebrew-tap repo to workspace and update formula for v0.3.0
#### Issues Created
| #43 | feat: add gr repo add command for adding new repos to workspace |
| #44 | fix: gr sync should not discard uncommitted manifest changes |
#### Raw Commands Used (Friction Log)
| `git clone git@github.com:laynepenney/homebrew-tap.git` | No command to add new repo to workspace | #43 |
| `cd .gitgrip/manifests && git add && git commit` | Manifest changes needed manual handling after sync reset | #44 |
| `cd homebrew-tap && git checkout -b && git push` | New repo not yet managed by gr | #43 |
---
### Commercial Plugin Architecture Implementation (2026-01-28)
**Overall Assessment**: `cr` worked very well for this multi-repo workflow. The core commands handled the majority of operations smoothly.
#### What Worked Well ✅
1. **`cr branch`** - Created branches across all 4 repos seamlessly
2. **`cr status`** - Excellent visibility into repo states, showed changes clearly
3. **`cr add`, `cr commit`, `cr push`** - Worked exactly as expected across repos
4. **`cr pr create`** - Created linked PRs in both codi and codi-private correctly
5. **`cr pr status`** - Showed PR status with checks, approval, mergeable state
6. **`cr sync`** - Pulled and synced repos correctly after merges
7. **`cr checkout main`** - Switched all repos back to main after merge
8. **`cr diff --stat`** - Useful for reviewing changes before commit
#### Issues Created
| #25 | fix: improve error handling for cr pr merge failures |
| #26 | fix: cr pr status shows stale check status |
| #27 | feat: add cr branch --delete for cleanup |
| #28 | feat: add cr rebase with upstream branch tracking |
| #29 | feat: add cr pr diff to show combined PR diff |
| #30 | feat: add cr pr checks to show CI status |
#### Raw Commands Used (Friction Log)
| `git fetch origin main && git rebase origin/main` | No rebase command | #28 |
| `git push --force-with-lease` | No force push after rebase | #28 |
| `gh pr merge 209 --squash` | `cr pr merge` failed with 405 | #25 |
| `gh pr diff 209` | No PR diff command | #29 |
| `gh pr checks 209` | No PR checks command | #30 |
| `git branch -d feat/...` | No branch delete command | #27 |
| `git push origin --delete feat/...` | No remote branch delete | #27 |
---
## Approved (Ready for Issues)
_No items approved._
---
## Completed
_Items that have been implemented. Keep for historical reference._
### `cr pr status/merge` branch check fix (Issue #20)
- **Added in**: PR #21
- **Description**: `cr pr status` and `cr pr merge` now find PRs by checking each repo's own branch. Repos on their default branch are skipped.
### `cr pr create` branch check fix
- **Added in**: PR #19
- **Description**: `cr pr create` now only checks branch consistency for repos with changes. Repos on `main` with no changes no longer block PR creation.
### `cr forall` command (Issue #15)
- **Added in**: PR #17
- **Description**: Run arbitrary commands in each repository with `cr forall -c "command"`. Supports `--repo`, `--include-manifest`, and `--continue-on-error` flags.
### Manifest repo managed by cr (Issue #9)
- **Added in**: PR #12
- **Description**: Manifest repo (`.codi-repo/manifests/`) is now automatically included in all `cr` commands when it has changes. `cr status` shows manifest in a separate section. `cr branch --include-manifest` explicitly includes manifest. `cr pr create/status/merge` handle manifest PRs.
### `cr sync` manifest recovery (Issue #4)
- **Added in**: PR #10
- **Description**: `cr sync` now automatically recovers when manifest's upstream branch was deleted after PR merge
### `cr commit` command (Issue #5)
- **Added in**: PR #10
- **Description**: Commit staged changes across all repos with `cr commit -m "message"`
### `cr push` command (Issue #6)
- **Added in**: PR #10
- **Description**: Push current branch across all repos with `cr push`
### `cr bench` command
- **Added in**: PR #1
- **Description**: Benchmark workspace operations with `cr bench`
### `--timing` flag
- **Added in**: PR #1
- **Description**: Global `--timing` flag shows operation timing breakdown
### `cr add` command (Issue #7)
- **Added in**: PR #11
- **Description**: Stage changes across all repos with `cr add .` or `cr add <files>`
### `cr diff` command (Issue #8)
- **Added in**: PR #11
- **Description**: Show diff across all repos with `cr diff`, supports `--staged`, `--stat`, `--name-only`
### `cr branch --repo` flag (Issue #2)
- **Added in**: PR #11
- **Description**: Create branches in specific repos only with `cr branch feat/x --repo tooling`
---
## Issues Created from These Entries
| #58 | feat: add --body flag to gr pr create |
| #59 | feat: add --amend flag to gr commit |
| #60 | feat: add gr pr checks command |
| #61 | feat: gr forall should default to changed repos only |
| #62 | feat: add single-repo branch creation for fixing commits |
| #63 | fix: gr pr create command times out |
| #99 | fix: gr pr merge doesn't recognize passing checks |
| #112 | fix: gr repo add corrupts manifest YAML structure |
| #113 | feat: add reference repos (read-only repos excluded from branch/PR operations) |
| #129 | fix: gr push shows 'failed' for repos with no changes to push |
| #130 | fix: gr pr merge reports 'checks failing' when checks actually passed |
Created: 2025-12-05
Updated: 2026-02-01
---
### Bug: `gr repo add` corrupts manifest YAML structure ✓
**Status**: ✅ **COMPLETED** - Fixed in PR for v0.5.6
**Discovered**: 2026-02-01 during reference repo addition
**Problem**: `gr repo add` placed the new repo entry between `version:` and `manifest:` sections instead of under `repos:`. This caused manifest parsing to fail.
**Solution**: YAML insertion logic now correctly places repos under `repos:` section.
---
### Bug: `gr push -u` shows failures for repos with no changes → Issue #129
**Discovered**: 2026-02-01 during sync no-upstream fix
**Problem**: When pushing a branch that only has commits in some repos, the repos without changes/commits show as "failed" instead of "skipped". This is misleading - there's nothing to push, so it's not really a failure.
**Reproduction**:
```bash
gr branch fix/something
# Make changes only in tooling repo
gr add . && gr commit -m "fix: something"
gr push -u
# Output: "5 pushed, 3 failed, 0 skipped"
```
**Expected behavior**:
```
# Output should be: "1 pushed, 0 failed, 7 skipped (no changes)"
```
**Notes**: The "failed" repos are ones where the branch exists locally but has no commits to push. They should be counted as "skipped" or "nothing to push".
---
### Bug: `gr pr merge` reports "checks failing" when checks passed → Issue #130
**Discovered**: 2026-02-01 during sync no-upstream fix (PR #127)
**Problem**: `gr pr merge` reported "checks failing" and refused to merge, but when checking with `gh pr checks`, all checks had passed (including the CI summary job). Had to fall back to `gh pr merge --admin`.
**Reproduction**:
```bash
gr pr merge
# Output: "tooling PR #127: checks failing"
# But: gh pr checks 127 --repo laynepenney/gitgrip shows all passing
```
**Workaround**:
```bash
gh pr merge 127 --repo laynepenney/gitgrip --squash --admin
```
**Possible causes**:
- Stale check status caching
- Not waiting for CI summary job to complete
- Check status API query not matching GitHub's merge requirements
**Related**: Issue #99 (gr pr merge doesn't recognize passing checks)
---
### Missing: Auto-discovery of legacy griptrees
**Discovered**: 2026-01-31 during Rust migration testing
**Problem**: The Rust implementation stores griptrees in `.gitgrip/griptrees.json`, but the TypeScript version stored a `.griptree` marker file in each griptree directory. Existing griptrees from the TypeScript version don't show up in `gr tree list`.
**Current behavior**:
- `gr tree list` only reads from `.gitgrip/griptrees.json`
- Existing griptrees with `.griptree` marker files are invisible
**Expected behavior**:
- `gr tree list` should scan sibling directories for `.griptree` marker files
- Discovered griptrees should be automatically registered in `griptrees.json`
- Or at minimum, show a message like "Found unregistered griptree: codi-dev"
**Workaround**:
Manually create `.gitgrip/griptrees.json`:
```json
{
"griptrees": {
"codi-dev": {
"path": "/Users/layne/Development/codi-dev",
"branch": "codi-dev",
"locked": false,
"lock_reason": null
}
}
}
```
**Suggested implementation**:
Add a `gr tree discover` command or auto-discovery in `gr tree list`.
---
### Friction: Git worktree conflict prevents checking out main
**Discovered**: 2026-02-02 during PR #118, #141 work
**Problem**: When the gitgrip repository has an existing worktree (e.g., at codi-workspace), trying to check out `main` in another workspace fails with:
```
fatal: 'main' is already used by worktree at '/Users/layne/Development/codi-workspace/gitgrip'
```
**Reproduction**:
```bash
# In codi-workspace, worktree exists for another purpose
gr branch fix/my-feature # Creates branch in codi-workspace worktree
# In codi-dev workspace
git checkout main # Fails!
```
**Workaround**: Create a new branch instead:
```bash
git checkout -b fix/my-feature
gr branch fix/my-feature # Works - creates new branch
```
**Expected behavior**: Either:
- Show a helpful message explaining the worktree conflict
- Offer to create/use the branch in the current workspace
- Add a `gr worktree` command to manage worktrees
**Suggested fix**: Add detection and helpful error message, or `gr worktree` management command.
---
### Friction: Repeated merge conflicts in IMPROVEMENTS.md
**Discovered**: 2026-02-02 during multiple PR rebases
**Problem**: When rebasing feature branches, kept hitting merge conflicts in IMPROVEMENTS.md because documentation commits from other PRs were also on main.
**Reproduction**:
```bash
gr branch fix/pr-merge-check-runs
# ... work on PR ...
git fetch origin main && git rebase origin/main
# CONFLICT in IMPROVEMENTS.md!
```
**Expected behavior**: Either:
- Documentation changes don't cause merge conflicts during rebase
- Better tooling to resolve such conflicts
**Suggested fix**: Consider whether documentation should be kept in a separate file/location, or document this as expected behavior and provide conflict resolution helpers.
---
### Friction: CI blocking merge with unclear status
**Discovered**: 2026-02-02 during PR #141 merge
**Problem**: PR showed "Repository rule violations found - Required status check 'CI' is expected" even though tests were passing. Had to wait significantly longer for the CI check to actually complete.
**Reproduction**:
```bash
gh pr checks 141
# Shows: Check pass, Clippy pass, Tests pass...
# But merge fails with: "Required status check 'CI' is expected"
# Wait 2+ minutes...
gh pr view 141 --json mergeStateStatus # Still shows CLEAN, but CI pending
```
**Expected behavior**: Either:
- Better visibility of which specific CI check is pending
- Merge blocked with clearer message about what's pending
- Auto-wait for CI to complete before reporting block
**Suggested fix**: Improve status reporting in CLI to show pending CI jobs more prominently.
---
### Friction: Formatting required multiple passes
**Discovered**: 2026-02-02 during PR #138, #140 work
**Problem**: Had to run `cargo fmt` multiple times as formatting kept failing CI even though it passed locally once.
**Reproduction**:
```bash
cargo fmt # Passes locally
gr push # CI fails on Format check
# Fix formatting locally again
cargo fmt # Now finds more issues
```
**Expected behavior**: `cargo fmt` should be deterministic and produce consistent results in CI.
**Suggested fix**: Add pre-commit hook for formatting, or ensure CI uses same rust-toolchain as local.
---
### Friction: PR got contaminated with unrelated changes
**Discovered**: 2026-02-02 during PR #140 → #141
**Problem**: Created PR #140 with github.rs changes that belonged to PR #118. Had to close it and create a clean PR #141 with only push.rs changes.
**Reproduction**:
```bash
# Working on two branches
gr branch fix/push-nothing-to-push # For push count fix
gr branch fix/pr-merge-check-runs # For check runs fix
# Changes from fix/pr-merge-check-runs got committed to fix/push branch
gh pr create # PR #140 contains both fixes mixed together
```
**Expected behavior**: Either:
- Branch isolation prevents cross-contamination
- Clear visual indicator of which files changed in PR diff before creating
**Suggested fix**: Better branch management, or PR preview before creation showing all modified files.