Jj History Investigation

---
name: jj-history-investigation
description: Investigate jj commit history, split commits, annotate file changes, and clean up redundant commits. Use when debugging history, splitting large commits, or explicitly authorized history rewrites.
---

# Jujutsu (jj) History Investigation and Manipulation

## Overview

When working with complex jj repositories, you may need to investigate historical commits, split monolithic changes into focused commits, or clean up messy history. This skill documents efficient techniques for:

- **Investigating commit history**: Finding when changes were made and why
- **Using jj annotate**: Tracking down who/when specific lines were added
- **Splitting commits**: Breaking large commits into focused, reviewable pieces
- **Handling immutability**: Overriding protections only for authorized local history rewrites
- **Cleaning up redundancy**: Removing duplicate or empty commits
- **Resolving conflicts**: Fixing merge conflicts after rebases

## Core Commands

| Command            | Purpose                      | Example                                    |
| ------------------ | ---------------------------- | ------------------------------------------ |
| `jj log`           | View commit history          | `jj log -r 'ancestors(@, 10)'`             |
| `jj show`          | Display commit details       | `jj show abc123`                           |
| `jj file annotate` | Line-by-line change tracking | `jj file annotate src/main.tex`            |
| `jj edit`          | Start editing a commit       | `jj edit abc123 --ignore-immutable`        |
| `jj split`         | Split a commit into pieces   | `jj split --ignore-immutable path/to/file` |
| `jj abandon`       | Remove commits from history  | `jj abandon abc123`                        |
| `jj rebase`        | Move commits to new base     | `jj rebase -b main -d new-base`            |

## Investigation Techniques

### 1. Finding When a Change Was Made

When you know a file changed but not when, use these approaches:

**Check recent commit messages:**

```bash
# Search for commits mentioning "copyright"
jj log -r 'description(copyright)' --no-graph

# Output:
# trsozpwy feat(frontmatter): Add post-defense required sections
# (shows commits with "copyright" in the message)
```

**View commit details:**

```bash
# Show full commit with statistics
jj show trsozpwy --stat

# Show just the files changed
jj show trsozpwy --summary
```

**Check specific file history:**

```bash
# See who/when each line was added
jj file annotate src/main.tex | grep "copyrightpage"

# Output:
# trsozpwy edmund.m 2025-11-09 00:13:05   49: \copyrightpage{2025}
```

### 2. Understanding Commit Lineage

**Check what's built on top of a commit:**

```bash
# View descendants of commit abc123
jj log -r 'abc123::@' --limit 20

# Check ancestors of current commit
jj log -r 'ancestors(@, 10)'
```

**Find relationships between branches:**

```bash
# See where main and feature branches diverged
jj log -r 'ancestors(main) & ancestors(feature)'

# Check if commit is ancestor of main
jj log -r 'abc123::main'
```

### 3. Extracting Specific Commit Information

**Get commit metadata:**

```bash
# Show commit ID, author, date
jj show abc123 | head -10

# Get just the change ID
jj log -r abc123 --no-graph -T 'change_id'
```

**Check file changes:**

```bash
# See what changed in a commit
jj diff -r abc123

# See specific file diff
jj diff -r abc123 src/main.tex
```

## Splitting Commits

### When to Split

Split a commit when it contains multiple logical changes that should be reviewed separately:

- ✅ **Good candidates**: "Add frontend + backend + tests + docs"
- ✅ **Mixed concerns**: Copyright page + acknowledgments + CV in one commit
- ❌ **Already focused**: "Fix typo in README"

### Basic Split Workflow

**1. Check if commit is immutable:**

```bash
jj edit abc123

# If error: "Commit abc123 is immutable"
# Then use --ignore-immutable flag
```

**2. Edit the commit:**

```bash
jj edit abc123 --ignore-immutable

# Working copy now at abc123
# File system shows state at that commit
```

**3. Split by file/directory:**

```bash
# Split out specific files
jj split --ignore-immutable src/main.tex

# jj will prompt for commit messages for:
# - Selected changes (what you specified)
# - Remaining changes (everything else)
```

**4. Split incrementally:**

```bash
# After first split, you're at "remaining changes"
# Split again to extract more pieces
jj split --ignore-immutable src/chapters/appendix.tex
```

**5. Update commit messages:**

```bash
# Update the commit you just split
jj describe @- -m "feat(frontmatter): Enable copyright page"

# Continue until all pieces are separated
```

### Advanced Split Techniques

**Split and update TODO in same commit:**

```bash
# 1. Split out the main change
jj split --ignore-immutable src/main.tex

# 2. In the split commit, also update TODO.org
# Edit TODO.org to mark item as DONE
jj describe -m "feat(frontmatter): Enable copyright page

Enable copyright on page ii as recommended by UTD.
Mark as complete in TODO.org."
```

**Split multiple files into one commit:**

```bash
# Save final state
cp src/main.tex /tmp/main.tex.final

# Restore to parent
jj restore --from @- src/main.tex

# Apply changes incrementally
# Make change 1, commit
# Make change 2, commit
# etc.
```

## Handling Immutability

### Why Commits Become Immutable

Commits are immutable when:

- They have descendants (other commits built on top)
- They're in shared history (pushed to remote)
- They're marked explicitly in config

### Overriding Immutability

**When it's safe:**

- ✅ Local-only history (not pushed)
- ✅ You own all descendant commits
- ✅ No collaborators affected
- ✅ The user explicitly authorized the rewrite target

Do not use `--ignore-immutable` on pushed or shared history without explicit authorization. Resolve the exact revisions and remote state first.

**How to override:**

```bash
# Edit immutable commit
jj edit abc123 --ignore-immutable

# Split immutable commit
jj split --ignore-immutable src/main.tex

# Note: This will rewrite ALL descendant commits
```

