dirtree

package module
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2022 License: MIT Imports: 9 Imported by: 0

README

go.dev reference Go Report Card codecov

Tests-linux actions Status Tests-others Actions Status

Dirtree

Dirtree lists the files in a directory, or an fs.FS, in a deterministic, configurable and cross-platform manner.

Very useful for testing, golden files, etc.

Usage

Add the dirtree module as dependency:

go get github.com/arl/dirtree@latest
  • Basic usage

To list the ./testdata directory, recursively, to standard output:

err := dirtree.Write(os.Stdout, "./testdata")
if err != nil {
	log.Fatal(err)
}

Using options, you can control what files are listed and what information is shown (size, CRC32, type, etc.).

Documentation

Walk your OS filesystem or an fs.FS?

Use dirtree.Write and dirtree.Sprint to walk your filesystem, or,
use dirtree.WriteFS and dirtree.SprintFS to walk an fs.FS.
These functions are useful when you're interested by the whole directory listing, to use for golden tests or displaying to user.

If you don't need to print the directory tree, you can use dirtree.List, it returns a slice of dirtree.Entry which you can examine programmaticaly.

All above functions accept a variable number (possibly none) of options. For example:

dirtree.Write(os.Stdout, "dir", dirtree.Depth(2), dirtree.ModeSize | dirtree.ModeCRC32)

In the following examples the root directory has the following content:

.
├── bar
│   ├── dir1
│   │   └── passwords
│   └── dir2
├── baz
│   └── a
│       └── b
│           └── c
│               └── nested
├── foo
│   ├── dir1
│   └── dir2
│       └── secrets
├── other-stuff.mp3
└── symlink -> foo/dir2/secrets
Default output (no options)

Calling dirtree.Write without any option will show, as in:

dirtree.Write(os.Stdout, "dir")

shows:

d            .
d            bar
d            bar/dir1
f 0b         bar/dir1/passwords
d            bar/dir2
d            baz
d            baz/a
d            baz/a/b
d            baz/a/b/c
f 1407216b   baz/a/b/c/nested
d            foo
d            foo/dir1
d            foo/dir2
f 7922820b   foo/dir2/secrets
f 39166b     other-stuff.mp3
?            symlink
Type option

The dirtree.Type option limits the files present in the listing based on their types. It's a string that may contain one or more characters:

  • f for regular files
  • d for directories
  • ? for anything else (symlink, etc.)

For example, dirtree.Type("f") will only show regular files while dirtree.Type("fd") will both show regular files and directories.

By default, dirtree shows all types if the Type option is not provided.

dirtree.Write(os.Stdout, "dir", dirtree.Type("f?"))

displays:

f 0b         crc=00000000 bar/dir1/passwords
f 1407216b   crc=733eee4d baz/a/b/c/nested
f 7922820b   crc=fe02449a foo/dir2/secrets
f 39166b     crc=d298754e other-stuff.mp3
?            crc=n/a      symlink
PrintMode option

The dirtree.PrintMode option is a bitset controlling the amount of information to show for each listed file.

  • dirtree.ModeType prints 'd', 'f' or '?', depending on the file type, directory, regular file or anything else.
  • dirtree.ModeSize shows the file size in bytes, for regular files only.
  • dirtree.ModeCRC32 shows a CRC32 checksum, for regular files only.

dirtree.ModeDefault combines dirtree.ModeType | dirtree.ModeSize and dirtree.ModeAll shows all information about all files:

dirtree.Write(os.Stdout, "dir", dirtree.ModeAll)

displays:

d            crc=n/a      .
d            crc=n/a      bar
d            crc=n/a      bar/dir1
f 0b         crc=00000000 bar/dir1/passwords
d            crc=n/a      bar/dir2
d            crc=n/a      baz
d            crc=n/a      baz/a
d            crc=n/a      baz/a/b
d            crc=n/a      baz/a/b/c
f 1407216b   crc=733eee4d baz/a/b/c/nested
d            crc=n/a      foo
d            crc=n/a      foo/dir1
d            crc=n/a      foo/dir2
f 7922820b   crc=fe02449a foo/dir2/secrets
f 39166b     crc=d298754e other-stuff.mp3
?            crc=n/a      symlink
Ignore files

