Skip to content

Commit

Permalink
docs: Add FAQ for keeping changes to tracked files
Browse files Browse the repository at this point in the history
The question "How do I avoid committing changes to files?" comes up a lot in
chat, and the solution is not obvious. It will be useful to have a description
with an example we can link to.

The wording of the similar question "How can I keep my scratch files in the
repository?" was tweaked to emphasize the difference between keeping untracked
files in the workspace and keeping changes tracked files out of published
history.
  • Loading branch information
jennings committed Aug 23, 2024
1 parent 352a4a0 commit ef76f2e
Showing 1 changed file with 74 additions and 1 deletion.
75 changes: 74 additions & 1 deletion docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ which may require multiple invocations of `jj rebase -r` or `jj rebase -s`.

To squash or split commits, use `jj squash` and `jj split`.

### How can I keep my scratch files in the repository?
### How can I create scratch files without committing them to the repository?

You can keep your notes and other scratch files in the repository, if you add
a wildcard pattern to either the repo's `gitignore` or your global `gitignore`.
Expand All @@ -111,6 +111,79 @@ store arbitrary files in `<your-git-repo>/scratch/`.

You can find more details on `gitignore` files [here][gitignore].

### How can I avoid committing my local-only changes to tracked files?

Suppose your repository tracks a file like `secret_config.json`, and you make
some changes to that file to work locally. Since Jujutsu automatically commits
the working copy, there's no way to prevent Jujutsu from committing changes to
the file. But, you never want to push those changes to the remote repository.

One solution is to keep these changes in a separate commit branched from the
trunk and _merge_ the private commit into your branch to use those changes.

Suppose you have a commit "Add new feature":

```shell
$ jj log
@ mmzpqlum [email protected] 2024-08-21 11:13:21 ef612875
│ Add new feature
◉ tvxsnxqm [email protected] 2024-08-21 11:13:09 main b624cf12
│ Existing work
~
```

First, create a new commit branched from main and add your private changes:

```shell
$ jj new main -m "private: my credentials"
Working copy now at: ttsqqnrx 861de9eb (empty) private: my credentials
Parent commit : tvxsnxqm b624cf12 main | Existing work
Added 0 files, modified 1 files, removed 0 files

$ echo '{ "password": "p@ssw0rd1" }' > secret_config.json
```

Now create a merge commit with the branch you're working on and the private
commit:

```shell
$ jj new mmzpqlum ttsqqnrx
Working copy now at: wktxklmk ac4d9fbe (empty) (no description set)
Parent commit : mmzpqlum ef612875 Add new feature
Parent commit : ttsqqnrx 2106921e private: my credentials
Added 0 files, modified 1 files, removed 0 files

$ jj log
@ wktxklmk [email protected] 2024-08-22 08:57:40 ac4d9fbe
├─╮ (empty) (no description set)
│ ◉ ttsqqnrx [email protected] 2024-08-22 08:57:40 2106921e
│ │ private: my credentials
◉ │ mmzpqlum [email protected] 2024-08-21 11:13:21 ef612875
├─╯ Add new feature
◉ tvxsnxqm [email protected] 2024-08-21 11:13:09 main b624cf12
│ Existing work
~
```

The revision _ttsqqnrx_ contains changes from both _mmzpqlum_ and _ttsqqnrx_. As
you work, squash your changes using `jj squash --into mmzpqlum`. Or, you can
keep your changes in a separate commit and remove _ttsqqnrx_ as a parent:

```shell
# Remove the private commit as a parent
$ jj rebase -r wktxklmk -d mmzpqlum

# Create a new merge commit to work in
$ jj new wktxklmk ttsqqnrx
```

To avoid pushing change _ttsqqnrx_ by mistake, use the configuration
[git.private-commits](config.md#set-of-private-commits):

```
$ jj config set --user git.private-commits 'description(glob:"private:*")'
```

### How can I keep local changes around, but not use them for Pull Requests?

In general, you should separate out the changes to their own commit (using
Expand Down

0 comments on commit ef76f2e

Please sign in to comment.