The sound distributed version control system

#661 confusing channel section in readme

Opened by joyously on March 29, 2022
joyously on March 29, 2022

I have read the Readme several times and always get confused by the channels section:

The main differences with Git branches are:

The identity of a change doesn’t depend on the branch it is on, or in other words, rebase and merge are the same operation in Pijul.

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

Also, conflicts are between changes, so the resolution of a conflict on one channel solves the same conflict in all other channels.

To me, saying that a channel is a set of changes means that you can have a line that is in two different states by putting it in two different channels. But that is more like a branch in git, because saying that resolving a conflict in one channel solves it in other channels means that the change has only one state. So what is a channel?

I suggest that this section’s wording is changed to more clearly explain the difference with branches. Only the first point actually addresses difference to a branch.

levi on April 28, 2022

I will write how I understand it, although I may be wrong. But I give it a try

The whole misunderstanding with Channels is based on two things.

  1. Name “channel” is confusing
  2. People often try to understand Channels through the prism of the Git and get even more confused, because documentation says (a bit like branches in Git).

Let’s try to deal with the first point. Lets change the name “Channel” to “Group” In the mathematical term this group is called “Set” what is just fancy word for an unordered collection of different “things”. In case of pijul those “things” are “changes”. Maybe you remember from elementary school or even kindergarten. Sets of apples and sets of pears ? I bet you do :)

This may seem trivial and funny. But as children, we attended a 101 set theory course, branch of abstract mathematics that pijul is based on.

But for the rest of this text we will stick to the word “group”.

So “group” is collection of results of pijul record command, new “change” is being added to the group every time you invoke this command. Every Pijul repository has at least one “group”, and that group is called “main”. We can list those “changes” by invoking pijul log. We can invoke pijul log for every group we are working on.

What groups give us ? Well, it gives as that “change” can belong to multiple groups at once. So we have ability to group “changes” into different “groups”. Much like file can belong to different folders at once. Or more file like shortcut, because changes are not being copy but referenced, making them very light and smart. So we can create multiple variations of our repository where every “group” is containing different/same set of “changes” or unique ones that only belongs to particular group.

So our workflow could be as follows. We have three groups and some change represented by hash, lets call it “ABC”

  • main
  • new-features
  • backup-version


pijul apply ABC --channel new-features
pijul apply ABC --channel backup-version

We add “ABC” from “main” group to both “new-features” and “backup-version” Now by switching groups we can make two different versions associated with that “change”. Improving ABC creating new feature, by adding more “changes” to that group, and leave another group as backup or maybe where we do some additional cleanups in repository.

And Indeed this works as folders on steroids. Allowing to maintain multiple versions of the same project by creating different groups of “changes” So we can now do all crazy stuff like show difference between two groups, apply one group to another in future versions of pijul maybe produce new group made up of differences between two, or produce new group where “changes” are unique to both ? Who knows. I think any operation that can be represented on a Vienna diagrams could potentially be performed in pijul in future.

Vienna Diagram

Now second point. Why groups and not “branches” ? Because there are no git like branches in Pijul. In fact there are no need to have one. The only similarity with git branch is that they store information side by side separately. That’s the “bit like branches” part.

Branches form a new tree branch with link from one change to another and another and another. Where end user in git needs to maintain that complex data structure. Decide whether merge branches or delineate new path in that tree, or connect one change to another in other way. But in git that is needed, because changes depends on each other. In pijul every little “Change” is independent you literally slam changes together and and conflicts are handled manually as they are nothing abnormal in workflow. Math will do the rest and take care that everything will be fine. There’s is no need to involve here with git’s complexity. Pijul is very elegant and simple tool.

I know that Channels bring to mind some kind of funnel or queue, something dynamic. I have cought in that mental spinning wheel myself. I assume this has to do with the category theory and functors that map one category to another. Such functors are represented by arrows on the diagrams. Maybe that was where the name came from? pmeunier is a scholar, where he used very specific language. Maybe that was his first idea for the name.

Final word: So called “Channels” are more like sophisticated versions of bags that some complex magical ideas. Flat and boring bags of “Changes”

joyously on April 28, 2022

So “group” is collection of results of pijul record command, new “change” is being added to the group every time you invoke this command.

Well, sort of. I gave a test case for showing that the add command is per channel, even though that command has no channel options. Because of this, the ls command is also per channel.

In pijul every little “Change” is independent you literally slam changes together and and conflicts are handled manually

Not really. It’s very difficult to make an independent change. You have to add a new file usually, to be independent. And files are tracked per channel.