tree

Documentation

Overview

Package tree implements functions to hash directory trees.

To calculate the hash of a directory tree (a tree hash) a list of all files in the directory root (a tree list) is created as follows.

All the files below the root of the directory tree are traversed in lexical order (with filepath.Walk) and printed in this format:

m xxx filename

Where:

m        is the mode ('f' or 'x')
xxx      is the SHA256 hash for the file in hex notation
filename is the file name with directory prefix starting at root

Example list:

f 7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730 bar/baz.txt
x b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c foo.txt

The fields are separated with single white space characters and the lines are separated with single newline characters.

Directories are only implicitly listed (i.e., if they contain files). Entries start with 'f' if it is a regular file (read and write permission for user) and with 'x' if it is an executable (read, write, and executable for user).

The directory tree must only contain directories, regular files, or executables.

The deterministic tree list serves as the basis for a hash of a directory tree (the tree hash), which is the SHA256 hash of the tree list in hex notation.

Index

• Constants
• func Hash(root string, excludePaths []string) (*[32]byte, error)
• func HashList(entries []ListEntry) [32]byte
• func ListBytes(root string, excludePaths []string) ([]byte, error)
• func PrintList(entries []ListEntry) []byte
• func SHA256(path string) (*[32]byte, error)
• type ListEntry
  • func List(root string, excludePaths []string) ([]ListEntry, error)

Constants

const EmptyHash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

EmptyHash is the hash of an empty directory tree (in hex notation).

Functions

func Hash

func Hash(root string, excludePaths []string) (*[32]byte, error)

Hash returns a SHA256 hash of all files and directories in the file tree rooted at root, except for the paths in excludePaths (the tree hash).

func HashList

func HashList(entries []ListEntry) [32]byte

HashList returns the SHA256 hash of a list of entries.

This is a convience function to calculate a tree hash out of entries without having to print them first in the canonical format.

func ListBytes

func ListBytes(root string, excludePaths []string) ([]byte, error)

ListBytes returns a list in lexical order of newline separated hashes of all files in the file tree rooted at root in the canonical format, except for the paths in excludePaths (the tree list).

func PrintList

func PrintList(entries []ListEntry) []byte

PrintList prints a list of (sorted) entries in the canonical tree list format.

This is a convience function to bring a list of entries returned by the List functions into the format returned by the ListBytes function.

func SHA256

func SHA256(path string) (*[32]byte, error)

SHA256 returns the SHA256 hash of the file with given path.

Types

type ListEntry

type ListEntry struct {
	Mode     rune     // 'f' (regular) or 'x' (binary)
	Filename string   // Including directory path starting from root
	Hash     [32]byte // SHA256 hash
}

ListEntry describes a directory tree entry.

func List

func List(root string, excludePaths []string) ([]ListEntry, error)

List returns a list in lexical order of ListEntry structs of all files in the file tree rooted at root. See the ListBytes function for details.

This is a convenience function to make a tree list accessible without having to parse tree list entries.