ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity

docs: fix some typos in github.md, and reformat it

Browse source
This commit is contained in:
Martin von Zweigbergk 2023-01-19 08:28:00 -08:00 committed by Martin von Zweigbergk
parent 24e03e2ff5
commit f7324768a7
1 changed files with 63 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

105
docs/github.md
View file

@ -1,16 +1,18 @@
# Using Jujutsu with GitHub and GitLab Projects
This guide assumes a basic understanding of either Git or Mercurial.
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
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.
As of December 2022 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.
## Basic workflow
The simplest way to start with Jujutsu, is creating a stack of commits, before
creating any branch.
The simplest way to start with Jujutsu, is creating a stack of commits, before
creating any branch.
```shell script
# Start a new commit off of `main`
@ -25,21 +27,23 @@ $ jj branch create bar -r @-
$ jj git push
```
While it's possible to create a branch and commit on top of it in a Git like
manner, it's not recommended, as no further commits will be placed on the branch.
While it's possible to create a branch and commit on top of it in a Git like
manner, it's not recommended, as no further commits will be placed on the
branch.
## 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 git rebase -d $main_branch` to update your changes.
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 git rebase -d $main_branch` to update your changes.
## 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 a 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, `jj` isn't the source of truth. But
Jujutsu allows an incremental migration, as `jj commit` updates the HEAD of the
git repository.
```shell script
$ nvim docs/tutorial.md
@ -52,9 +56,10 @@ $ 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 able to create a branch for a revision.
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
able to create a branch for a revision.
```shell script
$ # Do your work
@ -63,19 +68,23 @@ $ # Jujutsu automatically creates a branch
$ jj git push --change $revision
```
## Adressing review comments
There are two workflows for addressing review comments, depending on your
project's preference. Many projects prefer that you address comments by adding
commits to your branch[^1]. Some projects (such as Jujutsu and LLVM) instead
prefer that you keep your commits clean by rewriting them and then force-pushing[^2].
## Addressing review comments
There are two workflows for addressing review comments, depending on your
project's preference. Many projects prefer that you address comments by adding
commits to your branch[^1]. Some projects (such as Jujutsu and LLVM) instead
prefer that you keep your commits clean by rewriting them and then
force-pushing[^2].
### Adding new commits
If your project prefers that you address review comments by adding commits on
top, you can do that by doing something like this:
### Adding new commits
If your project prefers that you address review comments by adding commmits on
top, you can do that by doing something like this:
```shell script
$ # Create a new commit on top of the `your-feature` branch from above.
$ jj new your-eature
$ # Adress the comments, by updating the code
$ # Address the comments, by updating the code
$ jj diff
$ # Give the fix a description and create a new working-copy on top.
$ jj commit -m 'address pr comments'
@ -86,8 +95,10 @@ $ jj git push.
```
### Rewriting commits
If your project prefers that you keep commits clean, you can do that by doing
something like this:
If your project prefers that you keep commits clean, you can do that by doing
something like this:
```shell script
$ # Create a new commit on top of the second-to-last commit in `your-feature`,
$ # as reviews requested a fix there.
@ -103,38 +114,48 @@ $ jj git push --branch your-feature
## Useful Revsets
Log all revisions across all local branches, which aren't on the main branch
nor on any remote
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
Log all revisions which you authored, across all branches which aren't on any
remote
`jj log -r 'author(your@email.com) & branches() & ~remote_branches()'`
Log all remote branches, which you authored or commmited to
Log all remote branches, which you authored or committed to
`jj log -r 'remote_branches() & (comitter(your@email.com) | author(your@email.com))'`
Log all descendants of the current working copy, which aren't on a remote
`jj log -r ':@ & ~remote_branches()'`
## Merge conflicts
For a detailed overview, how Jujutsu handles conflicts, revisit the [tutorial][tut].
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.
[^2]: If you're wondering why we prefer clean commits in this project, see e.g.[this blog post][stacked]
[^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]
[detached head]: 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
[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
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".
You can configure the default remotes to fetch from and push to in your configuration file
You can configure the default remotes to fetch from and push to in your
configuration file
(for example `.jj/repo/config.toml`):
```toml