Abstract:

This transcript captures a design discussion about the command-line interface (CLI) for the Jujitsu (jj) version control system. The central debate revolves around the philosophy of command design: whether to prioritize a small set of "pure," orthogonal commands or a richer set of user-friendly commands that map directly to common workflows, even if they create functional overlap.

Participants analyze the ambiguity and similarities between commands like squash vs. amend and abandon vs. restore. A key proposal is to split the current squash command into two distinct operations: one for combining entire commits and another for moving partial changes (diffs), arguing this would improve clarity and explainability for new users. The conversation also explores how different user mental models ("edit" vs. "squash" workflows) influence command choice, the importance of documentation, and the potential for GUIs and scripting primitives to create more intuitive user experiences. The overarching theme is the challenge of balancing underlying consistency with a command set that feels intuitive and obvious to a wide range of users.

A Design Discussion on Jujitsu's Command-Line Interface

• 00:00:04 Command Ambiguity: The session begins by highlighting the overlapping functionality between key Jujitsu commands, such as restore vs. abandon and split vs. squash, noting that their behavior depends on the user's intent.
• 00:02:36 Preserving Jujitsu's Clarity: A core strength of Jujitsu is that, unlike Git, the right command for a task is often obvious. The group agrees this "obviousness" is a key property that should be maintained and improved.
• 00:03:38 Prioritizing User Needs Over Command "Purity": A speaker argues that command design should be driven by user workflows and what users need to accomplish, rather than striving for a theoretically pure or minimal command set. Consistency, such as the -i flag for interactive mode, is valuable even if it creates technical duplication between commands.
• 00:05:17 Critique of "Overly Helpful" Commands: A user expresses frustration with commands like jj abandon being "too helpful" by creating new empty commits, suggesting that this behavior obscures the underlying model. The goal should be for commands to help users build a correct mental model of the system.
• 00:08:04 Catering to Different Mental Models: The discussion acknowledges that different users have different workflows (e.g., an "edit mindset" vs. a "squash mindset"), which leads them to prefer different commands for the same outcome.
• 00:09:33 Proposal to Split the squash Command: A major proposal is to divide the squash command. One command would be for combining two entire commits, while a separate command (e.g., diffmove or amend) would handle moving partial changes from one commit to another. This is intended to make the tool easier to explain.
• 01:10:28 The amend vs. squash Debate: Participants discuss the conceptual difference between amending changes into a parent commit and squashing two separate commits together. While Jujitsu currently combines them, some argue they are distinct user intentions, especially concerning metadata like commit messages and bookmarks.
• 01:19:15 The Role of Documentation and GUIs: The conversation expands to include the importance of documentation and Graphical User Interfaces (GUIs). A GUI could offer more intuitive interactions, like dragging and dropping diffs between commits, which could bypass the potential confusion of CLI command names.
• 02:26:01 The Pitfalls of Complex Operations: An idea for a multi-way split (splitting one commit into many in one step) is discussed. A speaker notes that a similar feature implemented at Facebook was ultimately not released because the user interface became overwhelmingly confusing.
• 02:28:49 Building Commands from Core Primitives: A technical direction is proposed where user-facing commands could be implemented as scripts (e.g., using Starlark) built on a small set of core, primitive operations. This could provide a consistent foundation for the CLI, GUIs, and other integrations.
• 03:10:51 Takeaway: Semantic Actions Matter Most: A concluding thought is that it is more important for commands to correspond to a user's semantic mental model (e.g., "I want to make a commit") than for them to be a pure representation of underlying primitives. Having convenient commands like jj commit is valuable, even if its function can be replicated by combining other, lower-level commands. Error: value error Invalid operation: The response.text quick accessor requires the response to contain a valid Part, but none were returned. The candidate's finish_reason is 1.