The dirtree.Ignore option allows to ignore files matching a pattern. The path relative to the chosen root is matched against the pattern. Ignore follows the syntax used and described with the filepath.Match function. Before checking if it matches a pattern, a path is first converted to its slash ('/') based version, to ensure cross-platform consistency of the dirtree package.

dirtree.Ignore can be provided multiple times to ignore multiple patterns. A file is ignored from the listing as long as at it matches at least one dirtree.Ignore pattern. Also, dirtree.Ignore has precedence over dirtree.Match.

The pattern syntax is that of filepath.Match:

pattern:
	{ term }
term:
	'*'         matches any sequence of non-Separator characters
	'?'         matches any single non-Separator character
	'[' [ '^' ] { character-range } ']'
	            character class (must be non-empty)
	c           matches character c (c != '*', '?', '\\', '[')
	'\\' c      matches character c

character-range:
	c           matches character c (c != '\\', '-', ']')
	'\\' c      matches character c
	lo '-' hi   matches character c for lo <= c <= hi

dirtree.Write(os.Stdout, dir, dirtree.Ignore("*/dir1"))

prints:

d            .
d            bar
f 0b         bar/dir1/passwords
d            bar/dir2
d            baz
d            baz/a
d            baz/a/b
d            baz/a/b/c
f 1407216b   baz/a/b/c/nested
d            foo
d            foo/dir2
f 7922820b   foo/dir2/secrets
f 39166b     other-stuff.mp3
?            symlink
Match to limit the listing to files matching a pattern

The dirtree.Match option limits the listing to files that match a pattern. The path relative to the chosen root is matched against the pattern. dirtree.Match follows the syntax used and described with the filepath.Match function. Before checking if it matches a pattern, a path is first converted to its slash ('/') based version, to ensure cross-platform consistency of the dirtree package.

dirtree.Match can be provided multiple times to match multiple patterns. A file is included in the listing as long as at it matches at least one dirtree.Match pattern, unless it matches an dirtree.Ignore pattern (since dirtree.Ignore has precedence over dirtree.Match).

The pattern syntax is that of filepath.Match.

dirtree.Write(os.Stdout, dir, dirtree.Match("*/*[123]"), dirtree.Match("*[123]"))

prints:

d            bar/dir1
d            bar/dir2
d            foo/dir1
d            foo/dir2
f 39166b     other-stuff.mp3
Directory Depth

The dirtree.Depth option is an integer that controls the maximum depth to descend into, starting from the root directory. Everything below that depth won't be shown.

dirtree.Write(os.Stdout, dir, dirtree.Depth(1))

reports:

d            .
d            bar
d            baz
d            foo
f 39166b     other-stuff.mp3
?            symlink
ExcludeRoot

dirtree.ExcludeRoot hides the root directory in the listing.

dirtree.Write(os.Stdout, dir, dirtree.ExcludeRoot)

d            bar
d            bar/dir1
f 0b         bar/dir1/passwords
d            bar/dir2
d            baz
d            baz/a
d            baz/a/b
d            baz/a/b/c
f 1407216b   baz/a/b/c/nested
d            foo
d            foo/dir1
d            foo/dir2
f 7922820b   foo/dir2/secrets
f 39166b     other-stuff.mp3
?            symlink

TODO

  • streaming API (for large number of files)

License

Documentation

Overview

Package dirtree implements utility routines to list files in a deterministic and cross-patform manner.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Sprint 

func Sprint(root string, opts ...Option) (string, error)

Sprint walks the directory rooted at root and returns a string containing the list of files.

It's a wrapper around Write(...) provided for convenience.

func SprintFS 

func SprintFS(fsys fs.FS, root string, opts ...Option) (string, error)

SprintFS walks the directory rooted at root in the given filesystem and returns the list of files.

It's a wrapper around WriteFS(...) provided for convenience.

func Write 

func Write(w io.Writer, root string, opts ...Option) error

Write walks the directory rooted at root and prints one file per line into w.

