Documentation needs a few guides

Documentation
1

There is a “getting started” and “reference”, but what would really help learning how to use pijul, would be a set of guides for example:

  1. Fork and merge: how to fork your repository into multiple channels for parallel development and eventually merge them back together
  2. Rewriting history: fix a typo in an old change
  3. Cherry-picking: a different channel has one specific change that is also needed at my channel

These are things that I do with git each day, but reading the docs and a few posts on discourse, I just cannot figure them out.

2

Hi! Welcome here. I believe these topics are covered in the manual, but feel free to submit patches to the manual if that wasn’t clear enough.

  • Fork/merge + cherry-picking: merge, cherry-pick, record and pull are actually the same command. Pijul uses just patches. Patches and nothing else. If you want to take one patch from a channel, just apply it, and you’re done. You can use pijul pull or pijul apply for that.

  • For forking and merging, we have videos, the manual, blog posts, a chat room and this forum in which we keep repeating that in many cases, forks are overkill and patches do the same job more efficiently and with less cognitive overhead. But if you insist, pijul fork and pijul pull can be used to fork and exchanges patches between channels, local or remote.

Also, if you’re trying to use Pijul as a “friendlier Git”, this is unlikely to give you much benefit. Pijul is indeed meant to be much easier to use, but this is not due to our choices in CLI design and argument naming, it is actually thanks to a principled approach and a change in perspective on collaborative work (patches instead of snapshots).

3

Oh, Pijul really simplifies the model and the commands needed to manipulate it!

I guess I was hitting a bug then, because I was trying to use pijul pull --from-channel other-work . and pijul apply [the-long-change-hash].

I’ll file it pijul/pijul - Discussions

But in any case, there will be people looking at pijul docs thinking “how do I do git x y z with pijul”. I might open a Pull Request(?) with a new page in the manual when I figure this out.

4

I agree some docs are needed, mostly to explain the limitations of the commands when dependencies are involved.