From 283ad6595f3ccfe87c6f0fa0970df3295c69244d Mon Sep 17 00:00:00 2001
From: Brian Cully <bjc@kublai.com>
Date: Mon, 30 Mar 2009 17:25:48 -0400
Subject: Add perldoc.

---
 read_object.pl | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/read_object.pl b/read_object.pl
index 22dd2cf..520502d 100755
--- a/read_object.pl
+++ b/read_object.pl
@@ -1,5 +1,24 @@
 #!/usr/bin/env perl
 
+=head1 NAME
+
+read_object.pl - Read and print an object from the git object store.
+
+=head1 SYNOPSIS
+
+read_object.pl filename
+
+=head1 DESCRIPTION
+
+Reads C<filename> as a git object and print it out in a human-readable
+format. The purpose of this code is to show the ease of reading and
+writing git objects and explore the git object store directly.
+
+By using a short perl program, the object store formats can be
+trivially verified and understood.
+
+=cut
+
 use Compress::Zlib;
 use Digest::SHA qw(sha1_hex);
 use File::Basename;
@@ -14,6 +33,23 @@ my $out = format_object($type, $data);
 print "signature: $signature\ntype: $type\nsize: $size\n"
     . ("-" x 40) . "\n$out\n";
 
+=head1 FUNCTIONS
+
+=over
+
+=item C<read_object($str)>
+
+Reads C<$str> as git object and returns it unpacked into a signature,
+type, size, and data section.
+
+All objects are prefixed with their type, a space, their size, and a
+NUL byte before being compressed. The type and size are normal
+strings, and thus there is no size limit of blobs.
+
+Signature is computed based on the uncompressed blob, but does include
+the type and size prefix.
+
+=cut
 sub read_object {
     my ($zlib_data) = @_;
 
@@ -29,6 +65,16 @@ sub read_object {
     ($sig, $type, $size, $data);
 }
 
+=item C<format_object($str)>
+
+Returns a readable representation of C<$str>. If no useful
+representation can be created, a hexdump is returned by default.
+
+Because commits and tags are expected to be ASCII data, just return
+them without any formatting, whereas trees and blobs are turned into
+appropriate representations.
+
+=cut
 sub format_object {
     my ($type, $obj) = @_;
 
@@ -44,6 +90,16 @@ sub format_object {
     }
 }
 
+=item C<format_tree($str)>
+
+Reads C<$str> as a tree object as `$filemodes $name\0$id', where $id
+is a binary SHA-1 ID. Returns the tree as rows of `$filemode
+$id\t$name', as git-ls-tree(1).
+
+Interestingly, tree objects use a binary ID instead of an ASCII
+string, and this appears to be the only place where that's done.
+
+=cut
 sub format_tree {
     my ($str) = @_;
 
@@ -61,6 +117,12 @@ sub format_tree {
     join "\n", @rc;
 }
 
+=item C<hexdump($str)>
+
+Returns C<$str> as rows of 16 hexadecimal digits, followed by their
+character representations, if printable, otherwise `.'
+
+=cut
 sub hexdump {
     my ($str) = @_;
 
@@ -81,4 +143,16 @@ sub hexdump {
     } @chunks;
 }
 
+=back
+
+=head1 AVAILABILITY
+
+L<http://github.com/bjc/dvcs-git-slides>
+
+=head1 AUTHOR
+
+Brian Cully <bjc@kublai.com>
+
+=cut
+
 1;
-- 
cgit v1.2.3