diff --git a/docs/guides/coming-from-git.md b/docs/guides/coming-from-git.md new file mode 100644 index 00000000000..454f9807c8f --- /dev/null +++ b/docs/guides/coming-from-git.md @@ -0,0 +1,143 @@ +# Coming from Git + +> This tutorial is about guiding someone who has a working Git repository +> to get started with Jujutsu quickly. It assumes the reader is at least vaguely +> familiar with the basics. Get started with understanding the basic concepts at +> our [tutorial](../tutorial.md). + +## Minimal risk + +Since Jujutsu is compatible with Git, you can colocate a Jujutsu repository +and an existing Git repository. This makes adopting Jujutsu very easy as well as +minimally risky: if something breaks or you want to go back, just delete your +project's `.jj/` directory. + +## jj init for existing Git repositories + +Assuming you have [installed](../install-and-setup.md) Jujutsu, you can +initialize a +[colocated repository](../git-compatibility/#colocated-jujutsugit-repos) +in an existing Git repository on your computer like so: + +```sh +cd ~/whatever/project +jj git init +``` + +You can even do this in a Git repository with a dirty working directory. + +## Write the code + +Write some code or decide it's time for a commit for some of your current +changes in the working directory. + +Write the commit message: + +```sh +jj describe +``` + +Awesome! On most `jj` commands, the first thing Jujutsu will do is auto-commit +all changes (with an empty commit message), so what you just did with +`jj describe` is to write this _existing_ commit's message. This commit +includes all the current changes. + +## Splitting instead of committing + +You wrote a bunch of code but some of it can't go in that single commit. What +you do now is: + +```sh +jj split +``` + +Now, if you have a terminal without a mouse (or have mouse completely disabled +in your terminal because it constantly gets in the way, like I do) this next +screen might confuse you. Interestingly, it was the reason I gave up on jj the +first time. Here's how this "interactive" screen works: + +1. Use the arrows to go up and down the file list +1. Hit space to select the files that will go to the first commit +1. Press `c` to confirm your selection +1. Change the commit message for that first commit, and save +1. Change the commit message for that second commit, and save + +Of course, for that second commit, you might decide to split again later. That's +part of the game. + +## Time to push + +Ok, work done, how to push? + +We don't push branches in Jujutsu as we do in Git. Instead, we push `bookmarks`. +Branches are like tree branches: they fork off `main` and grow. Bookmarks are +like book _marks_: you constantly grow the book and at some points you put +bookmarks. This means that in Git every new commit is automatically part of a +growing branch. In Jujutsu, every new commit is part of the whole book and +nothing else. If you want it to be part of a Git branch, you assign a bookmark +to it: + +```sh +jj bookmark create fix-login -r @ +# this means I create a new bookmark in the latest/current commit (signified by @) + +jj git push -b fix-login --allow-new +# this means push bookmark/branch to default origin and also create the branch +``` + +## Two small tips + +You can always do: + +```sh +jj status +# or jj st +``` + +to see an overview of the working directory. + +You can always do: + +```sh +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. + +## More changes + +You pushed your bookmark branch, opened a PR on GitHub, asked for review, and +some annoying nitpickers ask for changes. Fine: + +```sh +vim code.txt +# :wq +jj describe -m "fix serious issue" + +jj bookmark move -f fix-login -t @ +# this means move the fix-login bookmark from [-f] its original place to [-t] latest commit (aka @) + +jj git push -b fix-login +# and then just push +``` + +## Concluding the workflow + +After pushing the changes, you get an approval, and merge your PR. Now what? +Pull changes: + +```sh +jj git fetch +# git fetch, classic + +jj new main +# prepare new commit following the latest commit of main branch, not fix-login + +# or: +jj new +# prepare new commit following the last one, part of fix-login branch +``` + +...and that's the end of the standard GitHub workflow. diff --git a/docs/tutorial.md b/docs/tutorial.md index 89e06992b22..599897b4b25 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -5,7 +5,10 @@ > range of features, you may find the (not quite finished) [tutorial by Steve > Klabnik](https://steveklabnik.github.io/jujutsu-tutorial/) helpful. If you're > looking for a tutorial that doesn't require experience with Git, take a look -> at [Jujutsu for everyone](https://jj-for-everyone.github.io). +> at [Jujutsu for everyone](https://jj-for-everyone.github.io). Finally, check +> out [Stavros' tutorial](https://www.stavros.io/posts/switch-to-jujutsu-already-a-tutorial/) +> for a high-level mental model and an FAQ to help you think in Jujutsu concepts +> rather than Git concepts. This text assumes that the reader is familiar with Git.