🐢 Yes, but what will T be? Although store structures have Serde implementations, they are not particularly useful for this.

🐇 We can have output types, named like XvcFileListOutput, that will be converted to strings with serialization.

🦊 We do something similar in xvc pipeline export and import commands. We use XvcPipelineSchema and XvcStepSchema just for the import and export commands. We’ll write similar structs for all JSON output and will use Serde to convert these to strings.

🐢 Unlike the import and export commands, we have optional fields in the output, though. I don’t want content digests to appear in JSON output if they are not required.

🐇 Let’s search for optional fields in Serde.

🦊 There is a crate for optional fields.

🐢 We don’t need another crate for this. Serde has the skip_serializing_if attribute for fields. We can add Option::is_none as a method to these to skip outputting None fields. All those fields, in this case, will be optional.

🐇 This is fine. We already use structs to format the xvc file list output. We can just use them to output JSON.

🐇 What about adding at least command completions for Nushell?

🐢 Let’s read a bit about clap_complete_nushell.

🦊 There seems to be a nu-complete command. Let’s check its documentation.

🐇 Nothing was found, and Kagi doesn’t help much either.

🐢 There is a completions document for Nushell: https://www.nushell.sh/book/custom_completions.html

🐇 There is a tool called carapace to provide completions across shells.

🐢 Its documentation is thin, and I’m not sure if it supports dynamic completions out of the box. I believe instead of adding a carapace setup, we can just write a Nushell completion script that will use JSON output from the commands and add some (maybe hidden) utility commands to support it.

🐇 There are a set of example scripts in the Nushell repo: https://github.com/nushell/nu_scripts/tree/main/custom-completions

🐢 The reason I want to write custom completions for Nushell is that it will be an exercise for the scripting language. gh completions are not as scary as a Bash script.

🐇 git completions are a better example for XVC. They simply run git whenever necessary. We can start from a static completions command and update this with dynamic completions manually. It will teach a lot.

🐢 I forked the nu_scripts repo and will add XVC completions script there.

🐇 Then let’s begin by adding Nushell static completions. Shall we add a command for this?

🦊 Reviving the completion command we removed in 0.6.13?

🐢 We shouldn’t list it. We can make a _comp subcommand for the time being and generate and distribute completions in the repository. When clap_complete_nushell has the feature parity to provide dynamic completions, we can remove these commands.

🐇 What will we use this for other than generating completions?

🐢 Maybe dynamic completions can call this as well.

🐇 Added Nushell static completions to be output using xvc _comp generate-nushell. Let’s bump up the version to 0.6.15.

cargo set-version 0.6.15-alpha.1
   Upgrading xvc from 0.6.14 to 0.6.15-alpha.1
...

🐢 I noticed we forgot a line in the CLI command handler that asserts xvc_root_opt.is_some(), and this fails when we run xvc outside of repositories. We need to release this version quickly.

🐇 Oops, now, ok, let’s write a static Nushell generator and just release quickly.

🦊 Generating completions with

xvc comp generate-nushell

🐢 Completion command is run with comp instead of _comp. Should we rename it?

🐇 Renamed it to _comp. It’s not hidden, but at least we can be sure that it won’t be misunderstood as a common command.

🐢 Bumping the version again. Now let’s source the generated script and test it.

cargo set-version 0.6.15-alpha.2
   Upgrading xvc from 0.6.15-alpha.1 to 0.6.15-alpha.2
...

🦊 Yep, it works. We now have completions for Nushell.

🐢 Let’s update the completions documentation.

🐇 Done. Now, let’s take a look at CI and see what fails.

ghrl | first
╭──────────────┬─────────────────────────────────────────────────────────╮
│ conclusion   │ success                                                 │
│ displayTitle │ Add Nushell completions                                 │
│ headBranch   │ nushell-completions                                     │
│ url          │ https://github.com/iesahin/xvc/actions/runs/13070200765 │
╰──────────────┴─────────────────────────────────────────────────────────╯

