Notes on the Pijul Manual

• pijul.org/manual really should be up-to-date. I remember it being grossly out-of-date just days ago, but it seems to be up-to-date now.

  ...Now it seems old again. Guess: I confused myself several times by looking at both the online version and a locally rendered one.

• Weak proposal: (at most a) single sentence per line? Not sure how beneficial this would be, given Pijul. See pijul/manual#57: there seems to be at least a little demand for shorter lines in the source.

• It would be nice if command sequence examples in the manual could be automatically tested.

• note to self: go over cellarroot/b/discussions/2 again

• note to self: read through the pijul/manual Discussions

• Might be nice to have pijul/pijul be tagged regularly, and to have the manual display which version (i.e. tag) it applies to.

• Huh, no links to jneem.github.io anywhere. That blog series was good! See Parts 1–5 at jneem.github.io/archive

• Not all source material ends up rendered 😱 Example: format.md ...Oh, it's commented out in SUMMARY.md.

• pijul.org/manual should not be available, or redirect to pijul.org/manual/ (with terminal /)

• What are those .md.NT22VBIWNZHOC files in the Manual repo?

• Missing sections:

  • contents of a change (high level)
  • internal structure of a change (lower level)
  • contents of a repo (high level)
  • internal structure of a repo (lower level)
  • string representation of conflicts

By section

Why Pijul?

Present text is not compelling for either

• people new to VCS
• git users

Perhaps separate chapters/texts is the way to go.

-/stitched together based on their contents rather than on the edits that took place/
+_stitched together based on their contents rather than on the edits that took place_

Installing

Needs shortening.

Include Windows build instructions.

Getting started

Move up paragraph on identities.

pijul key generate doesn't exist anymore.

We need an actual tutorial that includes not only recording, but also other operations. Note to self: peruse Zulip & Discourse for prior art. (see "phenomenology" on Discourse)

First-Time Setup: check that this section is up-to-date/necessary.

Clarify the roles of author.*. Authors seem invisible by default. Huh?

"Definitions" needs fleshing out. Give overview of a repo's structure. Indicate where config & working copy & changes & tree & pristine &c. live.

"...which can happen even by email exclusively" -- really? Show this functionality.

Provide link to the Nest. Perhaps note that is has the same purpose as GitHub for git.

Working with others

SSH: check whether prior authentication/proof is required.

Missing:

• how to add a remote

Pijul identities

Aspiration: I know next to nothing about SSH. This chapter should be understandable to me, and also to the even less knowledgeable. ( perhaps more applicable to: chapter on the Nest )

When/how are name & e-mail displayed? ( Confusion borne from below mentioned UI bug. Might still merit elaboration though. )

How to share the id--name mapping? ( suspected answer: prove )

How to prevent pushing patches made using the wrong identity? ( related: how to recover from pushing wrong identity? )

On success, the location of the generated identity will be displayed to the user (...).

👆 It isn't.

What does Linking identity `default` with @ mean?

Pijul UI bug: pijul identity new suggests a display name, but does not allow using it. On Windows, at least.

Why would I want to encrypt/expire my identities?

What does linking to a remote mean?

Document pijul id abbreviation of pijul identity. Also document other abbreviations, if any.

Patches submitted before proving your identity will show only the key as the author, for example 44hhwRgXtFEeAt6m3KooFCQ5VowqLoQ8YkBP93UZqm9R.

👆 Don't you mean that before proving only keys are displayed, but after proving also/instead the name is displayed? I'd be surprised by a distinction between pre-proof and post-proof patches.

What exactly is a Pijul identity? I have a vague memory of a public/private key pair. How is impersonation avoided?

Configuration

~~What does 'global' vs. otherwise mean? Describe.~~ (probably mostly for non-programmers)

What is the function of author.name &c? Is name actually the local name of the default (to be) identity? What are full_name and email doing here? key_path: flesh out a bit more as well.

Table: Link to Choice is fine, but the destination of Author does not explain what the available options for the author field are. Should it be an identity key, or a display name, or..? Same for Template. Kinds is not entirely explicit either, but deducible/guessable.

...Actually, the example right below the table explains a lot. Maybe order could or should be tweaked? Not sure.

Obvious though TOML might be, it may well be new to many people.

Link to keys.html is broken. It'd be nice have all links be automatically checked every once in a while.

What would be some example uses of templates?

Huh, config.toml in the one place, bare config in the other.

-have a higher precedence than
+take precedence over
 (or some such)

-If
+Whether

Remotes: could use some elaboration. Also: the linked reference/remote.html is empty. ...It isn't empty anymore 😕

Hooks: could use elaboration. What are some example uses? What are possibilities, what are the limits?

"standard glob syntax": we should explain it anyway, or point to a specification.

Conflicts

-occurs
+occur

-which comes first
+which should come first

This text speaks of adding/removing 'lines', but Pijul works on bytes, no? If the talk of lines is meant as a 'simplification' for humans, we should say so or try to avoid it, lest we encourage misunderstanding.

Note to self: check that the listed possibilities are truly exhaustive (as suggested by the text).

Could use a worked example of dealing with conflicts. how to read conflict markers how to fix conflicts

unrecord vs. unapply. Why does the latter not seem to exist?

We need a good conceptual overview of Pijul somewhere. For a start, see jneem.github.io

Theory

The LaTeX doesn't render.

The SVGs do not contrast with the light themes.

