{"id":16306762,"url":"https://github.com/oalders/debounce","last_synced_at":"2026-02-22T09:43:08.916Z","repository":{"id":256862791,"uuid":"836519566","full_name":"oalders/debounce","owner":"oalders","description":" Limit the rate at which a command can fire","archived":false,"fork":false,"pushed_at":"2025-11-24T18:34:43.000Z","size":251,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-28T06:54:41.890Z","etag":null,"topics":["cli","shell"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oalders.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-APACHE","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},"funding":{"github":["oalders"]}},"created_at":"2024-08-01T02:59:25.000Z","updated_at":"2025-11-24T18:34:40.000Z","dependencies_parsed_at":"2024-10-28T14:28:45.804Z","dependency_job_id":"fa6affe0-9c19-41bd-889d-474b2800d692","html_url":"https://github.com/oalders/debounce","commit_stats":null,"previous_names":["oalders/debounce"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/oalders/debounce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oalders%2Fdebounce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oalders%2Fdebounce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oalders%2Fdebounce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oalders%2Fdebounce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oalders","download_url":"https://codeload.github.com/oalders/debounce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oalders%2Fdebounce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29708363,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T05:59:28.568Z","status":"ssl_error","status_checked_at":"2026-02-22T05:58:46.208Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["cli","shell"],"created_at":"2024-10-10T21:11:34.080Z","updated_at":"2026-02-22T09:43:08.893Z","avatar_url":"https://github.com/oalders.png","language":"Go","funding_links":["https://github.com/sponsors/oalders"],"categories":[],"sub_categories":[],"readme":"# debounce\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n  - [Go Install](#go-install)\n  - [Using Ubi](#using-ubi)\n  - [Download a Release](#download-a-release)\n- [Examples](#examples)\n  - [A command without arguments](#a-command-without-arguments)\n  - [A command with arguments](#a-command-with-arguments)\n  - [Using Shell Variables](#using-shell-variables)\n  - [More Complex Commands](#more-complex-commands)\n- [Available Flags](#available-flags)\n  - [--cache-dir](#--cache-dir)\n  - [--local](#--local)\n    - [Example Usage](#example-usage)\n  - [--status](#--status)\n    - [Resetting the Cache](#resetting-the-cache)\n  - [--version](#--version)\n  - [--help](#--help)\n- [Caveats](#caveats)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n## Introduction\n\n`debounce` is a simple utility to limit the rate at which a command can fire.\nI've written a blog post on\n[the motivation behind this tool](https://www.olafalders.com/2025/02/25/debounce-all-of-the-things/).\n\nThe command format is:\n\n```bash\ndebounce \u003cinteger\u003e \u003cunit\u003e \u003ccommand\u003e\n```\n\nAvailable units are:\n\n- seconds (s)\n- minutes (m)\n- hours (h)\n- days (d)\n\nThe following are equivalent:\n\n```bash\ndebounce 1 s some-command\ndebounce 1 second some-command\ndebounce 1 seconds some-command\n```\n\n```bash\ndebounce 1 m some-command\ndebounce 1 minute some-command\ndebounce 1 minutes some-command\n```\n\n```bash\ndebounce 1 h some-command\ndebounce 1 hour some-command\ndebounce 1 hours some-command\n```\n\n```bash\ndebounce 1 d some-command\ndebounce 1 day some-command\ndebounce 1 days some-command\n```\n\nNote that `day` is shorthand for `24 hours`. Daylight Saving Time is not taken\ninto account.\n\n## Installation\n\nChoose from the following options to install `debounce`.\n\n### Go Install\n\n```bash\ngo install github.com/oalders/debounce@latest\n```\n\nor for a specific version:\n\n```bash\ngo install github.com/oalders/debounce@v0.5.2\n```\n\n### Using Ubi\n\nYou can use [ubi](https://github.com/houseabsolute/ubi) to install `debounce`.\n\n```bash\n#!/usr/bin/env bash\n\nset -eux -o pipefail\n\n# Choose a directory in your $PATH\ndir=\"$HOME/local/bin\"\n\nif [ ! \"$(command -v ubi)\" ]; then\n    curl --silent --location \\\n        https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh |\n        TARGET=$dir sh\nfi\n\nubi --project oalders/debounce --in \"$dir\"\n```\n\n### Download a Release\n\nYou can download the latest release directly from\n[here](https://github.com/oalders/debounce/releases).\n\n## Examples\n\n### A command without arguments\n\nThis runs the command without any parameters but prevents repeated execution\nwithin the set time window.\n\n```bash\n$ debounce 2 seconds date\nMon Aug  5 23:09:09 EDT 2024\n$ debounce 2 seconds date\n🚥 will not run date more than once every 2 seconds\n```\n\n### A command with arguments\n\nThis example uses [ubi](https://github.com/houseabsolute/ubi) to install\n[is](https://github.com/oalders/is) into the current directory. The command\nwon't be executed more than once every 8 hours.\n\n```bash\n$ debounce 8 hours ubi --verbose --project oalders/is --in .\n[ubi::installer][INFO] Installed binary into ./is\n$ debounce 8 hours ubi --verbose --project oalders/is --in .\n🚥 will not run \"ubi --verbose --project oalders/is --in .\" more than once every 8 hours\n```\n\n### Using Shell Variables\n\nRemember to single quote variables which shouldn't be expanded until the command\nis run.\n\n```bash\ndebounce 10 s zsh -c 'echo $PWD'\n```\n\n### More Complex Commands\n\nYou can use `\u0026\u0026` and `||` in your commands. You'll want to quote your command to\nensure that the entire command is passed to `debounce`.\n\n```bash\ndebounce 2 s bash -c 'sleep 2 \u0026\u0026 date'\n```\n\n## Available Flags\n\nIt's important to add `debounce` flags before other command arguments to avoid\nconfusion between `debounce` flags and flags meant for your command.\n\nGood: ✅\n\n```shell\ndebounce --debug 90 s curl https://www.olafalders.com\n```\n\nBad: 💥\n\n```shell\n$ debounce 90 s curl https://www.prettygoodping.com --debug\n🚀 Running command: curl https://www.prettygoodping.com --debug\ncurl: option --debug: is unknown\n```\n\nYou could be explicit about this by using `--` as a visual indicator that flag\nparsing has ended.\n\n```shell\ndebounce --debug 90 s -- curl https://www.prettygoodping.com\n```\n\n### --cache-dir\n\nSpecify an alternate cache directory to use. The directory must already exist.\n\n```bash\ndebounce --cache-dir /tmp 30 s date\n```\n\n### --local\n\nThe `--local` flag modifies the behavior of `debounce` by including the full\npath to the current working directory in the cache key. This ensures that the\ncache is specific to the directory from which the command is run.\n\nBy default, `debounce` works globally. It generates a cache key based on the\ncommand and its arguments. This means that if you run the same command from\ndifferent directories, `debounce` will treat them as the same command and use\nthe same cache file. This can be useful if you want to limit the execution of a\ncommand globally, regardless of the directory.\n\nWith the `--local` flag, `debounce` includes the full path to the current\nworking directory in the cache key. This means that the cache is specific to the\ndirectory from which the command is run. If you run the same command from\ndifferent directories, `debounce` will treat them as different commands and use\nseparate cache files. This is useful if you want to limit the execution of a\ncommand on a per-directory basis.\n\n#### Example Usage\n\n```shell\n# Run a command without the --local flag\ndebounce 10 s echo \"Hello, World!\"\n# Run the same command again within 10 seconds\ndebounce 10 s echo \"Hello, World!\"\n# Output: 🚥 will not run \"echo Hello, World!\" more than once every 10 seconds\n\n# Run a command with the --local flag\ndebounce --local 10 s echo \"Hello, Local World!\"\n# Run the same command again within 10 seconds from the same directory\ndebounce --local 10 s echo \"Hello, Local World!\"\n# Output: 🚥 will not run \"echo Hello, Local World!\" more than once every 10 seconds\n\n# Run the same command from a different directory\ncd /another/directory\ndebounce --local 10 s echo \"Hello, Local World!\"\n# Output: Hello, Local World!\n```\n\n### --status\n\nPrint debounce status information for a command.\n\n```bash\ndebounce --status 30 s date\n📁 cache location: /Users/olaf/.cache/debounce/0e87632cd46bd4907c516317eb6d81fe0f921a23c7643018f21292894b470681\n🚧 cache last modified: Thu, 19 Sep 2024 08:28:20 EDT\n⏲️ debounce interval: 00:00:30\n🕰️ cache age: 00:00:12\n⏳ time remaining: 00:00:17\n```\n\n#### Resetting the Cache\n\nSince the cache is just a file, you can `rm` the cache location file whenever\nyou'd like to start fresh.\n\n```shell\nrm /Users/olaf/.cache/debounce/0e87632cd46bd4907c516317eb6d81fe0f921a23c7643018f21292894b470681\n```\n\n### --version\n\nPrints current version.\n\n```bash\ndebounce --version\n0.5.2\n```\n\n### --help\n\nDisplays usage instructions.\n\n```text\ndebounce --help\nUsage: debounce \u003cquantity\u003e \u003cunit\u003e \u003ccommand\u003e ... [flags]\n\nlimit the rate at which a command can fire\n\nArguments:\n  \u003cquantity\u003e       Quantity of time\n  \u003cunit\u003e           s,second,seconds,m,minute,minutes,h,hour,hours,d,day,days\n  \u003ccommand\u003e ...    Command to run\n\nFlags:\n  -h, --help                Show context-sensitive help.\n      --debug               Print debugging info to screen\n      --version             Print version to screen\n      --status              Print cache information for a command without running it\n      --local               Localize debounce to current working directory\n      --cache-dir=STRING    Override the default cache directory\n```\n\n## Caveats\n\nUnder the hood, `debounce` creates or updates a cache file to track when a\ncommand was run successfully. This means that, under the right conditions, it's\nentirely possible to kick off two long-running tasks in parallel without\n`debounce` knowing about it.\n\nAdditionally, if a command fails, the cache file will not be created or updated.\n\nI've created this tool in a way that meets my needs. I will consider pull\nrequests for additional functionality to address issues like these. Please get\nin touch with me first to discuss your feature if you'd like to add something.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foalders%2Fdebounce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foalders%2Fdebounce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foalders%2Fdebounce/lists"}