Dynamic completions wishlist

[senekor]

As dynamic completions are being worked on, let's use this issue to gather ideas for possible completions in one place. I'll try to keep the list in the issue description up to date according to the discussion below.

• add dynamic completions #4737
• completion: teach commands about bookmark names #4828
• completion: teach forget about workspaces #4869
• completion: teach jj about aliases #4832
  • completion: resolve aliases #4816
• completion: teach commands about revisions #4873
  • completion: include bookmarks and tags in revisions #4900
• completion: teach commands about files #4887
  • completion: teach log about files #4898
  • completion: suggest file paths incrementally #4895
• completion: teach remote about existing names #4817
• completion: teach operation commands about ids #4868
• completion: teach config about keys #4891
  • Don't just complete static keys, but also dynamic ones, like user-defined aliases.
    (probably not that useful...)

open questions:

• Should we allow snapshotting of the working copy, so that e.g. jj commit/squash/split <TAB> works without having to run another jj command first?
  -> No. Besides the performance impact, it would be confusing for users if hitting TAB in their shell could modify the state of their repository. Users can enable file watching if they want snapshotting to occur automatically.

places to scrape for ideas and implementations:

• our wiki where manually written dynamic completions for specific shells have been shared, e.g. here
• completions of git
  -> The fish completions of git are 2.5k loc, I'm not reading that.

misc:

• polish: make use of CompletionCandidate::display_order to prioritize candidates appropriately and CompletionCandidate::help to display useful information about each candidate.
  -> All the PRs include these where it's obviously appropriate / useful. Good enough for now.

[bnjmnt4n]

Here's the features that I implemented for my custom Fish completions:

• Completion of aliases
• Completion of revisions for all commands
  • Short change IDs will be used as candidates for completion.
  • Revisions completed are customized based on the given command. Commands which mutate the repository will use the revset mutable() to get the list of completed revisions, while commands which do not mutate the repository will use the revset all().
  • There is a limit of 1000 changes shown.
  • Local and remote branches are also completed (they appear at the end of the list of completions).
• Completion of files for certain commands
  • If the command uses a -r or --from flag, the list of files is read from the given revision.
  • Otherwise, the list of files are read from the given working copy.
  • file show, file chmod, interdiff: List of files in revision
  • commit: List of modified files in working copy
  • split, squash: List of modified files in revision
  • resolve: List of conflicted files in revision
  • restore, untrack: List of files in revision, or modified files if in working copy
  • TODO: Should we allow snapshotting of the working copy, so that e.g. jj commit/squash/split <TAB> works without having to run another jj command first?
• Completion of bookmark names for jj bookmark and jj git
• Completion of remote names for jj remote and jj git push
• Completion of operation IDs for jj undo and jj operation

[senekor]

Awesome, thank you so much!

Otherwise, the list of files are read from the given working copy.

Is this different from telling the shell to use its built-in file path completion? clap has some specific hints that don't require dynamic completions. I guess the difference would be the inclusion of gitignored files?

Should we allow snapshotting of the working copy, so that e.g. jj commit/squash/split works without having to run another jj command first?

I have currently disabled it in my PR. We could allow it for those commands specifically, so we don't incur the performance overhead on commands where it doesn't matter. I have never tried it, but there is the file watcher option for snapshotting too, right? So if users run into performance problems, they could solve it for themselves that way.

[bnjmnt4n]

Otherwise, the list of files are read from the given working copy.

Is this different from telling the shell to use its built-in file path completion? clap has some specific hints that don't require dynamic completions. I guess the difference would be the inclusion of gitignored files?

To clarify, here's the full original statement:

• If the command uses a -r or --from flag, the list of files is read from the given revision.
• Otherwise, the list of files are read from the given working copy.

This will allow file completion of paths at a different revision e.g. jj restore --from XXX file[TAB] can provide a completion if the file doesn't exist in the current working directory but exists in the given revision. Additionally, jj also permits sparse working copies which means that a file might not be checked out in the working directory, but it will still be helpful to do e.g. jj file show file[TAB].

[senekor]

Aah, I didn't think about sparse checkouts, that makes sense!

[senekor]

Alright, I'm just about out of steam here. I'll carry the currently open PRs across the finish line, but I'm not planning to do more than that.

The only thing remaining on the list right now is dynamic configuration keys. (e.g. jj config get --user aliases.<TAB> completes your user-defined aliases) While I did come up with that, it doesn't seem very useful to me now. I would probably just open the config file in an editor if I needed to check my aliases.

If people come up with other cool completions, anyone should feel free to claim the work and not wait for me 🙂

[martinvonz]

Alright, I'm just about out of steam here. I'll carry the currently open PRs across the finish line, but I'm not planning to do more than that.

Thank you!

If people come up with other cool completions, anyone should feel free to claim the work and not wait for me 🙂

I think the most valuable next item might be completion of revision arguments.

[senekor]

I think the most valuable next item might be completion of revision arguments.

That one is actually already merged: #4873

It just wasn't on the list here. (fixed now) I constantly had issues with editing the issue text. GitHub would always reset previous edits I had made. Very frustration. I'm never going to use GitHub issues as a "living document" anymore. (That's what we have version control for, right? 😄)

[martinvonz]

That one is actually already merged: #4873

Ah, I had missed that. So we just need to extend that to support completion of local and remote branches and tags then.

[senekor]

True, that must've slipped off the list as well...

edit: done #4900

[bnjmnt4n]

Thanks so much for taking this up @senekor! I've been using the dynamic completions very happily and thrown away my custom Fish completions.

[senekor]

That's great to hear! I always had a tab open with your completions as reference. They were a huge help, especially for the more difficult stuff like revisions and files.

Btw. at least in fish, the dynamic completions can still be supplemented with custom ones without issue. This is very useful in combination with jj util exec aliases. For example, I have a jj clone script which completes the repo url based on previously used hosts and orgs. Makes my script feel like a native part of jj.