{"id":17086647,"url":"https://github.com/arl/dirtree","last_synced_at":"2025-03-23T14:41:46.429Z","repository":{"id":40480048,"uuid":"389044376","full_name":"arl/dirtree","owner":"arl","description":"Print directory structure in Go. Useful for command-line UI, golden files, testing, etc.","archived":false,"fork":false,"pushed_at":"2022-05-05T17:25:49.000Z","size":84,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-28T20:44:48.903Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-24T08:32:58.000Z","updated_at":"2024-10-24T05:42:12.000Z","dependencies_parsed_at":"2022-08-09T21:40:56.184Z","dependency_job_id":null,"html_url":"https://github.com/arl/dirtree","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arl%2Fdirtree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arl%2Fdirtree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arl%2Fdirtree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arl%2Fdirtree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arl","download_url":"https://codeload.github.com/arl/dirtree/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245119575,"owners_count":20563762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T13:29:08.116Z","updated_at":"2025-03-23T14:41:46.378Z","avatar_url":"https://github.com/arl.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat-square)](https://pkg.go.dev/github.com/arl/dirtree)\n[![Go Report Card](https://goreportcard.com/badge/github.com/arl/dirtree)](https://goreportcard.com/report/github.com/arl/dirtree)\n[![codecov](https://codecov.io/gh/arl/dirtree/branch/main/graph/badge.svg)](https://codecov.io/gh/arl/dirtree)\n\n[![Tests-linux actions Status](https://github.com/arl/dirtree/actions/workflows/tests-linux.yml/badge.svg)](https://github.com/arl/dirtree/actions)\n[![Tests-others Actions Status](https://github.com/arl/dirtree/actions/workflows/tests-others.yml/badge.svg)](https://github.com/arl/dirtree/actions)\n\nDirtree\n========\n\n**Dirtree** lists the files in a directory, or an [fs.FS](https://pkg.go.dev/io/fs#FS), in a deterministic, configurable and cross-platform manner.\n\nVery useful for testing, golden files, etc.\n\n\nUsage\n-----\n\nAdd the `dirtree` module as dependency:\n\n    go get github.com/arl/dirtree@latest\n\n\n - Basic usage\n\nTo list the `./testdata` directory, recursively, to standard output:\n\n```go\nerr := dirtree.Write(os.Stdout, \"./testdata\")\nif err != nil {\n\tlog.Fatal(err)\n}\n```\n\nUsing options, you can control what files are listed and what information is shown (size, CRC32, type, etc.).\n\n\n# Documentation\n\n## Walk your OS filesystem or an [`fs.FS`](https://pkg.go.dev/io/fs#FS)?\n\nUse `dirtree.Write` and `dirtree.Sprint` to walk your filesystem, or,  \nuse `dirtree.WriteFS` and `dirtree.SprintFS` to walk an [fs.FS](https://pkg.go.dev/io/fs#FS).  \nThese functions are useful when you're interested by the whole directory\nlisting, to use for golden tests or displaying to user.\n\nIf you don't need to print the directory tree, you can use `dirtree.List`, it\nreturns a slice of `dirtree.Entry` which you can examine programmaticaly.\n\nAll above functions accept a variable number (possibly none) of options.\nFor example:\n\n```go\ndirtree.Write(os.Stdout, \"dir\", dirtree.Depth(2), dirtree.ModeSize | dirtree.ModeCRC32)\n```\n\nIn the following examples the root directory has the following content:\n```\n.\n├── bar\n│   ├── dir1\n│   │   └── passwords\n│   └── dir2\n├── baz\n│   └── a\n│       └── b\n│           └── c\n│               └── nested\n├── foo\n│   ├── dir1\n│   └── dir2\n│       └── secrets\n├── other-stuff.mp3\n└── symlink -\u003e foo/dir2/secrets\n```\n\n\n### Default output (no options)\n\nCalling `dirtree.Write` without any option will show, as in:\n```go\ndirtree.Write(os.Stdout, \"dir\")\n```\nshows:\n```\nd            .\nd            bar\nd            bar/dir1\nf 0b         bar/dir1/passwords\nd            bar/dir2\nd            baz\nd            baz/a\nd            baz/a/b\nd            baz/a/b/c\nf 1407216b   baz/a/b/c/nested\nd            foo\nd            foo/dir1\nd            foo/dir2\nf 7922820b   foo/dir2/secrets\nf 39166b     other-stuff.mp3\n?            symlink\n```\n\n\n### `Type` option\n\nThe `dirtree.Type` option limits the files present in the listing based on their types.\nIt's a string that may contain one or more characters:\n  - `f` for regular files\n  - `d` for directories\n  - `?` for anything else (symlink, etc.)\n\nFor example, `dirtree.Type(\"f\")` will only show regular files while\n`dirtree.Type(\"fd\")` will both show regular files and directories.\n\nBy default, `dirtree` shows all types if the `Type` option is not provided.\n\n```go\ndirtree.Write(os.Stdout, \"dir\", dirtree.Type(\"f?\"))\n```\n\ndisplays:\n\n```\nf 0b         crc=00000000 bar/dir1/passwords\nf 1407216b   crc=733eee4d baz/a/b/c/nested\nf 7922820b   crc=fe02449a foo/dir2/secrets\nf 39166b     crc=d298754e other-stuff.mp3\n?            crc=n/a      symlink\n```\n\n\n\n### `PrintMode` option\n\nThe `dirtree.PrintMode` option is a bitset controlling the amount of information\nto show for each listed file.\n\n   - `dirtree.ModeType` prints 'd', 'f' or '?', depending on the file type,\n     directory, regular file or anything else.\n   - `dirtree.ModeSize` shows the file size in bytes, for regular files only.\n   - `dirtree.ModeCRC32` shows a CRC32 checksum, for regular files only.\n\n\n`dirtree.ModeDefault` combines `dirtree.ModeType` | `dirtree.ModeSize` and\n`dirtree.ModeAll` shows all information about all files:\n\n\n```go\ndirtree.Write(os.Stdout, \"dir\", dirtree.ModeAll)\n```\ndisplays:\n\n```\nd            crc=n/a      .\nd            crc=n/a      bar\nd            crc=n/a      bar/dir1\nf 0b         crc=00000000 bar/dir1/passwords\nd            crc=n/a      bar/dir2\nd            crc=n/a      baz\nd            crc=n/a      baz/a\nd            crc=n/a      baz/a/b\nd            crc=n/a      baz/a/b/c\nf 1407216b   crc=733eee4d baz/a/b/c/nested\nd            crc=n/a      foo\nd            crc=n/a      foo/dir1\nd            crc=n/a      foo/dir2\nf 7922820b   crc=fe02449a foo/dir2/secrets\nf 39166b     crc=d298754e other-stuff.mp3\n?            crc=n/a      symlink\n```\n\n### `Ignore` files\n\nThe `dirtree.Ignore` option allows to ignore files matching a pattern. The path\nrelative to the chosen root is matched against the pattern. Ignore follows the\nsyntax used and described with the `filepath.Match` function. Before checking if\nit matches a pattern, a path is first converted to its slash ('/') based\nversion, to ensure cross-platform consistency of the dirtree package.\n\n`dirtree.Ignore` can be provided multiple times to ignore multiple patterns. A\nfile is ignored from the listing as long as at it matches at least one\n`dirtree.Ignore` pattern. Also, `dirtree.Ignore` has precedence over\n`dirtree.Match`.\n\nThe pattern syntax is that of [filepath.Match](https://pkg.go.dev/path/filepath#Match):\n```\npattern:\n\t{ term }\nterm:\n\t'*'         matches any sequence of non-Separator characters\n\t'?'         matches any single non-Separator character\n\t'[' [ '^' ] { character-range } ']'\n\t            character class (must be non-empty)\n\tc           matches character c (c != '*', '?', '\\\\', '[')\n\t'\\\\' c      matches character c\n\ncharacter-range:\n\tc           matches character c (c != '\\\\', '-', ']')\n\t'\\\\' c      matches character c\n\tlo '-' hi   matches character c for lo \u003c= c \u003c= hi\n```\n\n```go\ndirtree.Write(os.Stdout, dir, dirtree.Ignore(\"*/dir1\"))\n```\nprints:\n```\nd            .\nd            bar\nf 0b         bar/dir1/passwords\nd            bar/dir2\nd            baz\nd            baz/a\nd            baz/a/b\nd            baz/a/b/c\nf 1407216b   baz/a/b/c/nested\nd            foo\nd            foo/dir2\nf 7922820b   foo/dir2/secrets\nf 39166b     other-stuff.mp3\n?            symlink\n```\n\n\n### `Match` to limit the listing to files matching a pattern\n\nThe `dirtree.Match` option limits the listing to files that match a pattern. The\npath relative to the chosen root is matched against the pattern. `dirtree.Match`\nfollows the syntax used and described with the `filepath.Match` function. Before\nchecking if it matches a pattern, a path is first converted to its slash ('/')\nbased version, to ensure cross-platform consistency of the dirtree package.\n\n`dirtree.Match` can be provided multiple times to match multiple patterns. A\nfile is included in the listing as long as at it matches at least one\n`dirtree.Match` pattern, unless it matches an `dirtree.Ignore` pattern (since\n`dirtree.Ignore` has precedence over `dirtree.Match`).\n\nThe pattern syntax is that of [filepath.Match](https://pkg.go.dev/path/filepath#Match).\n\n```go\ndirtree.Write(os.Stdout, dir, dirtree.Match(\"*/*[123]\"), dirtree.Match(\"*[123]\"))\n```\nprints:\n```\nd            bar/dir1\nd            bar/dir2\nd            foo/dir1\nd            foo/dir2\nf 39166b     other-stuff.mp3\n```\n\n\n### Directory `Depth`\n\nThe `dirtree.Depth` option is an integer that controls the maximum depth to\ndescend into, starting from the root directory. Everything below that depth\nwon't be shown.\n\n\n```go\ndirtree.Write(os.Stdout, dir, dirtree.Depth(1))\n```\nreports:\n```\nd            .\nd            bar\nd            baz\nd            foo\nf 39166b     other-stuff.mp3\n?            symlink\n```\n\n### `ExcludeRoot`\n\n`dirtree.ExcludeRoot` hides the root directory in the listing.\n```go\ndirtree.Write(os.Stdout, dir, dirtree.ExcludeRoot)\n```\n\n```\nd            bar\nd            bar/dir1\nf 0b         bar/dir1/passwords\nd            bar/dir2\nd            baz\nd            baz/a\nd            baz/a/b\nd            baz/a/b/c\nf 1407216b   baz/a/b/c/nested\nd            foo\nd            foo/dir1\nd            foo/dir2\nf 7922820b   foo/dir2/secrets\nf 39166b     other-stuff.mp3\n?            symlink\n```\n\n\n\n\n## TODO\n - streaming API (for large number of files)\n\nLicense\n-------\n\n- [MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farl%2Fdirtree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farl%2Fdirtree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farl%2Fdirtree/lists"}