supergit: update crate documentation

apps/servers/octopus/supergit/src/bin/test.rs

@@ -1,38 +1,33 @@
 //! A test binary to use during development
 
-// use std::sync::mpsc::channel;
-// use supergit::{BranchCommit, Repository};
+use supergit::Repository;
 
-// fn main() {
-//     let path = match std::env::args().nth(1) {
-//         Some(p) => p,
-//         None => {
-//             eprintln!("USAGE: supergit-test <path>");
-//             std::process::exit(2);
-//         }
-//     };
-
-//     let repo = Repository::open(path.as_str()).unwrap();
-//     let branches = repo.branches().unwrap();
-//     let main = branches
-//         .into_iter()
-//         .filter(|b| b.name() == Some("master".to_string()))
-//         .nth(0)
-//         .unwrap();
+fn main() {
+    let path = match std::env::args().nth(1) {
+        Some(p) => p,
+        None => {
+            eprintln!("USAGE: supergit-test <path>");
+            std::process::exit(2);
+        }
+    };
 
-//     let head = main.get_head();
-//     let tree = head.get_tree();
-    
-//     println!(
-//         "{:#?}",
-//         tree.history(main.get_all(), "Cargo.toml")
-//             .into_iter()
-//             .map(|c| c.summary())
-//             .collect::<Vec<_>>()
-//     );
-// }
+    let repo = Repository::open(path.as_str()).unwrap();
+    let branches = repo.branches().unwrap();
+    let main = branches
+        .into_iter()
+        .filter(|b| b.name() == Some("main".to_string()))
+        .nth(0)
+        .unwrap();
 
+    let head = main.head();
+    let tree = head.tree();
 
-fn main() {
-    
+    println!(
+        "{:#?}",
+        tree.base_history(main.get_all(), "README.md")
+            .unwrap()
+            .into_iter()
+            .map(|c| c.summary())
+            .collect::<Vec<_>>()
+    );
 }

apps/servers/octopus/supergit/src/lib.rs

@@ -1,8 +1,9 @@
-//! Read-only git repository explorer library.
+//! Strongly typed git repository explorer
 //!
-//! This library provides a more Rustic interface for libgit2, built
-//! on the `git2` bindings.  If you want more low-level access to your
-//! repository, consider using that library instead.
+//! This library provides a more Rustic interface for git
+//! repositories, built on the `git2` bindings.  If you want more
+//! low-level access to your repository, consider using that library
+//! instead.
 //!
 //! supergit aims to make queries into a git repo as typed and easy as
 //! possible.  Start by creating a
@@ -10,10 +11,25 @@
 //! fetching [`Branch`](struct.Branch.html)es that you are interested
 //! in.
 //!
-//! Unlike `libgit2`, this library can resolve reverse dependencies
-//! between files, and their commit history.  Some of these functions
-//! are very computationally intensive, and will be marked with their
-//! runtime cost.
+//! ```no_run
+//! use supergit::Repository;
+//! let r = Repository::open("/path/to/repo").unwrap();
+//! println!("{:?}", r.branches());
+//!
+//! let branch = r.branch("main").unwrap();
+//! let head = branch.head();
+//! println!("{}: {}", head.id(), head.summary().unwrap_or("".into()));
+//! ```
+//!
+//! ## Library structure
+//!
+//! The main abstraction layer for a repository is a set of iterators,
+//! over branches, commits, and files in commit trees.  Some functions
+//! implemented in `supergit` are quite computationally intensive;
+//! they are marked as such with their runtime cost!
+//!
+//! It's recommended to include [`supergit::prelude`](crate::prelude)
+//! to get started with development.
 
 pub mod branch;