docs: add simplify-parents command and workflow guidelines

Add jj simplify-parents command documentation to the Essential Commands section, explaining how to remove redundant parents from changes.

Add critical workflow guidelines for ending with empty changes after multi-change operations, including detailed examples for splitting changes, creating parallel changes, and organizing history. This ensures users maintain a clean working copy following jujutsu's design philosophy.
This commit is contained in:
sloane 2025-11-05 07:37:32 -05:00
parent d18742e067
commit ab99fc88d2
No known key found for this signature in database

View file

@ -54,6 +54,8 @@ jj new # Create new commit on top of current
jj new <base> # Create new commit on specified base
jj edit <commit> # Edit an existing commit
jj abandon <commit> # Abandon a commit (preserve children)
jj simplify-parents # Remove redundant parents from current change
jj simplify-parents -r <commit> # Remove redundant parents from specific change
```
### Moving Changes
@ -372,5 +374,58 @@ When helping users with jujutsu:
6. **Reference supplemental docs** - Point to revsets.md, filesets.md, templating.md for details
7. **Explain differences** - Help Git users understand jj's different mental model
8. **Encourage experimentation** - Everything is recoverable via operation log
9. **Always end with new empty change** - After performing operations that create or modify changes, create a new empty working copy change as the final step
### Critical Workflow Rule: End with Empty Change
**IMPORTANT**: When performing operations that create or modify changes, ALWAYS end by creating a new empty change. This ensures the working copy is ready for new work.
#### When to Create New Empty Change
- After splitting a change into multiple commits
- After creating multiple parallel changes
- After rebasing or moving changes
- After any operation that leaves you on a non-empty change
- When organizing or restructuring commit history
#### How to Create New Empty Change
```bash
# After any multi-change operation, end with:
jj new # Create new empty change on current commit
# Or for parallel changes:
jj new <change1> <change2> # Create new empty merge commit above multiple changes
jj simplify-parents # Simplify if merge has redundant parents
```
**Note on Redundant Parents**: When creating merge commits with `jj new <change1> <change2>`, if one change is an ancestor of another, use `jj simplify-parents` to remove redundant parents and create a cleaner history.
#### Examples
**Splitting changes:**
```bash
# User asks: "Split my current change into tests and implementation"
jj split # Split into two changes
jj new # Create new empty change above both
```
**Creating parallel changes:**
```bash
# User asks: "Create separate changes for feature A and feature B"
jj new -r base_commit
jj describe -m "feat: add feature A"
# Make changes for A
jj new -r base_commit
jj describe -m "feat: add feature B"
# Make changes for B
jj new <changeA> <changeB> # Create new empty merge change above both features
jj simplify-parents # Remove redundant parents if any
```
**After organizing history:**
```bash
# After rebasing, squashing, or other history operations
jj new # Always end with fresh empty change
```
This ensures users always have a clean working copy ready for new work, following jujutsu's design philosophy of treating the working copy as a first-class commit.
Remember: jujutsu's design philosophy prioritizes safety, ease of use, and powerful functionality. Help users leverage these strengths.