docs: Add Jujutsu for Git experts #7754

jennings · 2025-10-17T15:57:17Z

Checklist

If applicable:

I have updated CHANGELOG.md
I have updated the documentation (README.md, docs/, demos/)
I have updated the config schema (cli/src/config-schema.json)
I have added/updated tests to cover my changes

tingerrr

Just 2 nits from me. I think it's mentioned elsewhere too, but no stashing + no index + the working copy being a commit obviously has big ramifications on uniformity in workflows. For example, I would personally not know how to split a stash in git, but in jj this is trivial.

docs/git-experts.md

steveklabnik · 2025-10-17T19:51:25Z

docs/git-experts.md

+
+TODO: Acknowledge `git rebase --update-refs`
+
+## Undo is easier than searching the reflog


I would say "is more powerful than the reflog" to focus more appropriately, it's about ease of use and power, but you want to focus on power first for a git audience.

It's more powerful than "the reflog", meaning the reflog of HEAD, but in general it's just different. I find myself using the reflog for non-HEAD refs all the time even though I have jujutsu, because AFAICT jujutsu has no way to query "list all the commits that this ref pointed to", which makes it hard to tell e.g. which versions of PRs I've seen before.

BTW, if I can do this, with jj's rich output, timestamps, summary of what operation triggered the change, etc., I would be thrilled to learn this! But the current text doesn't say how.

Correct, we don't have a simple way of walking the operation log filtered to a specific ref yet. #2871 is the FR specifically for doing that for the working copy.

Updated the section title. The body text seems to already support the "more powerful" claim, so I didn't change anything there for now.

steveklabnik · 2025-10-17T19:57:45Z

docs/git-experts.md

+
+TODO: show `jj op log -p`, `jj op diff`
+
+## Conflict resolution can be deferred


this is a big one that we'll have to iterate on, a lot of people want to see something more concrete here. like they don't get the "well you can just do it later" without more details. I had a good example of this somewhere recently and now I've lost it, ugh...

