50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
# Starting a New Change
|
|
|
|
The jj workflow is: **describe first, then code, then refine**. The working copy is always a commit (`@`), so you're already in one when you start. The question is whether to reuse it or start fresh.
|
|
|
|
## The opening sequence
|
|
|
|
```bash
|
|
# 1. Check what @ currently looks like
|
|
jj st
|
|
```
|
|
|
|
**If `@` is empty** (no changes, no description set, or description is fine to discard):
|
|
- Reuse it. Just describe and start.
|
|
|
|
**If `@` has changes you want to keep** (it's someone else's WIP, or work you haven't finished):
|
|
- Start fresh with `jj new` — this creates a new empty commit on top of `@`.
|
|
|
|
```bash
|
|
# 2. Describe before coding (only with -m; never editor-based)
|
|
jj desc -m "feat: Add user authentication to login endpoint"
|
|
|
|
# 3. Make changes — they snapshot to @ automatically on the next jj command
|
|
# (no `jj add`, no `jj commit` needed)
|
|
|
|
# 4. Verify
|
|
jj st
|
|
```
|
|
|
|
## Why describe first
|
|
|
|
Setting the message up front:
|
|
- Forces you to articulate the change as one logical unit before writing code (atomic commits)
|
|
- Means there's never a phase where `@` says "(no description set)"
|
|
- Makes the change navigable in `jj log` while it's still being built
|
|
|
|
See `references/COMMIT_MSG.md` for the message format conventions.
|
|
|
|
## After the change is done
|
|
|
|
**Do NOT run `jj new` to "close" the change.** In jj, the working copy is always a commit — there's no separate commit step. Leave `@` as-is; the *next* task's step 1 (`jj st` → reuse or `jj new`) handles transition.
|
|
|
|
If refinement is needed (split, squash, absorb, abandon), see `references/REFINE_COMMIT.md`.
|
|
|
|
## Anti-patterns
|
|
|
|
- ❌ `jj commit` — doesn't exist; the working copy is already a commit
|
|
- ❌ `jj desc` without `-m` — opens an editor; will hang in non-interactive agent environments
|
|
- ❌ Running `jj new` at the end of a task — leaves an empty `@` for the next agent to clean up
|
|
- ❌ Starting code before describing — you'll forget to describe, or describe vaguely after the fact
|