I would like to write some documentation for the various subcommands and thought I’d start with pijul change. I don’t understand what the channel argument is for. At first I thought maybe it was necessary to show a change that wasn’t on the current channel, but a quick test proved that that wasn’t it. I also can’t figure it out from the code.

Excellent question! Suppose you have a change c to some file f, that gets pulled into a channel where f has been renamed into g. How should you display file paths in c? Should they be marked as relating to f or to g?

Interesting, thank you. Can I display a change relative to any existing channel, even if the channel doesn’t contain the change? Would it then show the change as it would appear on that channel?

EDIT: Actually, can you give a small concrete example of the situation you’re describing? I can’t manufacture something like it, mainly because I can’t see how to record a file rename as a change.

You can, but if the channel doesn’t have the files, it would panic (oops). The following steps should do it:

pijul init
echo a > a
pijul rec a -a -m "a" # At this point your get a hash named, let's say h
pijul fork niam
pijul mv a b
pijul rec -a -m "mv a b"
pijul change --channel niam h

Ah, there we run into the problem that I don’t know what fork does 😅 I’ll experiment and then probably write down my understanding of the argument in the documentation.

Maybe I’m misunderstanding something, but change <HASH> and change <HASH --channel niam show the exact same output? Is this intended?

❯ pijul init

❯ echo a > a

❯ pijul rec a -am "a"
Adding "a"
Hash: C62JVKIPSWJARWVBEYGOLCXIOVZOTKQYMFNQF7JMWCHEVDWLK6DAC

❯ pijul fork niam

❯ pijul mv a b

❯ pijul rec -am "mv a b"
Hash: IHDWOSSWRZK5IUZNCWKU4H4OAHM6TGXQBET36PS56MRRA755IZ7QC

❯ pijul change C62J --channel niam
message = 'a'
timestamp = '2020-11-17T17:00:38.974594333Z'

[[authors]]
name = 'loewenheim'
full_name = 'Sebastian Zivota'
email = 'loewenheim@mailbox.org'

# Changes

1. File addition: "a" in "/" 644
  up 1.0, new 0:3
+ a

❯ pijul change C62J
message = 'a'
timestamp = '2020-11-17T17:00:38.974594333Z'

[[authors]]
name = 'loewenheim'
full_name = 'Sebastian Zivota'
email = 'loewenheim@mailbox.org'

# Changes

1. File addition: "a" in "/" 644
  up 1.0, new 0:3
+ a

Ok, I understand this now. The change format is actually a little bit subtle, in that:

• the same change must have the same effects, once applied. If the change adds a file, and the file is renamed, we must not print the change with the new name, as this would be a change with a different effect from the original one.

• there is an even stronger constraint, which is that change hashes must be the same 100% of the time. Since changes are parsed from the text format at record time, this is the case in Pijul now, by design. Moreover, pijul record -a doesn’t parse its change, but there are tests for this in `libpijul.

One subtle point here, is that local file names are part of the hash, and so must not change when the change is parsed back to binary and applied. All in all, I’m removing the option, because I can’t see how to make it non-confusing.

Btw, while you’re active on documentation, one major issue is to keep the deployed documentation in sync with the current release. This has always been a problem for us, and outdated documentation is often worse and more frustrating to the users than no documentation at all. The way I’m doing this now, is by writing all the documentation as clap comments, and parsing it to generate the manual whenever I deploy the documentation.