**What happens:**

```bash
# Before split:
# abc123 (monolithic commit)
#   ↓
# def456 (descendant 1)
#   ↓
# ghi789 (descendant 2)

# After split:
# abc123 (piece 1)
#   ↓
# xyz111 (piece 2)
#   ↓
# def456' (rewritten descendant 1)
#   ↓
# ghi789' (rewritten descendant 2)
```

## Cleaning Up History

### Identifying Redundant Commits

**Find empty commits:**

```bash
# Show commit stats
jj show abc123 --stat

# If output shows "0 files changed", it's empty
```

**Find conflicting commits:**

```bash
# Check for conflicts
jj log -r 'all()' | grep conflict

# Output:
# ×  abc123 (conflict) feat: Add something
```

### Abandoning Commits

**Remove redundant commits:**

```bash
# Abandon single commit
jj abandon abc123

# Abandon multiple commits
jj abandon abc123 def456 ghi789

# What happens:
# - Commit is removed from history
# - Descendants are rebased onto parent
# - Changes are preserved in descendants
```

**Abandon empty commits automatically:**

```bash
# After rebasing, jj may create empty commits
# Abandon them to clean up
jj log -r 'all()' --summary | grep "(empty)"
jj abandon empty-commit-id
```

### Cleaning Up After Split

**Common pattern:**

```bash
# 1. Split monolithic commit
jj edit old-commit --ignore-immutable
jj split src/file1.txt
jj split src/file2.txt
# (repeat for each logical piece)

# 2. Check for redundant descendants
jj log -r 'old-commit::@' --limit 30

# 3. Abandon redundant commits
jj abandon redundant-commit-1 redundant-commit-2

# 4. Verify history
jj log -r 'old-commit::@' --no-graph
```

## Resolving Conflicts

### After Rebase/Split

**1. Identify conflicts:**

```bash
jj status

# Output:
# Warning: There are unresolved conflicts at these paths:
# TODO.org    2-sided conflict
```

**2. Create commit to resolve:**

```bash
# Create new commit on top of conflict
jj new conflicted-commit-id
```

**3. Read conflict markers:**

```bash
cat TODO.org

# Output:
# <<<<<<< Conflict 1 of 1
# +++++++ Contents of side #1
# ** DONE Add something
# %%%%%%% Changes from base to side #2
# ** TODO Add something
# >>>>>>> Conflict 1 of 1 ends
```

**4. Choose resolution:**

```bash
# Edit file to pick side #1, side #2, or merge both
# Remove conflict markers

# Or use editor with conflict resolution
jj resolve TODO.org
```

**5. Squash resolution:**

```bash
# Merge resolution into parent
jj squash

# This resolves the conflict in the parent commit
```

## Verifying History

### After Major Changes

**1. Check commit lineage:**

```bash
# View commits from base to current
jj log -r 'base-commit::@' --limit 50

# Check all commits are present
jj log -r 'commit1 | commit2 | commit3' --no-graph
```

**2. Verify each commit is focused:**

```bash
# For each commit in your split:
jj show commit-id --stat

# Should show:
# - Small number of files changed
# - Logical grouping of changes
# - Clear commit message
```

**3. Check for conflicts:**

```bash
# List all commits with conflicts
jj log -r 'all()' | grep conflict

# Should be empty after cleanup
```

**4. Verify bookmarks:**

```bash
# Check where main/feature branches point
jj log -r 'bookmarks()'

# Ensure they're at correct positions
```

### History Health Checklist

After split/rebase/cleanup:

- [ ] No conflict markers in `jj status`
- [ ] No `(conflict)` labels in `jj log`
- [ ] No empty `(empty)` commits (unless intentional)
- [ ] Commit messages are clear and descriptive
- [ ] Each commit has focused changes
- [ ] Bookmarks (main, feature, etc.) point correctly
- [ ] TODO.org or similar files are consistent

## Compact Example

```bash
jj show trsozpwy --stat
jj log -r 'trsozpwy::@' --limit 20
jj split --ignore-immutable src/figures/modules/
jj describe @- -m "feat(figures): split focused change"
jj status
jj log -r 'trsozpwy::@' --limit 30
```

Use this only after the authorization and remote-state checks above.

## Tips and Tricks

### Speed Up Investigation

**Use aliases for common queries:**

```bash
# In ~/.jjconfig.toml
[aliases]
recent = ["log", "-r", "ancestors(@, 20)", "--no-graph"]
conflicts = ["log", "-r", "conflicts()"]
empty = ["log", "-r", "empty()"]
```

**Search commit messages efficiently:**

```bash
# Case-insensitive search
jj log -r 'description("(?i)copyright")'

# Multiple terms
jj log -r 'description(frontmatter) & description(copyright)'
```

### Avoid Common Pitfalls

1. **Don't split without investigation**: Always `jj show` first to understand what's in a commit
2. **Save state before split**: create a named bookmark or a validated `mktemp -d` backup before major rewrites
3. **Split incrementally**: Don't try to split everything at once; do one logical piece at a time
4. **Update TODO immediately**: Mark TODO items in the same commit that does the work
5. **Verify after each step**: Check `jj log` frequently during split/rebase operations

### When NOT to Split

- Commit is already pushed and shared with others
- Changes are truly atomic (e.g., "Fix typo + its test")
- Split would make history harder to understand
- Commit is ancient and rarely viewed

## References

- [jj Documentation](https://jj-vcs.github.io/jj/)
- [jj Revset Language](https://jj-vcs.github.io/jj/latest/revsets/)
- [jj Conflict Resolution](https://jj-vcs.github.io/jj/latest/conflicts/)

## Related Skills

- `using-jj-workspaces` - Isolated jj agent workspaces
- `writing-git-commits` - Focused commit messages and commit splitting