128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
# Object Codec
|
|
|
|
This module implements a codec for the binary git object format for blobs, trees, tags, and commits.
|
|
|
|
This library is useful for writing new storage backends. Normal users will probably
|
|
just use one of the existing mixins for object storage.
|
|
|
|
## codec.frame({type,body}) -> buffer
|
|
|
|
This function accepts an object with `type` and `body` properties. The `type`
|
|
property must be one of "blob", "tree", "commit" or "tag". The body can be a
|
|
pre-encoded raw-buffer or a plain javascript value. See encoder docs below for
|
|
the formats of the different body types.
|
|
|
|
The returned binary value is the fully framed git object. The sha1 of this is
|
|
the git hash of the object.
|
|
|
|
```js
|
|
var codec = require('js-git/lib/object-codec');
|
|
var sha1 = require('git-sha1');
|
|
|
|
var bin = codec.frame({ type: "blob", body: "Hello World\n"});
|
|
var hash = sha1(bin);
|
|
```
|
|
|
|
## codec.deframe(buffer, decode) -> {type,body}
|
|
|
|
This function accepts a binary git buffer and returns the `{type,body}` object.
|
|
|
|
If `decode` is true, then the body will also be decoded into a normal javascript
|
|
value. If `decode` is false or missing, then the raw-buffer will be in body.
|
|
|
|
## codec.encoders
|
|
|
|
This is an object containing 4 encoder function Each function has the signature:
|
|
|
|
encode(body) -> raw-buffer
|
|
|
|
Where body is the JS representation of the type and raw-buffer is the git encoded
|
|
version of that value, but without the type and length framing.
|
|
|
|
```js
|
|
var encoders = require('js-git/lib/object-codec').encoders;
|
|
var modes = require('js-git/lib/modes');
|
|
```
|
|
|
|
Blobs must be native binary values (Buffer in node, Uint8Array in browser).
|
|
It's recommended to either use the `bodec` library to create binary values from
|
|
strings directly or configure your system with the `formats` mixin that allows
|
|
for unicode strings when working with blobs.
|
|
|
|
```js
|
|
rawBin = encoders.blob(new Uint8Array([1,2,3,4,5,6]));
|
|
rawBin = encoders.blob(bodec.fromUnicode("Hello World"));
|
|
```
|
|
|
|
Trees are objects with filename as key and object with {mode,hash} as value.
|
|
The modes are integers. It's best to use the modes module to help.
|
|
|
|
```js
|
|
rawBin = encoders.tree({ "greeting.txt": {
|
|
mode: modes.file,
|
|
hash: blobHash
|
|
}});
|
|
```
|
|
|
|
Commits are objects with required fields {tree,author,message}
|
|
Also if there is a single parent, you specify it with `parent`.
|
|
|
|
Since a commit can have zero or more parent commits, you specify the parent
|
|
hashes via the `parents` property as an array of hashes.
|
|
|
|
The `author` field is required and contains {name,email,date}.
|
|
|
|
Commits also require a `committer` field with the same structure as `author`.
|
|
|
|
The `date` property of `author` and `committer` is in the format {seconds,offset}
|
|
Where seconds is a unix timestamp in seconds and offset is the number of minutes
|
|
offset for the timezone. (Your local offset can be found with `(new Date).getTimezoneOffset()`)
|
|
|
|
The `message` field is mandatory and a simple string.
|
|
|
|
```js
|
|
rawBin = encoders.commit({
|
|
tree: treeHash,
|
|
author: {
|
|
name: "Tim Caswell",
|
|
email: "tim@creationix.com",
|
|
date: {
|
|
seconds: 1391790910,
|
|
offset: 7 * 60
|
|
}
|
|
},
|
|
parents: [ parentCommitHash ],
|
|
message: "This is a test commit\n"
|
|
});
|
|
```
|
|
|
|
Annotated tags are like commits, except they have different fields.
|
|
|
|
```js
|
|
rawBin = encoders.tag({
|
|
object: commitHash,
|
|
type: "commit",
|
|
tag: "mytag",
|
|
tagger: {
|
|
name: "Tim Caswell",
|
|
email: "tim@creationix.com",
|
|
date: {
|
|
seconds: 1391790910,
|
|
offset: 7 * 60
|
|
}
|
|
},
|
|
message: "Tag it!\n"
|
|
});
|
|
```
|
|
|
|
## codec.decoders
|
|
|
|
This is just like `codec.encoders` except these functions do the opposite.
|
|
They have the format:
|
|
|
|
decode(raw-buffer) -> body
|
|
|
|
```js
|
|
var commit = decoders.commit(rawCommitBin);
|
|
```
|