Skip to content

Commit

Permalink
Docs: Make github.md a bit clearer
Browse files Browse the repository at this point in the history
This adresses #1989
  • Loading branch information
PhilipMetzger committed Aug 27, 2023
1 parent 732e448 commit c00bb5e
Showing 1 changed file with 34 additions and 4 deletions.
38 changes: 34 additions & 4 deletions docs/github.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ 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`
# Start a new commit off of the default branch.
$ jj new main
# Refactor some files, then add a description and start a new commit
$ 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 @-
$ jj branch create bar -r @- # put the previous two commits on `bar`.
# Push the branch to GitHub (pushes only `bar`)
$ jj git push
```
Expand Down Expand Up @@ -65,7 +65,8 @@ able to create a branch for a revision.
$ # Do your work
$ jj commit
$ # Jujutsu automatically creates a branch
$ jj git push --change $revision
$ # Push change "mw", letting Jujutsu automatically create a branch called "push-mwmpwkwknuz"
$ jj git push --change mw
```

## Addressing review comments
Expand All @@ -91,7 +92,23 @@ $ jj commit -m 'address pr comments'
$ # Update the branch to point to the new commit.
$ jj branch set your-feature -r @-
$ # Push it to your remote
$ jj git push.
$ jj git push
```

Notably, the above workflow creates a new commit for you. The same can be
achieved without creating a new commit.

```shell script
$ # Create a new commit on top of the `your-feature` branch from above.
$ jj new your-feature
$ # Address the comments, by updating the code
$ jj diff
$ # Give the fix a description.
$ jj describe -m 'address pr comments'
$ # Update the branch to point to the current commit.
$ jj branch set your-feature -r @
$ # Push it to your remote
$ jj git push
```

### Rewriting commits
Expand All @@ -112,6 +129,17 @@ $ # Push the updated branch to the remote. Jujutsu automatically makes it a forc
$ jj git push --branch your-feature
```

## 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
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
undesirable, set `git.auto-local-branch = false` in the config file.

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
Expand Down Expand Up @@ -160,6 +188,8 @@ branches.
[^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
Expand Down

0 comments on commit c00bb5e

Please sign in to comment.