RFC: Command line usage

[13k]

Disclaimer: beware, wall of text ahead.

Abstract

Command line usage is pretty much ingrained in my workflows, as I suspect is for most vim users. Currently, the oni command lacks much of what would make it good for such usage.

I'm new to both neovim and oni, but I've used vim for more than 12 years and I want to switch to a modern version of vim. I tried both atom and vscode with vim emulation extensions, but it doesn't live up to expectations.

I have installed the rpm release package in Fedora, and everything I say here is in regards to using oni from the command line when installing it from release packages (not the npm package, neither from a dev checkout).

Motivation

I always start editors from the command line, mostly because:

a) I use the terminal when working on a project. I have tmux setup with sessions spawning panes and windows accordingly for each project. There's also a myriad of other command line tools that are used in development workflows.
b) To use the same environment in the editor as the environment set up in a). For example, variables set up according to several environment managers (pyenv, rbenv, nvm, gimme, rustup, etc). This enables development tools (debuggers, linters, language servers, etc) to be correctly detected, on a per-project basis.

Concerns

The release package installs a symlink to the electron binary in the system $PATH, bypassing cli/oni and spawning the electron app directly.

So my main issues are:

1. Regardless of cli/oni being changed to spawn the electron process in the background, it's never used and the editor is always launched in the foreground;
2. Command line options seem to be ignored or don't exist at all (correct if I'm wrong);
3. Workspace detection seems non-intuitive

Proposal

Starting the editor from command line should be treated as a separate concern from the regular app launch. When starting from the command line, it should:

• Dettach to background by default, since it's not a terminal application;
• Provide command line options with help;
• Provide a command line option to keep in the foreground (named foreground for reference), like gvim -f. This makes it possible for oni to be used in command line workflows that requires spawning an editor and waiting for termination (like git mergetool or setting VISUAL=oni -f);
• Provide command line option to open a buffer at a specific location (named goto for reference), similar to vim +line <file>;
• Apply specific workspace detection (see below);

Workspace detection

When detecting workspaces, $PWD should be taken into consideration. Therefore, detection logic could be:

• if no arguments are given: open an empty buffer, detect workspace using $PWD. If it fails, don't use any workspace
• if a directory is given as argument: detect workspace using the given directory. If it succeeds, open empty buffer. If it fails, open netrw's listing in a buffer
• if a file is given as argument: open the file in a buffer, detect workspace for the given file. If it fails, don't use any workspace

Then when respecting workspace configuration:

• "workspace.autoDetectWorkspace": "noworkspace":
  • if previous workspace is available: activate it
  • if no previous workspace is available: use detection logic
• "workspace.autoDetectWorkspace": "always": always use detection logic
• "workspace.autoDetectWorkspace": "never":
  • if previous workspace is available: activate it
  • if no previous workspace is available: do nothing

Implementation proposal

Most of the proposed points are taken from VSCode's code, with the exception that it also ignores $PWD when detecting workspaces.

Investigating more about the code command, the release package installs a symlink to a platform-specific launch script, which then runs the node cli script:

$ file $(which code)
/usr/bin/code: symbolic link to /usr/share/code/bin/code
$ file /usr/share/code/bin/code
/usr/share/code/bin/code: Bourne-Again shell script, ASCII text executable

Tail of the Linux launch script:

ELECTRON="$VSCODE_PATH/code"
CLI="$VSCODE_PATH/resources/app/out/cli.js"
ELECTRON_RUN_AS_NODE=1 "$ELECTRON" "$CLI" "$@"
exit $?

vscode's platform-specific launch scripts: linux, win32, darwin

vscode's CLI script: https://github.com/Microsoft/vscode/blob/8c37fa806d3044f5a3eeb2edea276c6aa66e56bc/src/vs/code/node/cli.ts

So steps for accomplishing the proposals would be (correct me if I missed something):

• Create platform-specific launch scripts that runs cli/oni using the electron binary
• Change packaging to install a symlink to the launch script
• Change cli/oni to:
  • extract CLI-specific options from argv (from proposal: foreground)
  • add a command line option to the main process that indicates it was started from the command line or manipulate the environment (named is_cli for reference)
  • be aware of both invocations (node or electron), which is mostly re-spawning its own process (the platform-specific launch script already decided in cases of release-installed invocations and is node itself in case of development invocations)
  • pass the rest of argv to the child process
  • wait for child process to exit if the foreground option was given
• Change the main/browser processes to:
  • parse command line options (from proposal: goto, is_cli if a command line)
  • change file opening to check for goto
  • change workspace detection to check is_cli and apply proposed detection logic if it's enabled

Additional Proposals

These are additional proposals for command line usage, which I think would require new features:

• Provide instance management command line options (new instance, reuse existing instance)
• Provide a diff mode command line option

[CrossR]

I've just merged in the start of this now, which is platform specific scripts to launch Oni, with an updated launch script to detach Oni from the shell.

Things to do:

• Add foreground flag.
• Add startup commands (goto)
• Add way to pass flags directly to neovim
• Workspace detection logic changes.
• Instance management options (Passing to an existing instance).
• Diff mode option.

I think I'm going to focus on the workspace detection stuff first, as its the part that most users will interact with.