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

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 # 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 ## 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 ## 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 ```shell script
# Start a new commit off of `main` # Start a new commit off of `main`
@ -25,21 +27,23 @@ $ jj branch create bar -r @-
$ jj git push $ jj git push
``` ```
While it's possible to create a branch and commit on top of it in a Git like 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. manner, it's not recommended, as no further commits will be placed on the
branch.
## 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 As of December 2022, Jujutsu has no equivalent to a `git pull` command. Until
`jj git rebase -d $main_branch` to update your changes. 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 ## 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 ```shell script
$ nvim docs/tutorial.md $ nvim docs/tutorial.md
@ -52,9 +56,10 @@ $ jj git push
``` ```
## Working in a Jujutsu repository ## 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 In a Jujutsu repository, the workflow is simplified. If there's no need for
is able to create a branch for a revision. explicitly named branches, you just can generate one for a change. As Jujutsu is
able to create a branch for a revision.
```shell script ```shell script
$ # Do your work $ # Do your work
@ -63,19 +68,23 @@ $ # Jujutsu automatically creates a branch
$ jj git push --change $revision $ jj git push --change $revision
``` ```
## Adressing review comments ## 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 There are two workflows for addressing review comments, depending on your
commits to your branch[^1]. Some projects (such as Jujutsu and LLVM) instead project's preference. Many projects prefer that you address comments by adding
prefer that you keep your commits clean by rewriting them and then force-pushing[^2]. 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 ```shell script
$ # Create a new commit on top of the `your-feature` branch from above. $ # Create a new commit on top of the `your-feature` branch from above.
$ jj new your-eature $ jj new your-eature
$ # Adress the comments, by updating the code $ # Address the comments, by updating the code
$ jj diff $ jj diff
$ # Give the fix a description and create a new working-copy on top. $ # Give the fix a description and create a new working-copy on top.
$ jj commit -m 'address pr comments' $ jj commit -m 'address pr comments'
@ -86,8 +95,10 @@ $ jj git push.
``` ```
### Rewriting commits ### 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 ```shell script
$ # Create a new commit on top of the second-to-last commit in `your-feature`, $ # Create a new commit on top of the second-to-last commit in `your-feature`,
$ # as reviews requested a fix there. $ # as reviews requested a fix there.
@ -103,38 +114,48 @@ $ jj git push --branch your-feature
## Useful Revsets ## Useful Revsets
Log all revisions across all local branches, which aren't on the main branch Log all revisions across all local branches, which aren't on the main branch nor
nor on any remote on any remote
`jj log -r 'branches() & ~(main | remote_branches())'` `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 remote
`jj log -r 'author(your@email.com) & branches() & ~remote_branches()'` `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))'` `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 Log all descendants of the current working copy, which aren't on a remote
`jj log -r ':@ & ~remote_branches()'` `jj log -r ':@ & ~remote_branches()'`
## Merge conflicts ## 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. [^1]: This is a GitHub Style review, as GitHub currently only is able to compare
[^2]: If you're wondering why we prefer clean commits in this project, see e.g.[this blog post][stacked] 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 [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 [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 [tut]: tutorial.md#Conflicts
[stacked]: https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/ [stacked]: https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/
## Using several remotes ## Using several remotes
It is common to use several remotes when contributing to a shared repository. For example, It is common to use several remotes when contributing to a shared repository.
"upstream" can designate the remote where the changes will be merged through a pull-request For example,
while "origin" is your private fork of the project. In this case, you might want to "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". `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`): (for example `.jj/repo/config.toml`):
```toml ```toml