🐢 It fails because of coverage, not the tests. Codecov says the new code isn’t tested.

🐇 The added xvc _comp command isn’t tested. We can add a test running those lines and testing if the command outputs a completion script.

🐢 We have a test for completions. We can add a test that runs the lines.

🐇 Added a test and bumping up the version.

cargo set-version 0.6.15-alpha.3
   Upgrading xvc from 0.6.15-alpha.2 to 0.6.15-alpha.3
...

🦊 We can add some more coverage while waiting for the tests.

🐇 XvcOutputLine implementation seems to have no tests. It’s weird because we use these everywhere.

🐢 I’m not sure we use this particular implementation; we just use XvcOutputLine::Info(s), not XvcOutputLine::info(s) anywhere. We can delete these methods actually.

🐇 We’ll add JSON output via this particular struct. Can we refactor these to use formatting for JSON, for example? Or use these to output JSON?

🦊 We can add a formatter to XvcOutputLine to output structures.

🐢 The enum is now defined as:

#[derive(Clone, Debug)]
pub enum XvcOutputLine {
    /// The output that we should be reporting to user
    Output(String),
    /// For informational messages
    Info(String),
    /// For debug output to show the internals of Xvc
    Debug(String),
    /// Warnings that are against some usual workflows
    Warn(String),
    /// Errors that interrupts a workflow but may be recoverable
    Error(String),
    /// Panics that interrupts the workflow and ends the program
    /// Note that this doesn't call panic! automatically
    Panic(String),
    /// Progress bar ticks.
    /// Self::Info is also used for Tick(1)
    Tick(usize),
}

Here, these fields can also have a formatter that will render the string in a particular format. For example, the output can be

XvcOutputLine::Output(XvcJsonFormatter, String)

🐇 I’m not sure this is a good idea. Output already specifies this string as output. We can have a wrapper instead, like,

struct XvcJsonOutput(Format<XvcStructuredOutput>, XvcStructuredOutput)

and we can use the supplied format to render XvcStructuredOutput to an output line with XvcOutputLine::Output. If we don’t provide output as structured, it will be too much error-prone work to convert the current outputs to structured.

🦊 The transition will also be gradual. We may not need structured output for most of the commands. We can start with xvc file list and convert others as we go.

🐢 This is sensible. By the way, coverage still didn’t increase. There may be something going on with Codecov or running the test.

ghrl | first
╭──────────────┬─────────────────────────────────────────────────────────╮
│ conclusion   │ success                                                 │
│ displayTitle │ Add Nushell completions                                 │
│ headBranch   │ nushell-completions                                     │
│ url          │ https://github.com/iesahin/xvc/actions/runs/13087431038 │
╰──────────────┴─────────────────────────────────────────────────────────╯

🐇 Let’s run the test:

cargo test -p xvc --test test_completions
...
test test_completions ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.80s

🐢 Can we make sure the output is a Nushell script and not an error message?

🐇 Let’s print it out.

🐢 It looks like when the COMPLETE environment variable is set, it never calls _comp subcommand and never calls those lines.

cargo set-version 0.6.15-alpha.4
   Upgrading xvc from 0.6.15-alpha.3 to 0.6.15-alpha.4
...

🐢 Let’s make a release for 0.6.15. Coverage is OK now.

cargo set-version 0.6.15
   Upgrading xvc from 0.6.15-alpha.4 to 0.6.15
...

gh pr merge --squash --body $"(open CHANGELOG.md | lines | skip 2 | take 5)" --subject "Add static nushell completions"

🐇 Merged the PR.

🐢 Releases should appear in a few minutes.

🐇 We need to tag the merge commit for this.

🐢 Oh, yep. AFAIK Lazygit doesn’t have something for git push --tags. Let’s push from the CLI.

git push --tags
You are on the main branch. Skipping CHANGELOG.md check.
To github.com:iesahin/xvc
 * [new tag]         v0.6.15 -> v0.6.15

🦊 These commands, especially tables, are not rendered correctly on the web. We need to change the theme, I think.