A variable number of options can be provided to control the limit the files printed and/or the amount of information printed for each of them.

func WriteFS 

func WriteFS(w io.Writer, fsys fs.FS, root string, opts ...Option) error

WriteFS walks the directory rooted at root in the given filesystem and prints one file per line into w.

A variable number of options can be provided to control the limit the files printed and/or the amount of information printed for each of them.

Types

type Depth 

type Depth int

The Depth option indicates how many levels of directories below root should we recurse into. 0, the default, means there's no limit.

type Entry 

type Entry struct {
	Path     string
	RelPath  string
	Type     FileType
	Size     int64
	Checksum string
	// contains filtered or unexported fields
}

An Entry holds gathered information about a particular file.

func List 

func List(root string, opts ...Option) ([]*Entry, error)

List walks the directory rooted at root and returns entries.

A variable number of options can be provided to control the limit the files printed and/or the amount of information gathered for each of them.

func ListFS added in v0.1.1 

func ListFS(fsys fs.FS, root string, opts ...Option) ([]*Entry, error)

List walks the directory rooted at root in the given filesystem and returns entries.

A variable number of options can be provided to control the limit the files printed and/or the amount of information gathered for each of them.

func (*Entry) Format 

func (e *Entry) Format() string

Format returns a summary string of e. Some information might be missing, depending on the PrintMode used to create the Entry.

type FileType 

type FileType byte
const (
	File  FileType = 1 << iota // File is for regular files
	Dir                        // Dir is for directories
	Other                      // Other is for anything else (symlink, whatever, ...)
)

type Ignore 

type Ignore string

The Ignore option allows to ignore files matching a pattern. The path relative to the chosen root is matched against the pattern. Ignore follows the syntax used and described with the filepath.Match function. Before checking if it matches a pattern, a path is first converted to its slash ('/') based version, to ensure cross-platform consistency of the dirtree package.

Ignore can be provided multiple times to ignore multiple patterns. A file is ignored from the listing as long as at it matches at least one Ignore pattern. Also, Ignore has precedence over Match.

type IncludeRoot 

type IncludeRoot bool

ExcludeRoot is the option controlling whether the root directory should be printed when listing its content.

type Match 

type Match string

The Match option limits the listing to files that match a pattern. The path relative to the chosen root is matched against the pattern. Match follows the syntax used and described with the filepath.Match function. Before checking if it matches a pattern, a path is first converted to its slash ('/') based version, to ensure cross-platform consistency of the dirtree package.

Match can be provided multiple times to match multiple patterns. A file is included in the listing as long as at it matches at least one Match pattern, unless it matches an Ignore pattern (since Ignore has precedence over Match).

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option is the interface implemented by dirtree types used to control what to list and how to list it. 

var ExcludeRoot Option = IncludeRoot(false)

The ExcludeRoot option hides the root directory from the list.

type PrintMode 

type PrintMode uint32

A PrintMode represents the amount of information to print about a file, next to its filename. PrintMode is a bit set. Somewhat related to os.FileMode and fs.FileMode but much less detailed. 

const (
	// ModeType indicates if file is a directory, a regular file or something
	// else. It prints 'd', 'f' or '?' respectively.
	ModeType PrintMode = 1 << iota

	// ModeSize reports the length in bytes for regular files, "1234b" for
	// example, or nothing for other types where size is not applicable (it
	// would be OS-dependent).
	ModeSize

	// ModeCRC32 computes and reports the CRC-32 checksum for regular files. For
	// other file types, or for files which permissions prevent reading, it
	// shows n/a (i.e. not applicable). Example "crc=294a245b" or "crc=n/a"
	ModeCRC32

	// ModeDefault is a mask showing file type and size.
	ModeDefault PrintMode = ModeType | ModeSize

	// ModeAll is a mask showing all information about a file.
	ModeAll PrintMode = ModeType | ModeSize | ModeCRC32
)

type Type 

type Type string

The Type option limits the files to list based their type. Type can be formed of one or more of: 

'f' for regular files
'd' for directories
'?' for anything else (symlink, etc.)

Source Files

View all Source files

Directories

Path Synopsis
cmd
dirtree

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.