From ef76f2ed1dc0f684e374f97be04c761bdc7a121e Mon Sep 17 00:00:00 2001 From: Stephen Jennings Date: Thu, 22 Aug 2024 08:42:51 -0700 Subject: [PATCH] docs: Add FAQ for keeping changes to tracked files 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. --- docs/FAQ.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 07f5b72d31..4ed7a8f672 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -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`. @@ -111,6 +111,79 @@ store arbitrary files in `/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 me@example.com 2024-08-21 11:13:21 ef612875 +│ Add new feature +◉ tvxsnxqm me@example.com 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 me@example.com 2024-08-22 08:57:40 ac4d9fbe +├─╮ (empty) (no description set) +│ ◉ ttsqqnrx me@example.com 2024-08-22 08:57:40 2106921e +│ │ private: my credentials +◉ │ mmzpqlum me@example.com 2024-08-21 11:13:21 ef612875 +├─╯ Add new feature +◉ tvxsnxqm me@example.com 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