README: Add example

1 files changed, 84 insertions, 0 deletions

diff --git a/README.md b/README.md
index 63a1c8a3..3bc1ef29 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,90 @@ guarantee that the API will break every now and then. Do not use in
 production. When we do have tagged releases, we will likely follow
 [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
+## Example program
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"git.sr.ht/~runxiyu/furgit"
+)
+
+func main() {
+	// Open a Git repository at a filesystem path.
+	repo, err := furgit.OpenRepository("/path/to/repo")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Resolve HEAD to its reference.
+	headRef, err := repo.ResolveHEAD()
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Resolve the reference to its object ID.
+	headID, err := repo.ResolveRef(headRef)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Load the commit object.
+	obj, err := repo.ReadObject(headID)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Assert that it is a commit.
+	commit, ok := obj.(*furgit.Commit)
+	if !ok {
+		log.Fatalf("HEAD is %T, expected *furgit.Commit", obj)
+	}
+
+	// Load the commit’s tree.
+	treeObj, err := repo.ReadObject(commit.Tree)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Assert that it is a tree.
+	tree, ok := treeObj.(*furgit.Tree)
+	if !ok {
+		log.Fatalf("Expected commit tree to be *furgit.Tree, got %T", treeObj)
+	}
+
+	// Try to locate README or README.md.
+	var entry *furgit.TreeEntry
+	for _, name := range [][]byte{[]byte("README"), []byte("README.md")} {
+		if e := tree.Entry(name); e != nil {
+			entry = e
+			break
+		}
+	}
+	if entry == nil {
+		log.Fatal("README not found")
+	}
+
+	// Load the blob.
+	blobObj, err := repo.ReadObject(entry.ID)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Assert that it is a blob. It could be a tree if someone made a directory
+	// named README.
+	blob, ok := blobObj.(*furgit.Blob)
+	if !ok {
+		log.Fatalf("Expected README to be *furgit.Blob, got %T", blobObj)
+	}
+
+	fmt.Printf("%s\n", blob.Data)
+}
+```
+
 ## History
 
 Furgit's lineage is from [Villosa](https://codeberg.org/lindenii/villosa), a