{"id":47402186,"url":"https://github.com/TomfromBerlin/diskguard","last_synced_at":"2026-04-03T17:00:53.402Z","repository":{"id":344008676,"uuid":"1180058137","full_name":"TomfromBerlin/diskguard","owner":"TomfromBerlin","description":"A ZSH plugin that warns you when you try to copy/move files and are running low on disk space","archived":false,"fork":false,"pushed_at":"2026-03-30T15:37:58.000Z","size":156,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T09:22:02.825Z","etag":null,"topics":["script","scripts","shell","shell-script","shell-scripting","shell-scripts","terminal","zsh","zsh-plugin"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/TomfromBerlin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2026-03-12T16:52:40.000Z","updated_at":"2026-03-30T15:37:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TomfromBerlin/diskguard","commit_stats":null,"previous_names":["tomfromberlin/diskguard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TomfromBerlin/diskguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomfromBerlin%2Fdiskguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomfromBerlin%2Fdiskguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomfromBerlin%2Fdiskguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomfromBerlin%2Fdiskguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TomfromBerlin","download_url":"https://codeload.github.com/TomfromBerlin/diskguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomfromBerlin%2Fdiskguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31364577,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T15:19:21.178Z","status":"ssl_error","status_checked_at":"2026-04-03T15:19:20.670Z","response_time":107,"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":["script","scripts","shell","shell-script","shell-scripting","shell-scripts","terminal","zsh","zsh-plugin"],"created_at":"2026-03-20T13:00:34.968Z","updated_at":"2026-04-03T17:00:53.389Z","avatar_url":"https://github.com/TomfromBerlin.png","language":"Shell","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Zsh%20Plugin-diskguard-blue?style=plastic\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/zsh%20version-%E2%89%A55.0-blue?style=plastic\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20BSD-lightgrey?style=plastic\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=plastic\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/TomfromBerlin/diskguard?style=plastic\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/downloads/TomfromBerlin/diskguard/total?style=plastic\u0026labelColor=grey\u0026color=blue\"\u003e\n  \u003c/p\u003e\n  \n_Memo to self: They'll clone this repository again and again and not leave a single comment. Yes, not even a tiny star. But at least my code is traveling around the world._\n\n# Disk🛡️Guard\n\n🛡️ Intelligent disk space monitoring for write operations in Zsh\n\n\u003cdetails\u003e\u003csummary\u003e 🚀 Quick Start\u003c/summary\u003e\n\n```zsh\n # Install\n git clone https://github.com/TomfromBerlin/diskguard ~/.config/zsh/plugins/diskguard\n echo \"source ~/.config/zsh/plugins/zsh-disk-guard/diskguard.plugin.zsh\" \u003e\u003e ~/.zshrc\n source ~/.zshrc\n```\nThis will only run the plugin temporarily. For permanent installation (also with the plugin manager or framework of your choice), see the 🛠️ Install section.\n\u003c/details\u003e\n\n## ✨ Features\n\n- ⚡ **Smart Performance**: Staged checking based on data size\n- 🪂 **Predictive**: Checks if there's enough space *before* writing\n- 🔧 **Configurable**: Adjust thresholds and behavior\n- 🫥 **Very Low Overhead**: Minimal checks for small files\n- 📦 **Plugin Manager Ready**: Works with oh-my-zsh, zinit, antigen, etc.\n- 👣 **Progress bar**: Percentage and visual progress\n- 💾 **Display of useful information**: total size of data to be processed, required and available storage space on the destination disk, file name and size of the file just processed\n- ⏱️ **Display of the total time** required for the file operation(s)\n\n## ❔ Why This Plugin?\n\n- ✅ With: Predictive warnings, safe operations, peace of mind\n- ❌ Without: Disk full errors mid-copy, wasted time, corrupted files\n\n## 📝 Requirements\n\n\u003cdetails\u003e\u003csummary\u003e**Zsh 5.0+** (released 2012)\u003c/summary\u003e\nThe version is checked when the plugin is loaded. If the version is too low, the plugin will not load. To manually check, run the following command at the command line:\n   \n  ```zsh\n  echo $ZSH_VERSION\n  ```\n  \nUpgrade: See [zsh.org](https://www.zsh.org/)\n \u003c/details\u003e\n \n\u003cdetails\u003e\u003csummary\u003eStandard Unix tools\u003c/summary\u003e\n\n- awk: scripting language for editing and analyzing texts\n- cp: copy files from one place to another\n- cut: remove sections from each line of files\n- df: Checks and displays the free disk space. Only mounted partitions are checked\n- du: Checks and displays the used disk space\n- grep: print lines that match patterns\n- lsb_release: print distribution specific information\n- mv: rename SOURCE to DEST, or move SOURCE(s) to DIRECTORY\n- rm: remove files or directories\n- sed: stands for [S]tream [ED]itor and is a Unix tool used to edit text data streams\n- sleep: pauses the executing process (essentially itself) for a specified time \n- stat: Used here to determine the file system status instead of the file status\n- touch: Unix command-line program for changing access and modification timestamps; we use it to create marker files\n- tput: initialize a terminal or query terminfo database\n\nIf one or more of these tools are unavailable, the plugin will display a message and will not load, but this should only happen under TempleOS and MicroSlop Windows.\n\n\u003c/details\u003e\n\n## 🖥️ Usage\n\nSince this is a plugin, manual execution is neither necessary nor useful. The plugin reacts to certain triggers and executes the corresponding actions automatically. Simply use `cp`, `mv`, and `rsync` as usual, e.g., `cp \u003csource\u003e \u003cdest\u003e`. No additional options should be specified. The plugin in action can be seen in the following clip. The plugin's status can be checked via the command line. See the 🎛️ Control section for more information.\n\n\u003cdetails\u003e\u003csummary\u003e ← Click here to see two output examples with low disk space warning\u003c/summary\u003e\n\n```zsh\n\n# Automatically checked\ncp large-file.iso /backup/\n# ⚠️  Warning: Partition /backup is 85% full!\n# Continue anyway? [y/N]\n\n# Prevents write if not enough space\nmv bigdata/ /mnt/small-disk/\n# ❌ ERROR: Not enough disk space on /mnt/small-disk!\n#    Required: 5 GiB\n#    Available: 3 GiB\n#    Missing: 2048 MiB\n\n# Smart: skips remote targets\nrsync -av files/ user@remote:/backup/  # No local check\n\n```\n\u003c/details\u003e\n\u003c!--\n[Zsh Disk Guard feat. a progress bar.webm](https://github.com/user-attachments/assets/2ae905e8-cadd-49eb-b5e1-1d3a0a6e21e9)\n--\u003e\n\n| 👁️‍🗨️ Note |\n|:-|\n| The plugin uses its own aliases for the **`cp`** and **`mv`** commands, so if you use this plugin and **`cp`** _and/or_ **`mv`** in other scripts, you should consider prefixing the commands in those scripts with `command`, e.g., `command cp \u003csource\u003e \u003cdest\u003e`. Existing aliases are ignored because the plugin calls these programs with the `command` prefix. That said, if you rely on your existing aliases, you should not consider using this plugin.\nThe functionality of the **`rsync`** program is barely affected. The plugin only checks whether the target is local or remote and whether **`rsync`** was called with options. If the target is remote or unclear, or if options are detected, all checks are skipped. If **`rsync`** is called without options and the destination is local but there is not enough disk space, a warning will be issued and a request will be made as to whether the file operation should be performed anyway. Apart from that, **`rsync`** is always called only with the user-specific options (if any), since it has its own output (e.g. its own progress bar). |\n\n## 🛠️ Install\n\u003cdetails\u003e\u003csummary\u003e ← click here\u003c/summary\u003e\n\nAdd to your `.zshrc`:\n\n### ZSH Unplugged (my recommendation)\n\n```zsh\n# (Do not use the following 15 lines along with other plugin managers!)\n# \u003c------------------------------------------------------------------------------------\u003e\n# ZSH UNPLUGGED start\n#\n# where do you want to store your plugins?\nZPLUGINDIR=$HOME/.config/zsh/plugins\n#\n# get zsh_unplugged and store it with your other plugins and source it\nif [[ ! -d $ZPLUGINDIR/zsh_unplugged ]]; then\n  git clone --quiet https://github.com/mattmc3/zsh_unplugged $ZPLUGINDIR/zsh_unplugged\nfi\nsource $ZPLUGINDIR/zsh_unplugged/zsh_unplugged.zsh\n#\n# extend fpath and load zsh-defer\nfpath+=($ZPLUGINDIR/zsh-defer)\nautoload -Uz zsh-defer\n#\n# make list of the Zsh plugins you use (Consider paying attention to the loading order)\nrepos=(\n  # ... your other plugins ...\n  TomfromBerlin/diskguard\n)\n```\n\nInsert the following code block before `autoload -Uz promptinit \u0026\u0026 promptinit`\n\n```\n# insert this block after all completion definitions (the zstyle ':completion [...] stuff)\n# for zsh-autocomplete you'll need ZSH Version 5.4 (maybe 5.8) or higher\n# read documentation of zsh-autocomplete\nif [[ -f \"${ZPLUGINDIR}/zsh-autocomplete/zsh-autocomplete.plugin.zsh\" ]] ; then\n    source \"${ZPLUGINDIR}/zsh-autocomplete/zsh-autocomplete.plugin.zsh\"\nelse\n    # this will not work with zsh-autocomplete\n    # tweak compinit\n    alias compinit='compinit-tweak'\n    compinit-tweak() {\n    grep -q \"ZPLUGINDIR/*/*\" \u003c\u003c\u003c \"${@}\" \u0026\u0026 \\compinit \"${@}\"\n    }\n    autoload -Uz compinit \u0026\u0026 compinit -C -d ${zdumpfile}\nfi\n#now load plugins\nplugin-load $repos\n# ZSH UNPLUGGED end\n```\n\n💡 Best practice: place the second code block right before your prompt definitions and - as already mentioned - mandatory before `autoload -Uz promptinit \u0026\u0026 promptinit`.\n\n\nOther pluginmanagers and frameworks:\n\n### Antigen\n\nadd to your .zshrc:\n\n```zsh\nantigen bundle TomfromBerlin/diskguard\n```\n\n### Oh-My-Zsh\n\nEnter the following command on the command line and confirm with Return\n\n```zsh\ngit clone https://github.com/TomfromBerlin/diskguard ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/diskguard\n```\n\nthen add to your .zshrc:\n\n```zsh\nplugins=(... diskguard)\n```\n\n### Zinit\n\nadd to your .zshrc:\n\n```zsh\nzinit light TomfromBerlin/diskguard\n```\n\nYou can load the plugin with any other pluginmanagers as well.\n\n⚠️ **Regardless which pluginmanager you use, the plugin may interfere with other plugins that monitor disk operations or use the wrapped commands (*cp*, *mv*, *rsync*). ⚠️**\n\n### manual call via the command line\n\n```zsh\ngit clone https://github.com/TomfromBerlin/diskguard ~/.config/zsh/plugins/diskguard\nsource ~/.config/zsh/plugins/zsh-disk-guard/diskguard.plugin.zsh\n```\n\n\u003c/details\u003e\n\n## 🧹 Uninstall\n\n\u003cdetails\u003e\u003csummary\u003e ← click here\u003c/summary\u003e\n\nSimply remove from your plugin list and restart Zsh.\n\n### 🚫 Temporary Disable\n\n```zsh\n\nzshdg disable\n\n```\n\n### ❌ To completely remove:\n\n```zsh\n\nzshdg unload\nrm -rf ~/.config/zsh/plugins/diskguard\n\n```\n\n\u003c/details\u003e\n\n## 🪄 How It Works\n\n### 📋 Two-Stage Checking\n\nThe plugin performs a quick or deep disk check depending on the data size before write operations.\n\n- #### ✅ Quick Check (files \u003c100 MiB):\n\n  - Uses stat only (fast)\n  - Warns if disk \u003e80% full\n  - No size calculation\n\n- #### ☑️ Deep Check (≥100 MiB or directories):\n\n  - Calculates actual size with du\n  - Verifies available space\n  - Prevents failed operations\n\n- #### 🧠 Smart Skipping\n  \n  - Automatically skips checks for:\n    - Remote targets (rsync user@host:/path)\n    - Options ending with - (rsync -av files -n)\n    - Unclear syntax\n\n### 👟 Performance\n\n|Scenario|Overhead|Check Type|\n|-|-|-|\n| cp small.txt /tmp | ~1ms | Usage only |\n| cp file.iso /backup (5 GiB) | ~3ms | Full check |\n| cp -r directory/ /tmp| Variable | Full check with du |\n\n## ⚙️ Configure\n\nThis plugin should be ready to use right out of the box and requires no further configuration. However, you can adjust some settings to suit your needs.\n\n\u003cdetails\u003e\u003csummary\u003e ← click here for more\u003c/summary\u003e\n\n```zsh\n# This settings can be changed at runtime. To do this, enter one or more of the\n# following commands in the command line:\n\n# set disk usage warning threshold to 90% (default value: 80%)\nzshdg threshold 90\n\n# set scan threshold for deep check to 500 MiB (default value: 100 MiB)\nzshdg scan-threshold 500\n\n# Enable debug output (default: off)\nzshdg debug \n\n# disable plugin (default: enable)\nzshdg disable\n\n# Run 'zshdg' to display more commands. Each command has several ways\n# (long, medium, short) to invoke it.\n\n# After changing a value with on of these commands you'll find a file\n# named 'diskguard.conf' in the plugin directory.\n# You can edit this file to change the settings, too.\n\n# ──────────────────────────────────────────────────────────────────\n# Do not play around with the following settings! I'm serious!\n\n# commands to be wrapped, separated by spaces (default: \"cp mv rsync\")\nexport DISKGUARD_COMMANDS=\"cp mv rsync\"\n\n# However, if you want to change the default (not recommended!),\n# further customization is required, i.e. you need to create suitable wrappers.\n# See the diskguard_cp() function to see how this can be done.\n# ──────────────────────────────────────────────────────────────────\n```\n\u003c/details\u003e\n\n# 🎛️ Control\n\n```zsh\nzshdg status    # Shows current configuration\n```\n\n```zsh\nzshdg disable   # Temporarily disable\n```\n\n```zsh\nzshdg enable    # Re-enable\n```\n\n```zsh\nzshdg color    # switch between color mode and B/W mode\n```\n\n```zsh\nzshdg default    # load default values\n```\n\n```zsh\nzshdg threshold N    # set warn threshold in percent (N must be a number between 1 and 99)\n```\n\n```zsh\nzshdg scan-theshold N    # set scan threshold in MB (N must be a number \u003e 1)\n```\n\n# 💬 Contribute\n\nIssues and PRs welcome at github.com/TomfromBerlin/zsh-disk-guard\n\nLicense: MIT\n\nAuthor: Tom (from Berlin)\n\n\n[![Star History Chart](https://api.star-history.com/image?repos=TomfromBerlin/diskguard\u0026type=date\u0026legend=top-left)](https://www.star-history.com/?repos=TomfromBerlin%2Fdiskguard\u0026type=date\u0026legend=top-left)\n","funding_links":[],"categories":["Plugins"],"sub_categories":["ZSH on Windows"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTomfromBerlin%2Fdiskguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTomfromBerlin%2Fdiskguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTomfromBerlin%2Fdiskguard/lists"}