pijul_org / pijul

#27 naming / URI scheme

Opened by FlorentBecker, on March 31, 2017
FlorentBecker commented on March 31, 2017

pijul manipulates the following objets:

  • repositories
  • branches in said repositories
  • "commits" / "revisions" (ie, the state you get by applying a given set of patches / the set of patches itself)
  • patches

We need a coherent terminology around them (ie, we should bikeshed revision vs commit; I prefer revision).

We also need a way to address each of these, and make sure commands treat them in a coherent way. Being inconsistent about that between commands is a sure way to get a fun UI.

So, the easy ones:

  • repositories are addressed by URL / path. They can be aliased by adding a line to .pijul/aliases . An upstream (or just up, maybe) alias is defined on clone. Some commands may default to this alias.
  • a branch is addressed by repository:branch. Aliases can be defined, we need a way to refer to the current branch, +, ! or = can work if we want it to be a single character. Maybe the meaning of some aliases or the default branch for some commands can depend on the current branch (this is what git does with remote-tracking-branch).

The not-so-easy:

  • revisions need canonical identifiers, certainly hash-like. There also needs to be a way to refer to "the current revision of such and such branch". repo:branch:hash should work, as well as repo::hash for "get that revision with known hash". repo:branch: is the current revision of that branch. repo:branch:~X or repo:branch:-X is X revisions in the past of that branch, and repo:branch:@time is the state of that branch at that time.
  • ditto for patches (not sure what shortcuts are needed, probably something like %revision for the last patch in a revision),
  • sets of patches probably don't have a good way to name them except maybe as revisionA--revisionB for the difference between revisions A and B.
FlorentBecker commented on March 31, 2017

The '%' and '--' operators should distribute over ':' (ie, it should be possible to do 'repo:branch:@yesterday--~0' for all patches since in that branch since yesterday)

FlorentBecker commented on March 31, 2017

For revisions, ther could probably also be a pseudo-revision for the current unrecorded state of the repository, but it's not clear if it would make sense with all / most commands.

pmeunier commented on April 1, 2017

Since patches commute, revisions are going to be confusing for many users, because even if Alice and Bob keep track of all revisions, they will almost certainly have revisions unknown to the other.

How about using tags for revisions? We could imagine an a-posteriori tagging command, which allows the user to communicate a specific revision to their coauthors.

FlorentBecker commented on April 1, 2017

In other words, revisions are just sets of patches, but tags are good to have too.