diff --git a/docs/github.md b/docs/github.md index cc2ca2f57..f8c50dd94 100644 --- a/docs/github.md +++ b/docs/github.md @@ -4,22 +4,22 @@ This guide assumes a basic understanding of either Git or Mercurial. ## Set up an SSH key -As of December 2022 it's recommended to set up an SSH key to work with GitHub +As of October 2023 it's recommended to set up an SSH key to work with GitHub projects. See [GitHub's Tutorial][gh]. This restriction may be lifted in the future, see [issue #469][http-auth] for more information and progress on -authenticated http. +authenticated HTTP. ## Basic workflow The simplest way to start with Jujutsu is to create a stack of commits first. -You will only need to create a branch when you need to push the stack to a -remote. There are two primary workflows, using a generated branch name or +You will only need to create a branch when you need to push the stack to a +remote. There are two primary workflows: using a generated branch name or naming a branch. ### Using a generated branch name In this example we're letting Jujutsu auto-create a branch. - + ```shell # Start a new commit off of the default branch. $ jj new main @@ -27,7 +27,9 @@ $ jj new main $ jj commit -m 'refactor(foo): restructure foo()' # Add a feature, then add a description and start a new commit $ jj commit -m 'feat(bar): add support for bar' -# Let Jujutsu generate a branch name and push that to GitHub +# Let Jujutsu generate a branch name and push that to GitHub. Note that we +# push the working-copy commit's *parent* because the working-copy commit +# itself is empty. $ jj git push -c @- ``` @@ -42,51 +44,56 @@ $ jj new main $ jj commit -m 'refactor(foo): restructure foo()' # Add a feature, then add a description and start a new commit $ jj commit -m 'feat(bar): add support for bar' -# Create a branch so we can push it to GitHub -$ jj branch create bar -r @- # create a branch `bar` that now contains the previous two commits. +# Create a branch so we can push it to GitHub. Note that we created the branch +# on the working-copy commit's *parent* because the working copy itself is empty. +$ jj branch create bar -r @- # `bar` now contains the previous two commits. # Push the branch to GitHub (pushes only `bar`) $ jj git push ``` -While it's possible to create a branch and commit on top of it in a Git-like -manner, you will then need to move the branch manually when you create a new -commits. Unlike Git, Jujutsu will not do it automatically . +While it's possible to create a branch in advance and commit on top of it in a +Git-like manner, you will then need to move the branch manually when you create +a new commits. Unlike Git, Jujutsu will not do it automatically. -## Updating the repository. +## Updating the repository -As of December 2022, Jujutsu has no equivalent to a `git pull` command. Until -such a command is added, you need to use `jj git fetch` followed by a -`jj rebase -d $main_branch` to update your changes. +As of October 2023, Jujutsu has no equivalent to a `git pull` command (see +[issue #1039][sync-issue]). Until such a command is added, you need to use +`jj git fetch` followed by a `jj rebase -d $main_branch` to update your +changes. + +[sync-issue]: https://github.com/martinvonz/jj/issues/1039 ## Working in a Git co-located repository -After doing `jj init --git-repo=.`, git will be in -a [detached HEAD state][detached], which is unusual, as git mainly works with -branches. In a co-located repository, `jj` isn't the source of truth. But -Jujutsu allows an incremental migration, as `jj commit` updates the HEAD of the -git repository. +After doing `jj init --git-repo=.`, Git will be in +a [detached HEAD state][detached], which is unusual, as Git mainly works with +branches. In a co-located repository, every `jj` command will automatically +synchronize Jujutsu's view of the repo with Git's view. For example, +`jj commit` updates the HEAD of the Git repository, enabling an incremental +migration. ```shell $ nvim docs/tutorial.md $ # Do some more work. $ jj commit -m "Update tutorial" -$ jj branch create doc-update -$ # Move the previous revision to doc-update. -$ jj branch set doc-update -r @- +# Create a branch on the working-copy commit's parent +$ jj branch create doc-update -r @- $ jj git push ``` ## Working in a Jujutsu repository In a Jujutsu repository, the workflow is simplified. If there's no need for -explicitly named branches, you just can generate one for a change. As Jujutsu is +explicitly named branches, you can just generate one for a change. As Jujutsu is able to create a branch for a revision. ```shell $ # Do your work $ jj commit -$ # Push change "mw", letting Jujutsu automatically create a branch called "push-mwmpwkwknuz" -$ jj git push --change mw +$ # Push change "mw", letting Jujutsu automatically create a branch called +$ # "push-mwmpwkwknuz" +$ jj git push --change mw ``` ## Addressing review comments @@ -105,7 +112,7 @@ top, you can do that by doing something like this: ```shell $ # Create a new commit on top of the `your-feature` branch from above. $ jj new your-feature -$ # Address the comments, by updating the code +$ # Address the comments by updating the code. Then review the changes. $ jj diff $ # Give the fix a description and create a new working-copy on top. $ jj commit -m 'address pr comments' @@ -115,8 +122,8 @@ $ # Push it to your remote $ jj git push ``` -Notably, the above workflow creates a new commit for you. The same can be -achieved without creating a new commit. +Notably, the above workflow creates a new commit for you. The same can be +achieved without creating a new commit. > **Warning** > We strongly suggest to `jj new` after the example below, as all further edits @@ -125,7 +132,7 @@ achieved without creating a new commit. ```shell $ # Create a new commit on top of the `your-feature` branch from above. $ jj new your-feature -$ # Address the comments, by updating the code +$ # Address the comments by updating the code. Then review the changes. $ jj diff $ # Give the fix a description. $ jj describe -m 'address pr comments' @@ -142,23 +149,24 @@ something like this: ```shell $ # Create a new commit on top of the second-to-last commit in `your-feature`, -$ # as reviews requested a fix there. +$ # as reviewers requested a fix there. $ jj new your-feature- # NOTE: the trailing hyphen is not a typo! -$ # Address the comments by updating the code -$ # Review the changes +$ # Address the comments by updating the code. Then review the changes. $ jj diff $ # Squash the changes into the parent commit $ jj squash -$ # Push the updated branch to the remote. Jujutsu automatically makes it a force push +$ # Push the updated branch to the remote. Jujutsu automatically makes it a +$ # force push $ jj git push --branch your-feature ``` -The hyphen after `your-feature` comes from [revset](https://github.com/martinvonz/jj/blob/main/docs/revsets.md) syntax. +The hyphen after `your-feature` comes from the +[revset](https://github.com/martinvonz/jj/blob/main/docs/revsets.md) syntax. ## Working with other people's branches By default `jj git clone` and `jj git fetch` clone all active branches from -the remote. This means that if you want to iterate or test another +the remote. This means that if you want to iterate or test another contributor's branch you can `jj new ` onto it. If your remote has a large amount of old, inactive branches or this feature is @@ -168,7 +176,7 @@ You can find more information on that setting [here][auto-branch]. ## Using GitHub CLI -GitHub CLI will have trouble finding the proper git repository path in jj repos +GitHub CLI will have trouble finding the proper Git repository path in jj repos that aren't [co-located](./git-compatibility.md#co-located-jujutsugit-repos) (see [issue #1008]). You can configure the `$GIT_DIR` environment variable to point it to the right path: @@ -178,8 +186,8 @@ $ GIT_DIR=.jj/repo/store/git gh issue list ``` You can make that automatic by installing [direnv](https://direnv.net) and -defining hooks in a .envrc file in the repository root to configure `$GIT_DIR`. -Just add this line into .envrc: +defining hooks in a `.envrc` file in the repository root to configure `$GIT_DIR`. +Just add this line into `.envrc`: ```shell export GIT_DIR=$PWD/.jj/repo/store/git @@ -193,52 +201,62 @@ commands like `gh issue list` normally. ## Useful Revsets -Log all revisions across all local branches, which aren't on the main branch nor -on any remote -`jj log -r 'branches() & ~(main | remote_branches())'` -Log all revisions which you authored, across all branches which aren't on any -remote -`jj log -r 'mine() & branches() & ~remote_branches()'` -Log all remote branches, which you authored or committed to -`jj log -r 'remote_branches() & (mine() | committer(your@email.com))'` -Log all descendants of the current working copy, which aren't on a remote -`jj log -r '::@ & ~remote_branches()'` +Log all revisions across all local branches that aren't on the main branch nor +on any remote: + +```shell +$ jj log -r 'branches() & ~(main | remote_branches())' +``` + +Log all revisions that you authored, across all branches that aren't on any +remote: + +```shell +$ jj log -r 'mine() & branches() & ~remote_branches()' +``` + +Log all remote branches that you authored or committed to: + +```shell +$ jj log -r 'remote_branches() & (mine() | committer(your@email.com))' +``` + +Log all descendants of the current working copy that aren't on any remote: + +```shell +$ jj log -r '::@ & ~remote_branches()' +``` ## Merge conflicts For a detailed overview, how Jujutsu handles conflicts, revisit the [tutorial][tut]. -[^1]: This is a GitHub Style review, as GitHub currently only is able to compare -branches. +[^1]: + This is a GitHub-style review, as GitHub currently only is able to compare + branches. -[^2]: If you're wondering why we prefer clean commits in this project, see -e.g. [this blog post][stacked] +[^2]: + If you're wondering why we prefer clean commits in this project, see + e.g. [this blog post][stacked] [auto-branch]: config.md#automatic-local-branch-creation - [detached]: https://git-scm.com/docs/git-checkout#_detached_head - [gh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent - [http-auth]: https://github.com/martinvonz/jj/issues/469 - [tut]: tutorial.md#Conflicts - [stacked]: https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/ ## Using several remotes It is common to use several remotes when contributing to a shared repository. -For example, -"upstream" can designate the remote where the changes will be merged through a -pull-request while "origin" is your private fork of the project. In this case, -you might want to -`jj git fetch` from "upstream" and to `jj git push` to "origin". +For example, "upstream" can designate the remote where the changes will be +merged through a pull-request while "origin" is your private fork of the +project. In this case, you might want to `jj git fetch` from "upstream" and to +`jj git push` to "origin". You can configure the default remotes to fetch from and push to in your -configuration file -(for example `.jj/repo/config.toml`): +configuration file (for example `.jj/repo/config.toml`): ```toml [git]