mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2025-01-17 17:55:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

docs: fix broken Markdown in github.md, plus various cleanups

Browse source 
While fixing the broken Markdown, I also went through the whole doc
and made various little improvements (hopefully).

Closes #2426.
This commit is contained in:
Martin von Zweigbergk 2023-10-24 14:09:13 -07:00 committed by Martin von Zweigbergk
parent 5e407982b1
commit 3a7d21043e
1 changed files with 83 additions and 65 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

148
docs/github.md
View file

@ -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 <branchname>` 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]