docs: add coming from git guide #7704

sirodoht · 2025-10-11T17:04:58Z

This is a new guide for learning jujutsu.

I finally made sense of how I can use jujutsu to fit a/the standard github flow. I know there are tons of opinionated guides but I felt this was missing and didn't find it anywhere else. Also, I think it should be part of the official docs -- so here it is!

google-cla · 2025-10-11T17:05:03Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

github-actions

The following commits do not follow our format for subject lines:

a8ae7c9: Add Coming from Git guide in docs

Commits should have a subject line following the format <topic>: <description>. Please review the commit guidelines for more information.

martinvonz · 2025-10-11T17:10:27Z

I haven't looked at this yet but could you explain how it relates to https://jj-vcs.github.io/jj/latest/tutorial/ (which targets current Git users) and https://jj-vcs.github.io/jj/latest/github/?

joyously · 2025-10-11T17:30:16Z

From the 0.34.0 CHANGELOG:

Git-based repositories are now colocated by default. Configure git.colocate = false to keep the previous behavior.

sirodoht · 2025-10-11T19:48:59Z

thanks, both, for reviewing so quickly!

@joyously awesome, thanks! I will adjust

@martinvonz sure! I can explain. I wrote this guide for people who have read about jujutsu and understood the basic idea and want to get started immediately with their working projects.

