Merge pull request #118 from samoht/master

Update REAMDE, improve docs, prepare the release

LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2013-2015 Thomas Gazagnaire <thomas@gazagnaire.org>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -33,67 +33,52 @@ $ opam install git
 ### What is supported
 
 * The loose object files can be read and written;
-
-- binary blobs (files)
-- trees (directories)
-- commits (revision history)
-
-* The pack files and pack indexes (which are collections of compressed
-  loose objects using a diff-based representation) can be read and
-  written). Moreover, diff hunks are exposed using a higher-level
+  - [blobs](http://mirage.github.io/ocaml-git/Blob.html) (files)
+  - [trees](http://mirage.github.io/ocaml-git/Tree.html) (directories)
+  - [commits](http://mirage.github.io/ocaml-git/Commit.html) (revision history)
+  - [tags](http://mirage.github.io/ocaml-git/Tag.html) (annotated tags)
+  - [references](http://mirage.github.io/ocaml-git/Reference.html) (branch names)
+
+* The [pack files](http://mirage.github.io/ocaml-git/Pack.html)
+  (collections of compressed loose objects using a binary-diff representation)
+  and [pack indexes](http://mirage.github.io/ocaml-git/Pack_index.html)
+  (indexes of pack files) can be read and
+  written). The binary diff hunks are exposed using a high-level
   position-independent representation so that they can be manipulated
-  more easily.
+  more easily. Pack file can be created but will not be compressed yet.
 
-* The index file (cache) -- used as for managing the stagging area --
-  is fully supported. Which means that `git diff` and `git status`
+* The [index file] (http://mirage.github.io/ocaml-git/Index.html)
+  (used as for managing the stagging area)
+  are fully supported. Which means that `git diff` and `git status`
   will work as expected on a repository created by the library.
 
-* Basic support for client-side cloning and fetching (using bare and
- deepen options) but with no support for fancy download capabilities
- which is exposed by usual Git servers.
+* [Cloning and fetching](http://mirage.github.io/ocaml-git/Sync.html)
+  (using various options) are fully supported for
+  the Git protocol, the smart-HTTP protocol and `git+ssh`. A subset
+  of the protocol capabilities are implemented (mainly `thin-pack`,
+  `ofs-delta`, `side-band-64k` and `allow-reachable-sha1-in-want`).
 
-### What is *not* supported
+* Pushing is still experimental and need more testing.
 
-* Only client-side operations are currently supported. Implementing
-  the corresponding server-side implementation is high on the TODO
-  list: using a dummy compression scheme, this should not be too hard
-  to add, though.
+* An abstraction for Git [Store](http://mirage.github.io/ocaml-git/Store.S.html)
+  is available. Various store implementations are available:
+  - An [in-memory](http://mirage.github.io/ocaml-git/Memory.html) implementation;
+  - A [unix filesystem](http://mirage.github.io/ocaml-git/Git_unix.FS.html)
+    implementation;
+  - A [mirageOS](http://mirage.github.io/ocaml-git/Git_mirage.html) implementation,
+    requiring an `V1_LWT.FS` implementation.
 
-* Merging and rebasing strategies are not supported.
+### What is *not* supported
 
-### Performance
+* No server-side operations are currently supported.
+* No GC.
+* Updates, merge and rebase are not supported. Use
+  [irmin](https://github.com/mirage/irmin) instead.
 
-Performance is comparable to the `git` command. For instance, when
-downloading and processing a 5.4MiB pack file (the download time
-itself takes ~10s):
+### Performance
 
-```
-$ time ogit clone git://github.com/ocaml/opam-repository
-Cloning into 'opam-repository' ...
-Receiving data ... done.
-Resolving deltas: 100% (37294/37294), done.
-remote: Counting objects: 37294, done.
-Checking out files: 100% (6527/6527), done.
-HEAD is now at 267e08725291fc61b8411c0f20553ddd2e246d4f
-
-real 0m22.522s
-user 0m4.954s
-sys  0m5.078s
-```
+Performance is comparable to the Git tool.
 
-```
-$ time git clone git://github.com/ocaml/opam-repository
-Cloning into 'opam-repository'...
-remote: Reusing existing pack: 37868, done.
-remote: Total 37868 (delta 0), reused 0 (delta 0)
-Receiving objects: 100% (37868/37868), 5.41 MiB | 408.00 KiB/s, done.
-Resolving deltas: 100% (13973/13973), done.
-Checking connectivity... done
-
-real	 0m17.409s
-user	 0m1.198s
-sys	 0m0.925s
-```
+### License
 
-Not much energy have been dedicated to profiling the protocol
-implementation yet, so there is still plenty room for improvement.
+MIT, see LICENSE file for its text.

_oasis

@@ -20,11 +20,13 @@ Library git
   Path:              lib/
   Findlibname:       git
   InternalModules:   LRU
-  Modules:           SHA, Blob, Index, Commit, Misc, Version,
-                     Global_graph, Pack, Pack_index, Packed_value,
-                     Reference, Sync, Tag, Tree, User, Value,
-                     Object, Object_type, Store, Search, Gri,
-                     Memory, FS, Packed_refs, Inflate
+  Modules:           Misc, SHA, Inflate, Object, Object_type,
+                     Blob, Tree, Commit, Tag, Reference, Value,
+                     Pack, Pack_index, Packed_value, Packed_refs, Index,
+                     Sync, Gri, Search, Global_graph, User,
+                     Store,
+                     Memory, FS,
+                     Version
   BuildDepends:      mstruct, dolog, ocamlgraph, uri, lwt, hex, stringext, crc
 
 Library git_top

_tags

@@ -1,5 +1,5 @@
 # OASIS_START
-# DO NOT EDIT (digest: 09920af19b83c7eb429e6939e5bf764e)
+# DO NOT EDIT (digest: 501285491099ba47432025adabcf8ece)
 # Ignore VCS directories, you can use the same kind of rule outside
 # OASIS_START/STOP if you want to exclude directories that contains
 # useless stuff for the build process
@@ -16,31 +16,31 @@ true: annot, bin_annot
 "_darcs": not_hygienic
 # Library git
 "lib/git.cmxs": use_git
+"lib/misc.cmx": for-pack(Git)
 "lib/SHA.cmx": for-pack(Git)
+"lib/inflate.cmx": for-pack(Git)
+"lib/object.cmx": for-pack(Git)
+"lib/object_type.cmx": for-pack(Git)
 "lib/blob.cmx": for-pack(Git)
-"lib/index.cmx": for-pack(Git)
+"lib/tree.cmx": for-pack(Git)
 "lib/commit.cmx": for-pack(Git)
-"lib/misc.cmx": for-pack(Git)
-"lib/version.cmx": for-pack(Git)
-"lib/global_graph.cmx": for-pack(Git)
+"lib/tag.cmx": for-pack(Git)
+"lib/reference.cmx": for-pack(Git)
+"lib/value.cmx": for-pack(Git)
 "lib/pack.cmx": for-pack(Git)
 "lib/pack_index.cmx": for-pack(Git)
 "lib/packed_value.cmx": for-pack(Git)
-"lib/reference.cmx": for-pack(Git)
+"lib/packed_refs.cmx": for-pack(Git)
+"lib/index.cmx": for-pack(Git)
 "lib/sync.cmx": for-pack(Git)
-"lib/tag.cmx": for-pack(Git)
-"lib/tree.cmx": for-pack(Git)
+"lib/gri.cmx": for-pack(Git)
+"lib/search.cmx": for-pack(Git)
+"lib/global_graph.cmx": for-pack(Git)
 "lib/user.cmx": for-pack(Git)
-"lib/value.cmx": for-pack(Git)
-"lib/object.cmx": for-pack(Git)
-"lib/object_type.cmx": for-pack(Git)
 "lib/store.cmx": for-pack(Git)
-"lib/search.cmx": for-pack(Git)
-"lib/gri.cmx": for-pack(Git)
 "lib/memory.cmx": for-pack(Git)
 "lib/FS.cmx": for-pack(Git)
-"lib/packed_refs.cmx": for-pack(Git)
-"lib/inflate.cmx": for-pack(Git)
+"lib/version.cmx": for-pack(Git)
 "lib/LRU.cmx": for-pack(Git)
 <lib/*.ml{,i,y}>: pkg_crc
 <lib/*.ml{,i,y}>: pkg_dolog

lib/FS.ml

@@ -342,7 +342,7 @@ module Make (IO: IO) (D: SHA.DIGEST) (I: Inflate.S) = struct
       IO.file_exists file >>= function
       | true  -> Lwt.return_unit
       | false ->
-        let pack = Pack_IO.Raw.buffer pack in
+        let pack = Pack.Raw.buffer pack in
         let temp_dir = temp_dir t in
         IO.write_file file ~temp_dir pack
 
@@ -551,11 +551,11 @@ module Make (IO: IO) (D: SHA.DIGEST) (I: Inflate.S) = struct
 
   let write_pack t pack =
     Log.debug "write_pack";
-    let sha1 = Pack_IO.Raw.sha1 pack in
-    let index = Pack_IO.Raw.index pack in
+    let sha1 = Pack.Raw.sha1 pack in
+    let index = Pack.Raw.index pack in
     Packed.write_pack t sha1 pack   >>= fun () ->
     Packed.write_pack_index t sha1 index >>= fun () ->
-    Lwt.return (Pack_IO.Raw.keys pack)
+    Lwt.return (Pack.Raw.keys pack)
 
   let write_reference t ref sha1 =
     let file = t.dot_git / Reference.to_raw ref in

lib/commit.mli

@@ -14,7 +14,7 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *)
 
-(** Git commits. *)
+(** Commits. *)
 
 type t = {
   tree     : SHA.Tree.t;

lib/git.mlpack

@@ -1,29 +1,29 @@
 # OASIS_START
-# DO NOT EDIT (digest: 42b4a7ea741b2cd57147917461410665)
+# DO NOT EDIT (digest: cef061f9d94df1d68949576e76304f23)
+Misc
 SHA
+Inflate
+Object
+Object_type
 Blob
-Index
+Tree
 Commit
-Misc
-Version
-Global_graph
+Tag
+Reference
+Value
 Pack
 Pack_index
 Packed_value
-Reference
+Packed_refs
+Index
 Sync
-Tag
-Tree
+Gri
+Search
+Global_graph
 User
-Value
-Object
-Object_type
 Store
-Search
-Gri
 Memory
 FS
-Packed_refs
-Inflate
+Version
 LRU
 # OASIS_STOP

lib/git.odocl

@@ -1,30 +1,30 @@
 # OASIS_START
-# DO NOT EDIT (digest: 4211e35ad430cb1587fceee4f2e5538a)
+# DO NOT EDIT (digest: b9aef35b4eb5bae846b1977d4b14ceaa)
+Misc
 SHA
+Inflate
+Object
+Object_type
 Blob
-Index
+Tree
 Commit
-Misc
-Version
-Global_graph
+Tag
+Reference
+Value
 Pack
 Pack_index
 Packed_value
-Reference
+Packed_refs
+Index
 Sync
-Tag
-Tree
+Gri
+Search
+Global_graph
 User
-Value
-Object
-Object_type
 Store
-Search
-Gri
 Memory
 FS
-Packed_refs
-Inflate
+Version
 unix/Git_unix
 mirage/Git_mirage
 # OASIS_STOP

lib/memory.ml

@@ -132,7 +132,7 @@ module Make (D: SHA.DIGEST) = struct
         Lwt.return_unit
       ) pack
     >>= fun () ->
-    let keys = Pack_IO.keys pack in
+    let keys = Pack.keys pack in
     Lwt.return keys
 
   let keys t =

lib/mirage/git_mirage.mli

@@ -14,8 +14,7 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *)
 
-(** Mirage implementation of the Git file-system backend and
-    protocol. *)
+(** Mirage backend. *)
 
 module type FS = sig
 

lib/object_type.mli

@@ -14,7 +14,7 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  *)
 
-(** Git object types. *)
+(** Object types. *)
 
 type t =
   | Blob