{"id":30738842,"url":"https://github.com/andrearcaina/pathfinder","last_synced_at":"2026-02-16T20:26:49.847Z","repository":{"id":312289948,"uuid":"1038745787","full_name":"andrearcaina/pathfinder","owner":"andrearcaina","description":"blazingly fast, lightweight CLI to map \u0026 track your codebase","archived":false,"fork":false,"pushed_at":"2026-01-14T19:38:34.000Z","size":541,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T22:59:13.028Z","etag":null,"topics":["charm","cli","cloc","go","goreleaser"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/andrearcaina/pathfinder/pkg/pathfinder","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/andrearcaina.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T18:43:38.000Z","updated_at":"2026-01-14T19:38:38.000Z","dependencies_parsed_at":"2025-10-08T16:12:01.820Z","dependency_job_id":"041ccb90-6801-445c-8ffb-c609aeb3c884","html_url":"https://github.com/andrearcaina/pathfinder","commit_stats":null,"previous_names":["andrearcaina/pathfinder"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/andrearcaina/pathfinder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrearcaina%2Fpathfinder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrearcaina%2Fpathfinder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrearcaina%2Fpathfinder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrearcaina%2Fpathfinder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrearcaina","download_url":"https://codeload.github.com/andrearcaina/pathfinder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrearcaina%2Fpathfinder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["charm","cli","cloc","go","goreleaser"],"created_at":"2025-09-03T22:10:19.781Z","updated_at":"2026-02-16T20:26:49.818Z","avatar_url":"https://github.com/andrearcaina.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pathfinder\n[![Go Report Card](https://goreportcard.com/badge/github.com/andrearcaina/pathfinder)](https://goreportcard.com/report/github.com/andrearcaina/pathfinder)\n[![CI Status](https://github.com/andrearcaina/pathfinder/actions/workflows/pathfinder-ci.yml/badge.svg)](https://github.com/andrearcaina/pathfinder/actions/workflows/pathfinder-ci.yml)\n[![CD Status](https://github.com/andrearcaina/pathfinder/actions/workflows/pathfinder-cd.yml/badge.svg)](https://github.com/andrearcaina/pathfinder/actions/workflows/pathfinder-cd.yml)\n\nBlazingly fast, lightweight CLI to map \u0026 track your codebase.\n\n### Overview\n\n`pathfinder` is a command-line tool written in Go that scans a specified directory (and its subdirectories) to count the number of files, directories, and total lines of code.\n\nIt is designed to be fast and efficient, leveraging Go's concurrency features to process files in parallel.\n\nIt is also implemented as a Go package, so that you can use to integrate its functionality into your own Go applications/programs.\n\n### Installation\n`pathfinder` can be installed and used in two main ways:\n\n**As a CLI Tool**\n\nInstall via cURL on Linux, WSL, or Git Bash:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/andrearcaina/pathfinder/main/install.sh | sh\n```\n\nInstall via Powershell on Windows:\n```bash\nirm https://raw.githubusercontent.com/andrearcaina/pathfinder/main/install.ps1 | iex\n```\n\nOr via Go (requires Go 1.24.5 or later):\n```bash\ngo install github.com/andrearcaina/pathfinder@latest\n```\n\n**As a Package**\n\nInstall via Go (requires Go 1.24.5 or later):\n```bash\ngo get github.com/andrearcaina/pathfinder/pkg/pathfinder\n````\n\n### Documentation\nFor detailed documentation on how to use `pathfinder`, both as a CLI tool and as a Go library, please refer to the [docs](docs/) folder in the repository and check their respective files (`cli.md` and `api.md`). You can also check out the Godoc page [here](https://pkg.go.dev/github.com/andrearcaina/pathfinder/pkg/pathfinder). The architecture and designs is also documented in the `architecture.md` file and [designs](docs/designs) folder.\n\n### Go Example Usage using API\nHere's a simple example of how to use the `pathfinder` library in your Go code:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/andrearcaina/pathfinder/pkg/pathfinder\"\n)\n\nfunc main() {\n\t // default config (scans current directory and non-recursively)\n\treport, err := pathfinder.Scan(pathfinder.Config{})\n\tif err != nil {\n\t\tfmt.Printf(\"Failed to scan codebase: %v\", err)\n\t}\n\n\tfmt.Printf(\"Scanned %d files in %d directories with a total of %d lines\\n\",\n\t\treport.CodebaseMetrics.TotalFiles, \n\t\treport.CodebaseMetrics.TotalDirs, \n\t\treport.CodebaseMetrics.TotalLines,\n\t)\n}\n```\n\n### CLI Usage\nBelow I ran `pathfinder` on this codebase with the `-R` flag to recursively scan all subdirectories, as well as the `-d` flag to scan dependencies. Image was taken at 2025-12-08 7:25 PM EST.\n![example4.png](images/example4.png)\n\nThen I ran the same command, but instead on my installed Go libraries and packages in WSL to benchmark performance with the `-t` flag to enable throughput mode.\n\n```bash\n\u003e pathfinder scan -p ../../../go -R -d -t\n\n# throughput mode (as of 2025-12-10 12:51 PM EST)\n\nPathfinder • Throughput Mode\n\n[Worker 0] processed 2823 files in 3.01s (937.7 files/sec)\n[Worker 1] processed 2973 files in 3.01s (987.6 files/sec)\n[Worker 2] processed 2845 files in 3.01s (945.1 files/sec)\n[Worker 3] processed 2794 files in 3.01s (928.2 files/sec)\n[Worker 4] processed 2874 files in 3.01s (954.7 files/sec)\n[Worker 5] processed 2891 files in 3.03s (954.0 files/sec)\n[Worker 6] processed 2813 files in 3.03s (928.0 files/sec)\n[Worker 7] processed 2932 files in 3.01s (974.1 files/sec)\n[Worker 8] processed 2888 files in 3.01s (958.2 files/sec)\n[Worker 9] processed 2956 files in 3.01s (982.0 files/sec)\n[Worker 10] processed 2952 files in 3.01s (980.7 files/sec)\n[Worker 11] processed 2955 files in 3.01s (981.6 files/sec)\n[Worker 12] processed 2899 files in 3.01s (963.0 files/sec)\n[Worker 13] processed 2851 files in 3.01s (947.1 files/sec)\n[Worker 14] processed 2946 files in 3.01s (978.7 files/sec)\n[Worker 15] processed 2829 files in 3.01s (939.8 files/sec)\n\nTotal workers: 16\nTotal scanned files: 46,221\nTotal scanned dirs: 11,165\nTotal lines: 24,873,896\nTotal time taken: 3.03s\nOverall throughput: 15229.7 files/sec\n``` \n\nYou can see that it found **46,221** files, **11,165** directories, and **24,873,896** total lines (as of 2025-12-10 12:51 PM EST).\n\nSimilarly, I ran with the `time` command to compare time taken and CPU usage (without throughput mode):\n\n```bash\n\u003e time pathfinder scan -p ../../../go -R -d\n\n...\n\npathfinder scan -p ../../../go -R -d  3.17s user 4.77s system 251% cpu 3.154 total\n```\n\nThis only took 3.03-3.154 seconds (on my machine), utilizing 251% of the CPU. \nThis is because `pathfinder` uses goroutines for both concurrent file reading and line counting, and parallelizes work across multiple CPU cores.\n\nI then ran it again on the same directory:\n```bash\n\u003e pathfinder scan -p ../../../go -R -d -t\nPathfinder • Throughput Mode\n\n[Worker 0] processed 2741 files in 0.61s (4516.0 files/sec)\n[Worker 1] processed 2963 files in 0.61s (4892.2 files/sec)\n[Worker 2] processed 2800 files in 0.63s (4475.3 files/sec)\n[Worker 3] processed 2924 files in 0.61s (4820.4 files/sec)\n[Worker 4] processed 2903 files in 0.61s (4754.6 files/sec)\n[Worker 5] processed 2967 files in 0.62s (4808.5 files/sec)\n[Worker 6] processed 2722 files in 0.63s (4342.5 files/sec)\n[Worker 7] processed 3079 files in 0.61s (5083.9 files/sec)\n[Worker 8] processed 2881 files in 0.61s (4736.4 files/sec)\n[Worker 9] processed 3219 files in 0.62s (5206.3 files/sec)\n[Worker 10] processed 2708 files in 0.62s (4380.7 files/sec)\n[Worker 11] processed 2767 files in 0.61s (4525.5 files/sec)\n[Worker 12] processed 2610 files in 0.63s (4147.0 files/sec)\n[Worker 13] processed 2840 files in 0.61s (4668.4 files/sec)\n[Worker 14] processed 3009 files in 0.62s (4851.4 files/sec)\n[Worker 15] processed 3088 files in 0.62s (5010.2 files/sec)\n\nTotal workers: 16\nTotal scanned files: 46,221\nTotal scanned dirs: 11,165\nTotal lines: 24,873,896\nTotal time taken: 0.63s\nOverall throughput: 73029.2 files/sec\n\n# and\n\n\u003e time pathfinder scan -p ../../../go -R -d\n\n...\n\npathfinder scan -p ../../../go -R -d  2.71s user 1.63s system 634% cpu 0.684 total\n```\nThis time it took only 0.63-0.684 seconds to run, utilizing 634% of the CPU.\nThe second run is much faster because the OS caches file data in memory, \nreducing I/O overhead and allowing goroutines to utilize more cores efficiently.\n\nThe `pathfinder` CLI also has a flag that exports the codebase metric data as a JSON file. Check out [examples/json-exports/](examples/json-exports/) directory to see example JSON reports generated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrearcaina%2Fpathfinder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrearcaina%2Fpathfinder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrearcaina%2Fpathfinder/lists"}