{"id":28325257,"url":"https://github.com/shravanasati/atomic","last_synced_at":"2025-07-23T09:33:08.107Z","repository":{"id":64304378,"uuid":"378085101","full_name":"shravanasati/atomic","owner":"shravanasati","description":"A simple CLI tool to benchmark your programs easily.","archived":false,"fork":false,"pushed_at":"2024-06-29T09:36:07.000Z","size":3350,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-23T12:43:35.890Z","etag":null,"topics":["benchmarking","cli","golang","hacktoberfest"],"latest_commit_sha":null,"homepage":"","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/shravanasati.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2021-06-18T08:30:15.000Z","updated_at":"2024-11-22T19:14:56.000Z","dependencies_parsed_at":"2023-01-15T10:15:15.093Z","dependency_job_id":"8de5896e-eae3-4065-b9c5-f03f6e929c02","html_url":"https://github.com/shravanasati/atomic","commit_stats":{"total_commits":83,"total_committers":1,"mean_commits":83.0,"dds":0.0,"last_synced_commit":"1e14e86b2d59c78e7eed1bd38dac82ec34992d3c"},"previous_names":["shravan-1908/atomic","shravanasati/atomic","shravan-1908/bench"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/shravanasati/atomic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Fatomic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Fatomic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Fatomic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Fatomic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shravanasati","download_url":"https://codeload.github.com/shravanasati/atomic/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shravanasati%2Fatomic/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266655186,"owners_count":23963551,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"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":["benchmarking","cli","golang","hacktoberfest"],"created_at":"2025-05-25T20:12:22.051Z","updated_at":"2025-07-23T09:33:08.092Z","avatar_url":"https://github.com/shravanasati.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# atomic\n\n[![Continuous integration](https://github.com/shravanasati/atomic/actions/workflows/integrate.yml/badge.svg)](https://github.com/shravanasati/atomic/actions/workflows/integrate.yml)\n\n![atomic demo](assets/demo.gif)\n\n\n*atomic* is a simple CLI tool for making benchmarking easy.\n\n\n\u003cbr\u003e\n\n## ✨ Features\n\n- Detailed benchmark summary at the end\n- Export the results in markdown, json, csv format\n- Statistical Outlier Detection\n- Plot the benchmarking data, comparing the different commands\n- Arbitrary command support \n- Constant feedback about the benchmark progress and current estimates.\n- Warmup runs can be executed before the actual benchmark.\n- Cache-clearing commands can be set up before each timing run.\n\n\u003cbr\u003e\n\n## ⚡️ Installation\n\n\n### Installation Scripts\n\n#### Linux and macOS\n\n```bash\ncurl https://raw.githubusercontent.com/shravanasati/atomic/master/scripts/install.sh | bash\n```\n\n### Package Managers\n\n#### Windows\n```powershell\nscoop install https://github.com/shravanasati/atomic/raw/master/scripts/atomic.json\n```\n\n### GitHub Releases\n\natomic binaries for all operating systems are available on the [GitHub Releases](https://github.com/shravanasati/atomic/releases/latest) tab. You can download them manually and place them on `PATH` in order to use them.\n\nTo simplify this process, you can use [eget](https://github.com/zyedidia/eget):\n```\neget shravanasati/atomic\n```\n\n### Using Go compiler\n\nIf you've Go compiler (v1.21 or above) installed on your system, you can install atomic via the following command. \n\n```\ngo install github.com/shravanasati/atomic@latest\n```\n\n\n### Build from source\n\nYou can alternatively build atomic from source via the following commands (again, requires go1.21 or above):\n\n```\ngit clone https://github.com/shravanasati/atomic.git\ncd ./atomic\ngo build\n```\n\nIf you want to build atomic in release mode (stripped binaries, compressed distribution and cross compilation), execute the following command. You can also control the release builds behavior using the [`release.config.json`](./scripts/release.config.json) file.\n\n```\npython ./scripts/build.py\n```\n\n\u003cbr\u003e\n\nTo verify the installation of *atomic*, open a new shell and execute `atomic -v`. You should see output like this:\n```\natomic 0.4.0\n\nVersion: 0.4.0\n```\nIf the output isn't something like this, you need to repeat the above steps carefully.\n\n\n\u003cbr\u003e\n\n## 💡 Usage\n\n\n### Simple benchmarks\n\nLet's benchmark our first CLI command using atomic.\n\n```\natomic \"grep -iFr 'type'\"\n```\n\nThis grep command searches the codebase for the plain text 'type', recursively and case sensitively.\n\nNotice how atomic automatically determines the number of runs to perform in the benchmark. atomic will run any given command atleast 10 times and for atleast 3 seconds, when determining the number of runs on its own.\n\nYou can alter this behavior using the `--min/-m X` and `--max/-M Y` flags. When the `--min/-m X` flag is passed, atomic will run the command atleast X number of times. If the `--max/-M Y` flag is passed, atomic will perform maximum Y number of runs.\n\n```\natomic \"grep -iFr 'type'\" -m 50 -M 200\n```\n\nBoth these flags are independent of each other, you can use any one of those at a time.\n\nYou can pass the exact number of runs to perform using the `--runs/-r N` flag.\n\n```\natomic \"grep -iFr 'type'\" --runs 50\n```\n\n### Warmup runs and preparation \u0026 cleanup commands\n\nYou might get a warning that says atomic found statistical outliers in the benchmark, which generally happens due to missing filesystem caches (especially for IO heavy programs like grep) and/or interferences from other running programs (OS context switches).\n\nYou can use the `--warmup/-w N` flag to ask atomic to run the command N number of times before beginning the actual benchmark.\n\n```\natomic \"grep -iFr 'type'\" --runs 50 --warmup 10\n```\n\natomic raises the statistical outlier warning even if one of the data point (execution time in this case) is an outlier. You can raise this threshold using the `--outlier-threshold P` flag where P is the minimum percentage of outliers that should be present in the benchmark data for atomic to raise the warning. \n\nA command you are running may require some additional setup before every time it is executed, or need to remove some assets it has generated after the execution. You can use the `--prepare/-p command` and `--cleanup/-c command` flags respectively to achieve above tasks.\n\n```\natomic \"go build\" --prepare \"go generate ./...\" --cleanup \"rm *.exe\"\n```\n\n### Intermediate shells\n\n\u003e This feature is under development.\n\nLet's look at another command to benchmark.\n\n```\natomic ls\n```\n\nThis command might give the error on Windows, because `ls` is not a executable but a shell function, provided by powershell, unlike Unix systems.\n\nIn such cases, use the `--shell/-s` flag to ask atomic to run the command within a shell context.\natomic will use `cmd.exe` on Windows and `/bin/sh` on Unix-based systems by default. \nYou can choose a custom shell too using the `--shell-path path` flag. Since `ls` is not provided by `cmd.exe` either, we'll use powershell.\n\n```\natomic ls -s --shell-path powershell\n```\n\natomic will perform shell calibration (substracting shell spawn time from total process execution time) but it's far from perfect (even working state) and may yield negative runtimes. \n\n### Timeouts \u0026 Debugging failed benchmarks\n\natomic also offers a `--timeout/-t D` flag, which tells atomic to cancel the benchmark if any of the run of given commands takes longer than D, where D is the time duration which can expressed as following: `number{ns|us|ms|s|m|h}`.\n\n```\natomic \"grep -iFr 'type'\" --timeout 100ms\n```\n\nSometimes the command you've given might finish with non-zero exit code, which generally indicates that it failed to execute successfully.\n\nIn such cases, atomic will stop the benchmark immediately. \n\nYou can alter this behaviour with the `--ignore-error/-I` flag, which will make atomic continue the benchmark even if commands return non-zero exit codes.\n\nUse this flag cautiously, advisably only when you know why the command is behaving that way and whether it is desired.\n\nA good example is Go compiler when called with zero arguments:\n\n```\natomic go\n```\n\nThis will fail - to investigate what's wrong you can use the `--verbose/-V` flag to show the output of the command. \n\nTurns out, the Go compiler just renders the help text with an exit status of 2, which causes the benchmark to fail. It's safe to use the `--ignore-error/-I` flag now.\n\nOn another note, use the `--verbose/-V` flag sparingly (writing to stdout is expensive).\n\n### Comparing several commands\n\natomic accepts multiple commands to benchmark, and then also displays relative summary at the end, comparing those commands.\n\nLet's use atomic to compare [scc](https://github.com/boyter/scc) and [tokei](https://github.com/XAMPPRocky/tokei), two popular code counting tools.\n\n```\natomic scc tokei -w 20\n```\n\nAll the flags you provide to atomic will be applied for all the commands.\nIn this example, 20 warmup runs will be executed for both scc and tokei.\n\n\n\n### Exports and plots\n\natomic can export the benchmarking data in JSON, markdown, CSV and text formats.\n\nUse the `--export/-e formats` flag where `formats` is the comma-separated list of supported export formats.\n\n```\natomic 'grep -iFr \"type\"' --export json,csv,md\n```\n\natomic will create three files named `atomic-summary.{ext}` with the benchmark data.\n\nThe default name for exports is `atomic-summary` but can be modified using the `--filename/-f name` flag. \n\nThe default time unit for exports is `ms` (milliseconds) but can be modified using the `--time-unit/-u unit` flag. Valid values for time units are {ns, us, ms, s, m, h}.\n\n```\natomic 'grep -iFr \"type\"' -e json,csv,md -f grep_data -u s\n```\n\nJSON export has the most amount of data, since it also contains a key named `times` which is an array of all run-times. This JSON output also matches with that of [hyperfine](https://github.com/sharkdp/hyperfine)'s, so you can utilize the Python scripts in the hyperfine repository that visualize the benchmark data (and vice versa with the upcoming `plot` command). \n\nYou can also plot this data using the `--plot T` flag, where `T` is the comma-separated list of chart formats. Valid values for T include {hist, histogram, bar, **all**}. If all is used as `T`, atomic will plot the data with all chart types.\n\n```\natomic 'ag pattern' 'rg pattern' --plot all\n```\n\n\u003e The plot feature is also under development.\n\n\u003cbr\u003e\n\n## Acknowledgement\n\nThis tool is heavily inspired by [*hyperfine*](https://github.com/sharkdp/hyperfine). I learnt a lot of stuff looking at the code of this project and tried matching the feature-set as close as possible.\n\n## Known Issues and Missing Features\n\n- [ ] Shell calibration yields negative process run times\n- [ ] No Color functionality is broken\n- [ ] Implementation of errorbar, boxplot and bubble chart is pending\n- [ ] Plot command is missing\n\n## 🔖 Versioning\n*atomic* releases follow semantic versioning, every release is in the *x.y.z* form, where:\n- *x* is the MAJOR version and is incremented when a backwards incompatible change to atomic is made.\n- *y* is the MINOR version and is incremented when a backwards compatible change to atomic is made, like changing dependencies or adding a new function, method, struct field, or type.\n- *z* is the PATCH version and is incremented after making minor changes that don't affect atomic's public API or dependencies, like fixing a bug.\n\n\u003cbr\u003e\n\n## 📄 License\nLicense\n© 2021-Present Shravan Asati\n\nThis repository is licensed under the MIT license. See [LICENSE](LICENSE) for details.\n\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshravanasati%2Fatomic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshravanasati%2Fatomic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshravanasati%2Fatomic/lists"}