Documentation feedback thread

[neongreen]

Inspired by the GitHub Docs feedback thread, let’s have one for jj docs as well.

Just copy the template below and add your answers.

---

1- What was your task / goal?

2- What information did you need?

3- How did you look for the information?

4- Were you successful in finding the information you needed? How did you know when you'd done so?

5- If you can, share a link to the information you used. Or, if there's any documentation you specifically liked/disliked, link to it as well.

[jjt]

i was trying to start a new branch from a descendant

i wanted to know what flags/args to pass to new

i opened the docs to search for that info and also look at other commands

my eyes found the blurb about the -A/—insert-after so i tried jj new -A REV which inserted a new commit in between two commits instead of a new branch tip, which someone on the discord helped me tojj new REV

a graph diagram like the one for prev would have helped immediately, or at the very least explicitly saying “for new branch tip at REV just jj new REV

the -B flag i understood would insert, because there’s no like… empty revset space to put a branch tip “before” and that just didn’t enter my brain as a possibility

[neongreen]

1- What was your task / goal?
Set up completion for revisions/bookmarks in zsh

2- What information did you need?
How to do it, ideally a one-liner that would append to my .zshrc

3- How did you look for the information?
Googled "jj completion"

4- Were you successful in finding the information you needed? How did you know when you'd done so?
❌ I found https://jj-vcs.github.io/jj/latest/install-and-setup/#command-line-completion and copied

autoload -U compinit
compinit
source <(jj util completion zsh)

but I didn't realize that for revisions I had to use the "dynamic" variant -- because I didn't actually read the text and just assumed dynamic was some kind of a fallback when compinit can't be used

Generally if I see a block of code and assume I know what it does, I don't read the text

[arxanas]

1. RIP
2. the documentation doesn't really list the downsides of enabling dynamic completions; my expectation would be that a) dynamic completions are potentially slower since they probably involve executing some subprocesses that may do non-trivial analysis of the repo state and b) they may have latent bugs, including possibly some which aren't fixable in the current design.

[nrbray]

Only one, 'origin', of my two tracked bookmarks gets pushed with jj git push --tracked

Documentation says: "a single local bookmark can be tracking remote bookmarks on multiple remotes, and the names of the local and remote bookmarks must match"

When I

$ jj git push --tracked
Changes to push to origin:
  Move forward bookmark main from f667764ae78a to 3504c351db58
Warning: The working-copy commit in workspace 'default' became immutable, so a new commit has been created on top of it. 

I have to

jj git push --remote dubedary

to get the other tracked bookmark:

Changes to push to dubedary:
  Move forward bookmark main from 7bbcba65517d to 3504c351db58

I have two tracking bookmarks:

$ jj bookmark list --tracked
main: wyonxpvw 3504c351 # Done: Work out how to invoke this from inside a module instead of the flake
  @dubedary: wyonxpvw 3504c351 # Done: Work out how to invoke this from inside a module instead of the flake
  @origin: wyonxpvw 3504c351 # Done: Work out how to invoke this from inside a module instead of the flake

[arxanas]

a single local bookmark can be tracking remote bookmarks on multiple remotes, and the names of the local and remote bookmarks must match

Docs link with this quote (last paragraph) for reference: https://jj-vcs.github.io/jj/v0.24.0/bookmarks/#terminology-summary

This issue is interesting, and I wonder if the documentation is incidentally misleading or fundamentally misleading. For example, it says this:

A tracking (local) bookmark is the local bookmark that jj tries to keep in sync with the tracked remote bookmark.

Is this really true? If there's multiple tracked remote bookmarks, how does jj decide which one to keep the local one in sync with?

• I guess it could just mark them as divergent in that case — but is that really what happens, and is that really what's supposed to happen?
• For example: I could easily imagine that two repositories' main branches would diverge in the case of a fork, and it wouldn't be an erroneous situation.

I also wonder if it's misleading to use "tracked" here since it may have specific connotations from Git that don't carry over. Or perhaps the semantics match Git for now, but only unintentionally due to a bug/omission:

• IIRC, in Git, a branch can track at most one "pull remote" and one "push remote", rather than an arbitrary number of remotes.
• It's possible that jj git push is implicitly using the same semantics, without the implementer having intended to ignore the other tracking remotes.