When someone runs pijul --help, he/she only gets the list of subcommands and no help. I have put some about statements to all subcommands to add some help

Would you please squash your two changes together? I don’t think there needs to be a separate “format” change :) Thanks!

Nice work! I have some suggestions, though:

1. change is not for changing the channel, it’s to show the details of a change.
2. I think all help strings should follow the same style, cf. “Add a file to the tree” vs. “Manages different channels”. help uses the latter style, so we could conform to that; alternatively, the help message can be customized.
3. The same effect as

    #[clap(name = "init", about = "Initialize an empty pijul repository")]
    Init(Init),

can also be achieved by

    /// Initialize an empty pijul repository
    #[clap(name = "init")]
    Init(Init),

Which do you prefer?

re your third point: I much prefer using doc comments with structopt. Looks a lot cleaner, IMO.

Sorry about that, I actually only wanted to push one change. Why is it that pijul thinks I need to push the initial change of the repository as a dependency; surely the channel already has it?

This happens when you’re on a different channel than the channel you’re pushing to. If I make a dummy change while on another branch, branch, and run pijul push cole-h@nest.pijul.com:pijul/pijul --to-channel :96, it will show me every single change from that branch (since branch != main). However, if I run pijul push cole-h@nest.pijul.com:pijul/pijul --to-channel main:96, this doesn’t happen.

The only reason I know about this is because I was debugging something related to pushing earlier and noticed that there’s a regex with two captures (CHANNEL, in pushpull.rs): ([^:]*) and (:(.*)) – with :96, it would capture "" and "96", but with main:96, it would capture "main" and "96".

Ok. I prefer the doc comment version. I will make a change to that. Also I am gonna make sure to change the change subcommand help. But how to squash the changes. Any help is greatly appreciated

To squash the changes you basically just unrec the “Format the code” change (KV66KF6K34PNCWOR7E74DDY32QP4M27BW3X4SCCB2LSDICTV657QC) – this will remove the change from your history, but keep the actual change’s contents – and then pijul rec --amend the “Add help on subcommands” change (G4ROOMN2ST7MBHZKD3OXR7KJPMROVP2T2RQ3UTPACTD66FQXIY7AC).

Thank you very much

This is so cool, thanks! One more step towards good documentation. I promise I’ll add many more steps when there are no more fires to put out.

Also, for the future (in case you didn’t know) – to display a more in-depth description when calling pijul help [subcmd], you just need to add a blank doc comment line after the short description, and then start the long description on the next line. https://docs.rs/structopt/0.3.20/structopt/#long_help-and—help

I just updated the “reference” section in the manual to be automatically generated from this. Not everything is automated yet, since the manual still depends on the “mdbook-katex” crate, and I didn’t have the time to make a nix expression for it yet.

Here’s a Nix expression you can use for mdbook-katex (used in conjunction with callPackage):

{ rustPlatform
, fetchCrate
}:

rustPlatform.buildRustPackage rec {
  pname = "mdbook-katex";
  version = "0.2.4";

  src = fetchCrate {
    inherit pname version;
    sha256 = "sha256-7cvFYNpYGyE4QQzCq67Kiv3rajOCiihjb9g+H4jJMM8=";
  };

  cargoSha256 = "sha256-3YaPvyhrQrjfWkazEa/v2KsaBAUKt2urNeXq2L+pOI0=";
}

Thanks @cole-h. Another difficulty I had was to recompile Pijul from its flake, from my deployment code. It’s done now, and the documentation is now updated at each redeployment.

What kind of trouble did you have with recompiling Pijul from its flake? If you had an issue, there’s a non-zero chance other people might have some, and I’d love to help fix / avoid that.

No serious trouble, but my deployment scripts are non-trivial (I wrote my own NixOps).