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? (Googled for “X”, opened the docs, etc)

4- What did you find (CLI help, doc pages, blog posts, github issues) — and did it help you, or misled you?

[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

[yuja]

is it a bug in the behaviour I saw? It appears to me to be the documented intent like I can push to multiple remotes in git.

It works as intended. I personally don't think the bookmarks doc is misleading. Perhaps, the help text of jj git push can be improved to explicitly state that it pushes bookmarks to the specified remote (or the default remote), not to the "all" tracked remotes.

[nrbray]

I personally don't think the bookmarks doc is misleading.

I've been using "git push" to push to multiple remotes. I missed the full meaning in the documentation:

# jj git push

Push to a Git remote
...

Only after your comment do I realise that jj git push <--any-option> will push to only one remote, and I think that could be made more explicit if indeed there is no way to push to multiple remotes (in one command) with jj like I think git does.

The name --tracked implies plural, and I interpreted that as multiple remotes as well as multiple bookmarks. I think it would help to distinguish here also since the whole text for jj git begins Commands for working with Git remotes.

Having missed the full meaning of the first line, there is the documentation for --remote that is phrased in terms of one remote, but it was not obvious to me that for --tracked the singular remote also applied (having missed the "a Git remote" above.

--remote <REMOTE> — The remote to push to (only named remotes are supported)

This defaults to the git.push setting. If that is not configured, and if there are multiple remotes, the remote named "origin" will be used. Unlike in Git, the default remote is not derived from the tracked remote bookmarks.

Thank you for the clarification.

[arxanas]

FWIW, the common misunderstanding is that, in git push, the user chooses the branch to push (and the remote is implicitly selected by default), whereas in jj git push, the user chooses the remote to push to (and the bookmarks are implicitly selected by default.)

Thanks, that clarifies things for me.

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.
They don't always? The main branch usually moves forward in one remote if these two repositories are synced occasionally. If they aren't, it's better to not track both main branches.

@yuja In the case of a fork and using jj in a distributed manner, what is the recommended way of tracking both repos? I have done precisely this in Git and tracked the same branch for two different forks, and merged or rebased between one or the other as appropriate (or simply not merged changes from one into the other in the case that those changes were not meant to be upstreamed).

It appears to me to be the documented intent like I can push to multiple remotes in git.

@nrbray Is it the case in git that you can push to multiple remotes with a single git push invocation? For my understanding, did that determine your intuition here? Did you intuit that you should or shouldn't be able to push to multiple remotes solely because of the documentation, or also because of any expectations from git itself?

Perhaps, the help text of jj git push can be improved to explicitly state that it pushes bookmarks to the specified remote (or the default remote), not to the "all" tracked remotes.

I think with regard to the original quote "a single local bookmark can be tracking remote bookmarks on multiple remotes", I was also somehow misled into thinking that the jj git push operation will push to all remotes. However, it's difficult to suggest more natural wording/documentation that will emphasize appropriately that jj git push still only pushes to one remote.

[idle thought] We should expect the UX and documentation for commands regarding the distributed workflows to be fundamentally difficult, so it's not really surprising/unexpected that it may require a lot of iteration.

Having missed the full meaning of the first line, there is the documentation for --remote that is phrased in terms of one remote, but it was not obvious to me that for --tracked the singular remote also applied (having missed the "a Git remote" above.

The most effective solution here might be to add info text to jj git push explaining how it selected the remote and/or bookmarks to push (but of course we should try to adjust documentation as well). If it had said something like this (rough):

$ jj git push --tracked
Pushing to default remote: origin (https://github.com/foo)
hint: to configure the default push remote, run: jj config set --repo git.push 'remote'
hint: to push to a different remote, pass `--remote`  # maybe only shown if you have multiple configured remotes, or not at all
Pushing changes to 1 local bookmark tracking `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. 

then it 1) might have been clearer that it operates on a per-remote basis, even if you want to push all tracked branches, and 2) would offer natural onboarding rails for learning about relevant configuration.

We can also consider hints/warnings for cases of tracking multiple remotes, if we think it's particularly likely that users won't realize the nuances.

[tangential] I'm guessing some faction of users works primarily in a "two-remote" setup, with the push-remote being their fork of the repo and the fetch-remote being the upstream repo. I don't know if there's anything in particular that's likely to affect them regarding this comment thread. For those users, it seems a little unfortunate to work at the "remote" level of abstraction rather than the "bookmark" level, because pushing to the wrong remote could result in an error in the best case or overwriting work/shared history in the worst case. I don't know if that arises for users in practice, though.

[yuja]

@yuja In the case of a fork and using jj in a distributed manner, what is the recommended way of tracking both repos?

I would just use remote refs <name>@<remote> unless I had to update these remote branches separately, by myself. There's no way for jj to manage them totally unrelated bookmarks locally. It could be implemented, but the UI would become more complicated.

Regarding the jj git push help, I think we can insert something like "Unlike Git, the remote to push to ..." to the command description. I never considered --tracked would imply multiple remotes, but if that's the case, --all might be also confused as --all-bookmarks-and-remotes.

[nrbray]

@nrbray Is it the case in git that you can push to multiple remotes with a single git push invocation? For my understanding, did that determine your intuition here? Did you intuit that you should or shouldn't be able to push to multiple remotes solely because of the documentation, or also because of any expectations from git itself?

@arxanas Yes, you can push to multiple remotes with a single git push. My thoughts here (now with the jj documentation) are that the name git push is used with over a decade of learning attached to it. jj seems to use this name with a different behaviour in some cases, so perhaps it is wise to clarify that a little more explicitly.

Regarding the jj git push help, I think we can insert something like "Unlike Git, the remote to push to ..." to the command description. I never considered --tracked would imply multiple remotes, but if that's the case, --all might be also confused as --all-bookmarks-and-remotes.

@yuja I think your suggestion is a good way forward and believe there is reason to be confused in each case for those familiar with the behaviour of git push with multiple remotes. Words "Unlike git" and "only one remote" might be used in each part of the jj git push documentation to be clear.