This text's style might be too mathematical for many readers.

I'll skip going over it in detail for now.

Diff algorithm

~~Drop this chapter, or relegate it to an appendix.~~ This might be useful to understand, actually. Try for example

pijul init reprorepo ; cd reprorepo
echo -e ".\n.\n.\n" > file
pijul add file
pijul record --all --message "base"
pijul fork a ; pijul fork b
pijul channel switch a
echo -e "a\n.\n.\n" > file ; pijul record --all --message "a"
pijul channel switch b
echo -e ".\nb\n.\n" > file ; pijul record --all --message "b"
pijul channel switch main
pijul pull . --all --from-channel a
pijul pull . --all --from-channel b
cat file
# expected:  ab.  (or a conflict)
# actual:    a.b.

👆 the final line is important: including it leads to the unexpected behavior, excluding it produces a conflict.

The Nest

Add note about .com vs. .org.

Creating an account

out of date:

• .org vs .com
• via GitHub/Google/Twitter no longer possible

Uploading public keys

I do not know how SSH works, in general, and this section does not enlighten me. Let's add a very quick getting-started guide.

Note to self: reexamine this section again in the future.

link to keys.html is broken.

Creating repositories

(no need to clone it, patches can be pushed directly)

Indeed, currently cloning right after creating results in 404. See this Zulip thread.

Contributing to a project

How to remove patches from a discussion?

To push to a discussion is just to push to a channel. Point this out.

Workflows

I expect a well-developed Workflows chapter to be important for Pijul adoption.

Zulip has already produced a number of how do I do X scenarios. Use these for inspiration for more sections. TODO: take stock

Also on Discourse: Phenomenological Pijul (or Pijul from the outside). TODO: study the above, and also browse some more

We're missing the most basic scenarios. (How to: record, amend, push, ...) They might not seem terribly interesting, but I still think it's good to have them around. ( There will be overlap with the tutorial, but that's fine. )

Other missing scenarios:

• the one(s) that the initial, "semi-empty", root-introducing patch is meant to help with. Submodules.

Working with channels

My understanding: Channels and branches are wholly different things. 'The' difference is not at all subtle. It's just that these two different tools can be used to solve some of the same problems.

Question: why channels and not simply separate repos? Suspected answer: for efficiency only.

"Formally" -- does the non-mathematician know how to interpret this?

A channel is not just any set of changes, right? It'll always contain all transitive dependencies, no?

[...] (a bit like branches in Git).

[...]

However, channels are different from Git branches, and do not serve the same purpose.

Like branches, but unlike branches. In what ways? (And implicitly: why mention it?)

In Pijul, independent changes commute, which means that in many cases where branches are used in Git, there is no need to create a channel in Pijul.

As evidenced by the many questions about branches and channels, there is a need for more clarity on this point. We should probably not (only) tell, but also show.

The identity of a change doesn’t depend on the branch it is on, [...]

What does 'branch' mean here? Shouldn't it be 'channel'?

[...] or in other words, rebase and merge are the same operation in Pijul.

I fear this only makes sense if you understood already.

This implies that conflicts do not mysteriously come back after you solve them (which is what git rerere is for).

This sentence feels out of place. If it shouldn't feel out of place, then consider showing in addition to telling. Many seem unfamiliar with this problem, or to feel it isn't a big deal. Few know about rerere.

Also, conflicts are between changes, [...]

This, too, seems like it only makes sense if you understood already. Evidence: persistent confusion on Zulip, and probably also Discourse and elsewhere.

Should the comparison with Git be moved to a separate chapter? I feel it distracts a bit. By the way: see jvns.ca/#git for inspiration -- perspectives on 'branches' in particular. Also: What helps people get comfortable on the command line? And while we're at it: Patterns in confusing explanations

What you can do with channels

I expected a tutorial or demonstrations, but what follows is more of a reference. We need tutorials as well. Scenarios, problem statements + solutions.

-\$
+$
 (in many places)

Recording, splitting and combining changes

Reminder: there should be a thorough discussion of log order somewhere in the manual.

Reminder: somewhere in the manual, lay out exactly which info ends up in the patch.

-[[author]]
+[[authors]]

What is the role of [[authors]]? What happens to these entries? What if they are inconsistent, or contain typos?

How to add dependencies?

How to edit the implicitly 'staged' diff? Only deleting portions of it might not be enough.

pijul reset is automatically hyphenated but probably shouldn't be. ( Not unique to this string; I just noticed it here. )

Whatever you remove, the files themselves will still look the same as before the amend, only the record will have changed.

Explicitly note what happens to the hunks that you remove. Also: what happens to the old change? Will it continue existing, or disappear?

[...], but not the content of the change itself.

It has not yet been noted explicitly that this is what reset (I expect) is for.

Reference

It might be useful to show which pijul version/build this material was generated from.

~~generate-reference seems broken.~~ It's just lacking a manual. Haven't figured it out yet. Don't know bash... ...Alright, it is outdated: SUBCOMMANDS: has become Commands:. Other breakage: (SUMMARY.md)

-    - [pijul ls](./reference/ls.md)
-    - [pijul mv](./reference/mv.md)
+    - [pijul list](./reference/list.md)
+    - [pijul move](./reference/move.md)

Pages not listed in SUMMARY.md: completion identity tag client dependents. 't Would be nice if mismatch between SUMMARY.md and src/reference were automatically detected.