General discussion
===============[updated on the basis of T1241#42722 below]
The goal of this task is to define the canonical way of describing //paths// in the SWH Merkle DAG.
This is formally a description of how one goes from a given node in the Merkle DAG, that we call an //anchor// to another node following the edges in the DAG, the //endpoint//.
In the general caseWe observe that when the anchor denotes a revision (and most often when it's a release), it's trivial to find in the DAG the root directory of the source code, and we only need the file path to identify the content we are interested in. When it's a snapshot, the path is composed of the following re is a default root directory to point to.
Hence we have concluded that for the vast majority of use cases it is enough to
extend the syntax and semantics of our SWH-IDs with the following optional
elements:
1)- **anchor** : the swh-id of the //anchor//: node in the DAG//: this can be a snapshot, a release, a revision, or a directory
2) the //cpath//: the part of the path that traverses the development history (its nodes are releases/revisions)- **path** : the full path from the root directory of the anchor to the //endpoint// object, that can be a directory or a file content
3) the //fpath//: the part of the path that traverses the directory tree (its nodes are directories)
Since the DAG is immutable, the path representation does not need to store the actual swh-ids of the nodes for 2) and 3): it is enough to encode the choices made when traveling down into the DAG, exactly like what is done in git, see for example https://git-scm.com/book/en/v2/Git-Tools-Revision-Selectio- **visit** : the swh-id of the //snapshot// in whose context the anchor must be shown
If one were to follow git's notation, then the following path:Here is a full example:
anchor=swh:1:snp:170df8c232c8c44f8d08f0ce5f5f806571d93649;cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;
cpath=1; (the first commit of the first branch of the snapshot) anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;
fpath=2.9 ; (the 9th element of the 2nd element from the root)
would end into swh:1:cnt:41ddb23118f92d7218099a5e7a990cf58f1d07fa, that is Luminary099/BURN_BABY_BURN--MASTER_IGNITION_ROUTINE.agc from the Apollo-11 source code as recorded on July 3rd 2018
Encoding the path expressions
=======================
For short paths, the explicit representation above may be sufficient. For longer paths, though (tens or hundreds of edges), we may want to provide shorter notations.
The first step would be to use the same approach as in git's language:
<cpath> := <empty> | <sel> <cpath> path=/Examples/SimpleFarm/simplefarm.ml;
<sel> := "~" [<count>] | "^" <branch_selector> visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9;
<count> := integer origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;
<branch_selector> := integer lines=12-23
As an example, ~3^2~21 is the commit found following the first parent 3 timesWe checked with @anlambert that all the pieces of information needed to generate such optional elements for the swh-ids are already available in the WebApp view, then moving to the second parentso it will be straightforward to provide then following the first parent 21 times final user with this kind of links.
The second step would be to compress such path expressions: in the commit graph,On the receiving end, we also have all the information needed to check that the object and its context match:
most of the time we'll have just 1s and 2s- for the //path// part, and that should eat up only one bit,we just need to follow the path from the anchor and check that the endpoint has the declared swh-id
not 8- for the //visit// part, 16 or 32 (depending on the character encoding).we might (if we want) make a request to the swh graph to check that the anchor node is well in the subgraph rooted at the given snapshot