feat(but): add but open command

[slarse]

🧢 Changes

Adds a POC for a but open command that allows you to open an uncommitted file with your configured text editor using the but IDs.

☕️ Reasoning

The primary use case is to run but status, se bunch of edited files, and then run but open <id> where <id> was emitted by status. I often find myself copy/pasting file paths to modified files and this kind of feature would obviate that need.

Example:

$ but status
╭┄zz [unstaged changes]
┊    nm M crates/but/src/args/metrics.rs
┊   uts M crates/but/src/args/mod.rs
┊    pq M crates/but/src/command/legacy/mod.rs
┊    pk A crates/but/src/command/legacy/open.rs
<snip>
$ but open pk
<opens up crates/but/src/command/legacy/open.rs in the configured editor>

📌 Todos

This could be incorporated into the (currently hidden) edit command, but the primary use case of edit is to create new files, which is somewhat antithetical to what but open wants to do.

Also, the built-in editor should be launched if there's no configured editor command. Some tests would probably be nice, too.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
gitbutler-web	Ignored	Preview	Mar 10, 2026 8:57am

[krlvi]

thank you @slarse for this command name 🙇‍♂️

[slarse]

thank you @slarse for this command name 🙇‍♂️

@krlvi It's very descriptive, I know.

I was also thinking it could be useful to have a but expand <id> to be able to expand a short ID to its fully qualified "thing" (relative to the repository, of course). In this case it would be a repository root-relative file path.

[Byron]

Since path_safe_intent is so special, could it be explained in the doc string? Also, I am trying to establish a pattern where every parameter is named in the doc-string, so The editor command would probably be ``editor_cmd is….

[slarse]

I haven't thoroughly gone through the code yet so docs are not entirely accurate.

But this highlights something important that I've been thinking about: the path passed in here is not safe. It's an arbitrary path from the repository. It could be a file called $(rm dad-jokes.md) for example. Very much not a safe path, the intent is entirely unknown, and I've been trying to inject badness here but without success.

From what I can tell in gix, any single added .arg() is passed separately to to exec, so it seems fine?

I'll address the docs before trying to get this merged, just want a sanity check on using a potentially unsafe path as input here.

[Byron]

Maybe this tells us that we'd want to have a path which proves that a path is inside the worktree (and probably not inside .git).

Git actually has the notion of a prefix, which is the subdirectory the user's CWD is in compared to the worktree. It is used to normalise input paths to be worktree-relative, and to denormalise (?) output paths to once again be relative to the prefix, i.e. the user's CWD.

Also, to be clear about the "let's have the best-possible docs" directive: this is based on thinking that the non-command parts of the but CLI are like its own little SDK, so it should be very re-usable and thus well documented. Much like the but-api or the plumbing crates, which should all excel in helping to use it correctly with docs (and types). Or said differently: docs capture the expert knowledge that isn't obvious when looking at the code, and that will soon be gone once the human moved on.

[slarse]

Maybe this tells us that we'd want to have a path which proves that a path is inside the worktree (and probably not inside .git).

Perhaps, or perhaps we want a path that is provably accessible to GitButler given the context of the current repository. Excluding the changes I've made here, none of the paths we open in this module are actually relative to the worktree, they're all temporary files (that would usually end up in /tmp, but it's fundamentally up to the OS). So that doesn't work if we don't change that mechanism. I believe Git always opens its temporary files in the .git/ directory (e.g. .git/COMMIT_EDITMSG), and doesn't make use of temporary files the way we do. But maybe we should do the same there and create temporary files in .git/gitbutler. At least macOS and Linux allow us to specify the directory

I'm really aching for the kind of functionality that but open would provide, and it can be further expanded with all kinds of interesting stuff, but we need to think through the security implications carefully. I think I'll finish up the basic implementation and then we'll take it from there, I'm sure we can make it secure and useful all in one big lovely package.

Also, to be clear about the "let's have the best-possible docs" directive: this is based on thinking that the non-command parts of the but CLI are like its own little SDK, so it should be very re-usable and thus well documented. Much like the but-api or the plumbing crates, which should all excel in helping to use it correctly with docs (and types). Or said differently: docs capture the expert knowledge that isn't obvious when looking at the code, and that will soon be gone once the human moved on.

I'm not opposed to any of that. I would probably delimit that effort to public functions, however. High-quality docs are harder to maintain than code as they cannot be automatically checked (although LLMs do help a bit, but it's far from bullet proof).

[Byron]

Thanks!

While type-safety around this is nothing I'd even suggest to tackle here, it's something I always eyed but never accomplished. Maybe one day.

Regarding docs, while this one isn't public, it still triggered this conversation about that path parameter, which is clear sign that expanding the docs to contain this expert knowledge should be worthwhile.