There was an example I read (I don't see it in the docs) that explained how a command could generate a conflict which is then resolved automatically in the next command, which is the best case for deferring.
See Advantages in the docs for scenarios to form an example around.

I added one paragraph about the "need to go fix a critical bug" situation, and then a second paragraph for, "I did another rebase and it resolved all the conflicts for me". What do you think?

I think it's somewhat rare that the "rebase again resolves conflicts" is very useful in practice. I'm not sure it's going to convince many. Perhaps it will be more confusing that it's helpful.

I wonder if this paragraph should be about the conflict algebra (probably without using that term). If it is, I think I would rank 3 things it provides like this:

Rebase/merge always succeeds, so we can always rebase descendants

We can define the changes in a merge commit well

Conflicts resolutions can be deferred

My point is that I think deferring conflict resolution is actually less important as a feature. Just a thought; feel free to ignore.

docs/git-experts.md

joyously · 2025-10-18T14:03:02Z

docs/git-experts.md

+
+TODO: Show example
+
+TODO: show `jj op log -p`, `jj op diff`


maybe mention jj evolog also

People love the evolog but I don't personally use it that much, so I might have trouble writing about it. I added a section but it's probably not very compelling. What do you think?

PhilipMetzger

minor points

PhilipMetzger · 2025-10-20T10:54:36Z

docs/git-experts.md

+Because Jujutsu records the inputs to conflicts, not just conflict markers, it
+can sometimes automatically resolve conflicts after a rebase. When performing
+several rebases in sequence, some conflicts may be introduced by one and then
+later automatically resolved by another, without any manual effort to resolve
+the conflicts.


nit: this paragraph should reference that this makes Git's rerere functionality obsolete since it is built in

PhilipMetzger · 2025-10-20T10:56:35Z

docs/git-experts.md

+You can leave a commit in a conflicted state, continue other work, and return
+later. This reduces the cost of context switching when resolving a large number
+of conflicts.


An advantage of this is that you can rebase like really old work on top of trunk() support without ever needing to solve it, I currently do that for Noah's Topic branch

I do that too. I wonder if that sounds like a benefit, though. I imagine the rebuttal: "If the conflict isn't resolved, you can't use the branch, so why bother even rebasing it?"

Yes, I think this is something we can let people discover later. They'll likely even discover it on their own.

I wonder if that sounds like a benefit, though. I imagine the rebuttal: "If the conflict isn't resolved, you can't use the branch, so why bother even rebasing it?"

I mean having the ability to revive any patch from the past of a codebase is to me a big plus. But your rebuttal is correct though.

I came here to suggest a similar thing; I have a rebase-all alias that I use often, so I'm rebasing all of my branches. This lets me continue to work on a non-conflicted branch, and know which ones I'll need to fix later. Hard to describe this without getting into the alias, though...

martinvonz

Thanks! I think this looks good enough as a start. I think it's good to get it merges in roughly the current shape so we can all help improve it when we see a need. But please address the existing review comments. My approval is not meant as a dismissal of their feedback, of course.

martinvonz · 2025-10-20T15:37:22Z

docs/git-experts.md

+side-by-side. If you find a situation that's easier with Git, run the `git`
+command and return to `jj` when you're done.


nit: Add "Also please file a feature request" or similar?

martinvonz · 2025-10-21T04:57:46Z

docs/git-experts.md

+workflows it improves without losing access to the Git commands and tools you
+already know.
+
+## Automatic and safer history editing


We should probably mention the staging area somewhere. I don't know if that would be part of this section or somewhere else. Feel free to just leave a TODO if you agree.

I would make it a section right above this one, it's going to be the largest change that someone runs into immediately.

martinvonz · 2025-10-21T05:03:10Z

docs/git-experts.md

+If you frequently amend, reorder, or squash commits, Jujutsu can often perform
+the same operations in fewer commands.
+
+Suppose you want to amend an older commit and squash it into earlier history.


This sentence sounds a bit redundant to me because "amend an older commit" and "squash into earlier history" sounds like about the same thing. Maybe "Suppose you want to amend some changes in the working copy into an older commit" or something like that?

martinvonz · 2025-10-21T05:13:05Z

docs/git-experts.md

+You can leave a commit in a conflicted state, continue other work, and return
+later. This reduces the cost of context switching when resolving a large number
+of conflicts.


Yes, I think this is something we can let people discover later. They'll likely even discover it on their own.

martinvonz · 2025-10-21T05:31:52Z

docs/git-experts.md

+
+TODO: show `jj op log -p`, `jj op diff`
+
+## Conflict resolution can be deferred


I think it's somewhat rare that the "rebase again resolves conflicts" is very useful in practice. I'm not sure it's going to convince many. Perhaps it will be more confusing that it's helpful.

I wonder if this paragraph should be about the conflict algebra (probably without using that term). If it is, I think I would rank 3 things it provides like this:

Rebase/merge always succeeds, so we can always rebase descendants

We can define the changes in a merge commit well

Conflicts resolutions can be deferred

My point is that I think deferring conflict resolution is actually less important as a feature. Just a thought; feel free to ignore.

steveklabnik · 2025-10-21T18:05:01Z

docs/git-experts.md

+
+## Git can be used side-by-side in the same repository
+
+Jujutsu repositories are colocated by default, so you can use `jj` and `git`


I would skip the colocated jargon and just talk about how they're next to each other.

steveklabnik · 2025-10-21T18:05:41Z

docs/git-experts.md

+
+Jujutsu repositories are colocated by default, so you can use `jj` and `git`
+side-by-side. If you find a situation that's easier with Git, run the `git`
+command and return to `jj` when you're done.


do we have worries about destructive git commands in this case? I don't want to get too into the weeds right at the start, though...

steveklabnik · 2025-10-21T18:06:14Z

docs/git-experts.md

+workflows it improves without losing access to the Git commands and tools you
+already know.
+
+## Automatic and safer history editing


I would make it a section right above this one, it's going to be the largest change that someone runs into immediately.

steveklabnik · 2025-10-21T18:08:53Z

docs/git-experts.md

+You can leave a commit in a conflicted state, continue other work, and return
+later. This reduces the cost of context switching when resolving a large number
+of conflicts.


I came here to suggest a similar thing; I have a rebase-all alias that I use often, so I'm rebasing all of my branches. This lets me continue to work on a non-conflicted branch, and know which ones I'll need to fix later. Hard to describe this without getting into the alias, though...

jennings force-pushed the jj-for-git-experts branch 2 times, most recently from 02711aa to 10dd898 Compare October 17, 2025 16:00

tingerrr reviewed Oct 17, 2025

View reviewed changes

docs/git-experts.md Outdated Show resolved Hide resolved

docs/git-experts.md Outdated Show resolved Hide resolved

steveklabnik reviewed Oct 17, 2025

View reviewed changes

docs/git-experts.md Show resolved Hide resolved

steveklabnik reviewed Oct 17, 2025

View reviewed changes

jennings force-pushed the jj-for-git-experts branch from 10dd898 to 9af648b Compare October 18, 2025 07:11

joyously reviewed Oct 18, 2025

View reviewed changes

docs/git-experts.md Outdated Show resolved Hide resolved

joyously reviewed Oct 18, 2025

View reviewed changes

sirodoht mentioned this pull request Oct 19, 2025

docs: add coming from git guide #7704

Open

jennings force-pushed the jj-for-git-experts branch 2 times, most recently from 7712344 to a401a5f Compare October 20, 2025 05:52

docs: Add Jujutsu for Git experts

c991044

jennings force-pushed the jj-for-git-experts branch from a401a5f to c991044 Compare October 20, 2025 05:58

jennings marked this pull request as ready for review October 20, 2025 05:59

jennings requested a review from a team as a code owner October 20, 2025 05:59

jennings requested review from joyously, steveklabnik and tingerrr October 20, 2025 06:01

PhilipMetzger reviewed Oct 20, 2025

View reviewed changes

martinvonz approved these changes Oct 21, 2025

View reviewed changes

steveklabnik reviewed Oct 21, 2025

View reviewed changes


		TODO: Acknowledge `git rebase --update-refs`

		## Undo is easier than searching the reflog


		TODO: show `jj op log -p`, `jj op diff`

		## Conflict resolution can be deferred

		side-by-side. If you find a situation that's easier with Git, run the `git`
		command and return to `jj` when you're done.


		## Git can be used side-by-side in the same repository

		Jujutsu repositories are colocated by default, so you can use `jj` and `git`

docs: Add Jujutsu for Git experts #7754

Are you sure you want to change the base?

docs: Add Jujutsu for Git experts #7754

Conversation

jennings commented Oct 17, 2025

Checklist

Uh oh!

tingerrr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jennings Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhilipMetzger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinvonz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

jennings Oct 20, 2025 •

edited

Loading

martinvonz left a comment •

edited

Loading