AgentSkillsCN

using-jj

在进行任何创意性工作之前——无论是创建功能、构建组件、添加新功能，还是修改行为——您都必须先使用本指南。在实施前，深入探索用户意图、明确需求与设计方案。

SKILL.md
--- frontmatter
name: using-jj
description: Use when managing source control with Jujutsu (jj), including commits, branching (bookmarks), rebasing, and GitHub PRs.

Using Jujutsu (jj)

Overview

Jujutsu (jj) is a Git-compatible VCS that treats commits as mutable objects identified by a Change ID. It emphasizes a "stacked diffs" workflow where you can easily manipulate history.

When to Use

  • •Always when a .jj directory exists in the project root.
  • •Creating commits, branches (bookmarks), and PRs.
  • •Rebasing, splitting, or squashing changes.

Core Concepts

  • •Change ID: Constant identifier (e.g., kkmpptxz) for a change. Persists across rewrites.
  • •Commit ID: Git SHA (e.g., a1b2c3d). Changes every time you modify the revision.
  • •Bookmark: Equivalent to a Git branch. Points to a specific revision.
  • •Working Copy (@): The revision you are currently editing.

Workflow: Creating a PR

  1. •Work: Make changes in the working copy.
  2. •Describe: jj describe -m "feat: description"
  3. •Bookmark: jj bookmark create <branch-name>
  4. •Push: jj git push --bookmark <branch-name>
  5. •PR: gh pr create

Common Operations

GoalGit CommandJJ Command
Statusgit statusjj st
Loggit log --graphjj log
Commitgit add . && git commitjj describe -m "msg" (no staging needed)
Amendgit commit --amendjj describe -m "new msg" (metadata) or edit files (content)
New Branchgit switch -c featjj new -m "feat" && jj bookmark create feat
Switchgit switch mainjj edit main (edits existing) or jj new main (new on top)
Pushgit pushjj git push
Pullgit pulljj git fetch (updates remote pointers, doesn't merge)

Stacking & Reshaping

  • •Rebase: jj rebase -s <revision> -d <destination>
  • •Split: jj split (interactive split of current change)
  • •Squash: jj squash (moves changes into parent)

Red Flags / Anti-Patterns

  • •❌ Don't use git commands directly for creating commits/branches (except gh CLI).
  • •❌ Don't panic about "detached HEAD". JJ is always detached. Use jj new to start fresh.
  • •❌ Don't forget to push bookmarks. Changes without bookmarks are local-only.

Troubleshooting

  • •Conflict: jj records conflicts in the file. Edit file to resolve <<<< markers, then no git add needed.
  • •Lost: jj op log shows operation history. jj undo works like magic.