comparing to the tutorial page (https://jj-vcs.github.io/jj/latest/tutorial/), the guide in this PR:

goes farther, explains a full code change lifecycle (in the github flow)
assumes the reader is already familiar with the basic jujutsu concepts (thinking of adding an intro paragraph to explain and link to that)
assumes an existing local repository with either a clean or even a non-clean working directory (this includes everybody who wants to start learning jujutsu immediately)
integrates github as part of it and follows the standard github flow explaining a simple PR workflow with changes
each step is designed not to be verbose, focusing on a single concept/task
has the purpose of allowing someone to use jujutsu immediately and figure out the rest of the stuff as they go (with this guide being the first step)

comparing to the github page (https://jj-vcs.github.io/jj/latest/github/), the guide in this PR:

focuses less so on commands completeness or variety of options and potential situations
explains concepts such as branches/bookmarks as part of the purpose (the tutorial) which makes it more (IHMO!) engaging as one of the first things to read
explains concepts less verbosely and in much less detail -- which is good for the purpose of this guide but not good for other valuable purposes

the main motivation for writing this guide came because I had a friend explain to me how jujutsu works, but then I found no tutorial on how to start using it in my existing local repository. I think this guide would work well in addition to the existing tutorial, not replacing it, maybe with a title such as "Full lifecycle tutorial".

let me know what you think! happy to make changes, I only submitted this because nothing else I read was useful at this point of my jujutsu experience -- but that's just me!

All commits are now correctly formatted. Thank you for your contribution!

PhilipMetzger

Here are some initial comments. cc @ilyagr since he has looked at most larger doc PRs.

While I like the idea, it certainly lacks a bit of polish and I'm not sure yet how to integrate it into existing documentation.

docs/guides/coming-from-git.md

sirodoht · 2025-10-19T11:54:06Z

Perfect, thank you @PhilipMetzger! These were all valuable suggestions. I've updated the document with some additional changes as well, and I added an overview section too, which includes the blog post that inspired me to get back to Jujutsu and write this guide.

joyously · 2025-10-19T13:57:02Z

docs/guides/coming-from-git.md

+jj describe
+```
+
+Awesome! Jujutsu auto-commits on every file save (with empty commit messages), so


I think this gives the wrong impression: "every file save" would have to be tied to the editor or using some file monitor. Isn't it simply that every jj command does a snapshot first?

Ah, right. Let me try to fix that.

joyously · 2025-10-19T14:02:54Z

docs/guides/coming-from-git.md

+jj log
+```
+
+to see current and previous commits along with messages and bookmarks.


The default revset for jj log often doesn't show much, so this can be misleading.

I see, fixing.

Is it true to say this?

You can always do jj log to see the most recent relevant commits (i.e. working copy commit and ancestor plus any other mutable — unpushed — commits) along with messages and any bookmarks on
those commits.

Is it true to say this?

I don't know, but it's the long way around, if you don't mention revsets or default log parameters. Either way, it's more than is needed for your explanation.
My own experience with this is that I don't know the revset stuff, and the log command doesn't show much by default, so it feels really frustrating or that the tool lost all the commits.

joyously · 2025-10-19T14:10:18Z

docs/guides/coming-from-git.md

+
+Ok, work done, how to push?
+
+`jj` does not have branches, it has `bookmarks`. Branches are like tree branches:


jj does not have branches,

I like your explanation except this phrase, because the graph does branch. Also because a deleted branch in Git is abandoned in jj, isn't it?

Right, thanks! What does "abandoned in jj" mean? Does it mean it's no longer accessible? I'll change this sentence to:

We don't push branches in Jujutsu as we do in Git. Instead, we push bookmarks.

What does "abandoned in jj" mean?

To me it means "the result of the abandon command". I don't know what is going on underneath.

sirodoht · 2025-10-19T16:03:08Z

Thanks @joyously! These were great suggestions.

I think how we can integrate this into the existing documentation remains an open question though. I just saw there is also another similar PR from 2 days ago: #7754

I wonder if we can somehow include different approaches but at the same time make it clear which one is for whom 🤔

PhilipMetzger

another minor round

PhilipMetzger · 2025-10-19T15:54:22Z

docs/guides/coming-from-git.md

+jj bookmark set fix-login -r @
+# this means I set a new bookmark in the latest/current commit (signified by @)


nit: In both this example and the next one you use bookmark set which has upserting behavior if you mistype the bookmark name. It should be jj bookmark move <name> which avoids this failure mode.

I had the thought to use jj bookmark create for the first one. I'll do that and then use move for the second example.

PhilipMetzger · 2025-10-19T15:55:35Z

docs/guides/coming-from-git.md

+# prepare new commit following the last one, part of fix-login branch
+```
+
+...and that's the end of a standard GitHub workflow.


nit: "end of a standard GitHub workflow" => "end of the standard GitHub workflow" since there's only one

PhilipMetzger · 2025-10-19T16:07:04Z

docs/guides/coming-from-git.md

+> concepts. In addition to this documentation, this
+> [blog post by Stavros](https://www.stavros.io/posts/switch-to-jujutsu-already-a-tutorial/)
+> is also recommended as a resource for familiarizing oneself with the basic
+> concepts.


optional: I'd prefer if we linked out to our tutorial and then link to stavros tutorial there.

sure! let me change that

Comparing to the existing getting started tutorial, this "Coming from Git" guide: * Goes farther and explains a full code change lifecycle * Assumes the reader is already familiar with the basic jujutsu concepts * Assumes an existing local git repository * Integrates GitHub as part of it and follows the GitHub PR flow * Each step is designed to be concise, focusing on a single concept/task * Has the purpose of allowing someone to use jujutsu immediately and figure out the rest of the stuff as they go

sirodoht requested a review from a team as a code owner October 11, 2025 17:04

github-actions bot previously requested changes Oct 11, 2025

View reviewed changes

sirodoht force-pushed the add-coming-from-git branch 2 times, most recently from a8ae7c9 to cd8afe7 Compare October 11, 2025 20:03

sirodoht force-pushed the add-coming-from-git branch from cd8afe7 to ca66caf Compare October 11, 2025 20:05

PhilipMetzger reviewed Oct 12, 2025

View reviewed changes

sirodoht force-pushed the add-coming-from-git branch from ca66caf to e15995d Compare October 19, 2025 11:52

joyously reviewed Oct 19, 2025

View reviewed changes

sirodoht force-pushed the add-coming-from-git branch from e15995d to ad82187 Compare October 19, 2025 15:24

PhilipMetzger reviewed Oct 19, 2025

View reviewed changes

sirodoht mentioned this pull request Oct 19, 2025

github: make validation script check to not fail on non-dismissable PRs #7772

Open

sirodoht force-pushed the add-coming-from-git branch from ad82187 to d4cb140 Compare October 19, 2025 16:54

sirodoht changed the title ~~Add Coming from Git guide in docs~~ docs: add coming from git guide Oct 20, 2025


		Ok, work done, how to push?

		`jj` does not have branches, it has `bookmarks`. Branches are like tree branches:

		jj bookmark set fix-login -r @
		# this means I set a new bookmark in the latest/current commit (signified by @)

docs: add coming from git guide #7704

Are you sure you want to change the base?

docs: add coming from git guide #7704

Conversation

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

Uh oh!

Uh oh!

google-cla bot commented Oct 11, 2025

Uh oh!

github-actions bot 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!

martinvonz commented Oct 11, 2025

Uh oh!

joyously commented Oct 11, 2025

Uh oh!

sirodoht commented Oct 11, 2025

Uh oh!

PhilipMetzger left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sirodoht commented Oct 19, 2025

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!

sirodoht commented Oct 19, 2025

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sirodoht commented Oct 11, 2025 •

edited

Loading

github-actions bot left a comment •

edited

Loading