The sound distributed version control system

#96 Put help about each subcommand

Closed on November 19, 2020
arijid79 on November 18, 2020

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

arijid79 added a change on November 18, 2020
This change could not be retrieved at the moment
G4ROOMN2ST7MBHZKD3OXR7KJPMROVP2T2RQ3UTPACTD66FQXIY7AC
arijid79 added a change on November 18, 2020
This change could not be retrieved at the moment
KV66KF6K34PNCWOR7E74DDY32QP4M27BW3X4SCCB2LSDICTV657QC
cole-h on November 18, 2020

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

loewenheim on November 18, 2020

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?

cole-h on November 18, 2020

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

loewenheim added a change on November 18, 2020
SXEYMYF7P4RZMZ46WPL4IZUTSQ2ATBWYZX7QNVMS3SGOYXYOHAGQC
main
loewenheim added a change on November 18, 2020
Validate change before reset by pmeunier, created on November 16, 2020
M3VTIZCPE7CMJXRENE7J3DYEXA4KILMNYLPMPCDRCWXTJ34JKSCQC
main
loewenheim added a change on November 18, 2020
flake.nix: use crate2nix by jwaksbaum, cole-h, created on November 16, 2020
G734WNM64AR5BLAZMN5MDPKSFTYXTUQR6MAGB32NRBC5FXFRWSJAC
main
loewenheim added a change on November 18, 2020
IMCZFTIJ245E3JBOHAY3FMEZCGTL4VNIF26WAKJSZMQXZJ4NK3LAC
main
loewenheim added a change on November 18, 2020
rustfmt.toml: init by cole-h, created on November 16, 2020
HYRH4E55TIRBB3RFFR432METJPNVBSPL6DJVHXE5XGFGZAGBACDAC
main
loewenheim added a change on November 18, 2020
push/pull: fixed "changes" arguments created on November 16, 2020
5HF7C67M4DZMYTCIG32XEQQ662AHQMIHTHUK7TAVSO52XLMFBZPAC
main
loewenheim added a change on November 18, 2020
This change could not be retrieved at the moment
KQJN63AIKMPAIAV5ROB6ODX6FRSHFCP2AM56QLG3ZPRXFDC45OZAC
loewenheim added a change on November 18, 2020
UZZQ3VIA4YVL7C6P22LBPWWPB4BKH6VQLYKVHGQ3XRFISKM52TRQC
main
loewenheim added a change on November 18, 2020
OAXTXEAFX6YLO2XX6L4VMCVW4YZSIXWL6QOZKQCDSL7M44QNX66AC
main
loewenheim added a change on November 18, 2020
AN7IDX26RK33ZXASXLJMD4GTFWHCTHMJ6Y5C4ROCPIH33VUT2EYQC
main
loewenheim added a change on November 18, 2020
This change could not be retrieved at the moment
HZPYFG5RCT3SHO7R5MM37IID7X7Q2NXFWLOISKDZGMPSJD6Y74QAC
loewenheim added a change on November 18, 2020
Version updates by pmeunier, created on November 17, 2020
3S4DR77ZU3XFGGDE6XSCUK6TN76IXNOQIKQSLDBM7KUHNILWHS3QC
main
loewenheim added a change on November 18, 2020
2GNO2PLCZ3BM5RRRSPLGVWEWHOOTVT4VKFBNNQMUKOKF3VXL3ZFQC
main
loewenheim added a change on November 18, 2020
ZWPPIJXFKEL3RP2MEYGB3BPTE73GYRW6FSRZDQKFBJFOK4JBNQ4AC
main
loewenheim added a change on November 18, 2020
flake.nix: remove unnecessary build inputs by cole-h, created on November 16, 2020
VN6L65VRWLKTIXY7XD7OOZBMNKNSIEJG6PJUX5NKKYVYGVG4DFTAC
main
loewenheim added a change on November 18, 2020
Format, versions, README by pmeunier, created on November 17, 2020
BAUL3WR2ACY2HCJIM7K6HJOJ3UXDJISGLMDCSPH3WMPGJPL5AR4QC
main
loewenheim added a change on November 18, 2020
CVAT6LN3SYYLREM6NLM4IUPFI5EX3BL6MRPFTY24ROJFSB3J5OOQC
main
loewenheim added a change on November 18, 2020
76PCXGML77EZWTRI5E6KHLVRAFTJ2AB5YRN5EKOYNAPKTWY2KCGAC
main
loewenheim added a change on November 18, 2020
Channels in the README by pmeunier, created on November 17, 2020
2KURKIFC6P62HW2TCV3N7IMCAARI7UBHYR5M3RIGWYLZU3X763AQC
main
loewenheim added a change on November 18, 2020
GUNVHCG3GTVBGGODDAHVZ5W552BS2IQEOKMAFGFNRTCZR6EPYWJAC
main
loewenheim added a change on November 18, 2020
flake.nix: add rust-src to devShell created on November 17, 2020
IXGIROWKSRQM2E5Q7OVB7ZHGY5I5NSHI2WOOPLEHRKACNE3QH2JAC
main
loewenheim added a change on November 18, 2020
This change could not be retrieved at the moment
T3FHN6EYB34LW7UV53G6XXVOVEC4336QGQFQ6OXS4DZPQMXL4B3AC
loewenheim added a change on November 18, 2020
IXWN5CYPMGNBRYKS2MMRV6DVAUQFSYUB2MXZLEMPF6RSEG5AFA6QC
main
loewenheim on November 18, 2020

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?

cole-h on November 18, 2020

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 [email protected]:pijul/pijul --to-channel :96, it will show me every single change from that branch (since branch != main). However, if I run pijul push [email protected]: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".

arijid79 on November 18, 2020

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

cole-h on November 18, 2020

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).

arijid79 on November 18, 2020

Thank you very much

arijid79 added a change on November 18, 2020
JWTT77WJIGJOZVLLZBADUDZIMSEAR7ZLYLWISOXFJJCNWJGJPWQQC
main
pmeunier on November 19, 2020

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.

pmeunier closed this discussion on November 19, 2020
cole-h on November 19, 2020

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

pmeunier on November 22, 2020

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.

cole-h on November 22, 2020

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=";
}
pmeunier on November 23, 2020

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.

cole-h on November 23, 2020

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.

pmeunier on November 23, 2020

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