Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add FAQ for keeping changes to tracked files #4320

Merged
merged 1 commit into from
Sep 4, 2024

Conversation

jennings
Copy link
Contributor

(I'm fine with having this whole PR changed or even rejected. Since this is a docs change, I figured it was easiest to just make the PR rather than trying to pre-approve it in chat.)

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.

Checklist

If applicable:

  • I have updated CHANGELOG.md
  • I have updated the documentation (README.md, docs/, demos/)
  • I have updated the config schema (cli/src/config-schema.json)
  • I have added tests to cover my changes

Copy link
Contributor

@PhilipMetzger PhilipMetzger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While I don't think this will be rejected, as it certainly got popular as a question. There's just some word forgery and simplifications left.

docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
@ilyagr
Copy link
Contributor

ilyagr commented Aug 23, 2024

Thank you! I think this is useful to add.

I was mildly worried it might be distracting (and if others people feel stronger about this, feel free to chime in), but if the FAQ gets too long, we could always split it into sections with these two questions in its own section.

@jennings jennings force-pushed the jennings/push-totwnvvsttup branch 2 times, most recently from 2ba0a2d to ef76f2e Compare August 23, 2024 15:44
Copy link
Contributor

@PhilipMetzger PhilipMetzger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I'd wait for another round of feedback from Ilya though.

docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
docs/FAQ.md Outdated Show resolved Hide resolved
@ilyagr
Copy link
Contributor

ilyagr commented Sep 2, 2024

This PR might become out of date once/if #4338 goes in.

@ilyagr
Copy link
Contributor

ilyagr commented Sep 2, 2024

Actually, on second thought, only the tiny part of this PR that has to do with the "scratch files" question overlaps with #4338, so I may have spoken too soon..

docs/FAQ.md Show resolved Hide resolved
@jennings jennings force-pushed the jennings/push-totwnvvsttup branch from ef76f2e to f662724 Compare September 3, 2024 17:51
@jennings
Copy link
Contributor Author

jennings commented Sep 3, 2024

I just noticed that the next question already in the FAQ is "How can I keep local changes around, but not use them for Pull Requests?". That answer recommends doing either:

  1. Rebasing the branch on top of the private commit, then rebasing back on top of main before pushing
  2. Rebase the private commit on top of the branch, then jj new

This PR gives a third option, creating a merge commit. This is the technique I've seen recommended in Discord lately. I think three options is too many for someone relatively new to Jujutsu, I think we should be more prescriptive until they are comfortable. So I removed the original question entirely. I'm open to changing this decision if people don't like it.

Copy link
Contributor

@ilyagr ilyagr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks pretty good to me. Thank you!

I just noticed that the next question already in the FAQ is "How can I keep local changes around, but not use them for Pull Requests?".

Replacing that question seems to me like it works quite well.

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.
@jennings jennings force-pushed the jennings/push-totwnvvsttup branch from f662724 to ad7bb43 Compare September 4, 2024 00:12
@jennings jennings enabled auto-merge (rebase) September 4, 2024 00:13
@jennings jennings merged commit 1c672d7 into jj-vcs:main Sep 4, 2024
18 checks passed
@jennings jennings deleted the jennings/push-totwnvvsttup branch September 4, 2024 01:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants