Difference between revisions of "Repository snapshot objects"

From Software Heritage Wiki
Jump to: navigation, search
(Git implementation)
(Repository snapshot objects)
Line 3: Line 3:
 
A repository '''snapshot object''' is a [https://en.wikipedia.org/wiki/Merkle_tree Merkle] DAG node used to capture the state of a VCS repository.
 
A repository '''snapshot object''' is a [https://en.wikipedia.org/wiki/Merkle_tree Merkle] DAG node used to capture the state of a VCS repository.
  
Conceptually, a snapshot object is a map from branch names to the identifiers of other objects in the repository.<br>
+
Conceptually, a snapshot object is a map from branch names to other objects in the repository.<br>
Practically, the map is serialized as an association list sorted by branch name.
+
Practically, the map is serialized to a '''textual manifest''' as a list of triples ''<object type, object ID, branch name>'', sorted by branch name.
  
 
''Note:'' "branch" is used here in the generic [[Software Heritage]] meaning, which encompasses branches, tags, etc., depending on the VCS.
 
''Note:'' "branch" is used here in the generic [[Software Heritage]] meaning, which encompasses branches, tags, etc., depending on the VCS.
Line 10: Line 10:
 
=== Object ID ===
 
=== Object ID ===
  
Each snapshot object has as its '''snapshot object ID''' the cryptographic has value of a textual serialization of the ''<branch name, object ID>'' association list.
+
Each snapshot object has as its '''object ID''' a cryptographic hash (the same used elsewhere in the Merkle DAG) of its textual manifest.
  
 
== Git implementation ==
 
== Git implementation ==

Revision as of 21:53, 9 August 2016

Repository snapshot objects

A repository snapshot object is a Merkle DAG node used to capture the state of a VCS repository.

Conceptually, a snapshot object is a map from branch names to other objects in the repository.
Practically, the map is serialized to a textual manifest as a list of triples <object type, object ID, branch name>, sorted by branch name.

Note: "branch" is used here in the generic Software Heritage meaning, which encompasses branches, tags, etc., depending on the VCS.

Object ID

Each snapshot object has as its object ID a cryptographic hash (the same used elsewhere in the Merkle DAG) of its textual manifest.

Git implementation

In the spirit of other Git objects, snapshot object for Git repositories can be implemented as follows.

# create repo with some commits, branches, and tags
$ git init test
$ cd test/
$ echo foo > foo.txt
$ git add foo.txt 
$ git commit -m 'checkin foo'
$ git branch foo
$ echo bar >> foo.txt 
$ git commit -a -m 'add bar'
$ git tag bar
$ echo baz >> foo.txt 
$ git commit -a -m 'add baz'

# ASSUMPTION: the output of git show-ref is sorted by ref name using
# the usual Git sort algorithm for textual object manifests. This is
# currently the case as of Git 2.8.1, but it is not documented
# behavior in git-show-ref(1).

# repository object in full (the manifest)
$ git show-ref | \
  while read id ref ; do
    type=$(git cat-file -t $id)
    echo $type $id $ref
  done \
  > /tmp/snapshot-object.txt
$ cat /tmp/snapshot-object.txt
commit 585f6e27f540012af621a18d0155aae2a8ec0276 refs/heads/foo
commit 6d976a397fe0b28a5bc59540e64f7f36a861af68 refs/heads/master
commit 521cb6d728f9fa3d6c4d73ddd309c0796ddf6995 refs/tags/bar

# repository object ID, as a Git SHA1
$ git hash-object -w --stdin --literally -t snapshot < /tmp/snapshot-object.txt
470d2daa27715987685708b816bf2b52ba5a47c8

# raw content of the repository object, including Git header
$ zlib-flate -uncompress < .git/objects/47/0d2daa27715987685708b816bf2b52ba5a47c8
snapshot 191commit 585f6e27f540012af621a18d0155aae2a8ec0276 refs/heads/foo
commit 6d976a397fe0b28a5bc59540e64f7f36a861af68 refs/heads/master
commit 521cb6d728f9fa3d6c4d73ddd309c0796ddf6995 refs/tags/bar

# i.e., a 191-byte long object of type "snapshot"
# (note that a "\0" before the first "commit" string has been stripped)