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.
🛡️ Intelligent disk space monitoring for write operations in Zsh
🚀 Quick Start
# Install
git clone https://github.com/TomfromBerlin/diskguard ~/.config/zsh/plugins/diskguard
echo "source ~/.config/zsh/plugins/zsh-disk-guard/diskguard.plugin.zsh" >> ~/.zshrc
source ~/.zshrcThis will only run the plugin temporarily. For permanent installation (also with the plugin manager or framework of your choice), see the 🛠️ Install section.
- ⚡ Smart Performance: Staged checking based on data size
- 🪂 Predictive: Checks if there's enough space before writing
- 🔧 Configurable: Adjust thresholds and behavior
- 🫥 Very Low Overhead: Minimal checks for small files
- 📦 Plugin Manager Ready: Works with oh-my-zsh, zinit, antigen, etc.
- 👣 Progress bar: Percentage and visual progress
- 💾 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
- ⏱️ Display of the total time required for the file operation(s)
- ✅ With: Predictive warnings, safe operations, peace of mind
- ❌ Without: Disk full errors mid-copy, wasted time, corrupted files
**Zsh 5.0+** (released 2012)
The 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:echo $ZSH_VERSIONUpgrade: See zsh.org
Standard Unix tools
- awk: scripting language for editing and analyzing texts
- cp: copy files from one place to another
- cut: remove sections from each line of files
- df: Checks and displays the free disk space. Only mounted partitions are checked
- du: Checks and displays the used disk space
- grep: print lines that match patterns
- lsb_release: print distribution specific information
- mv: rename SOURCE to DEST, or move SOURCE(s) to DIRECTORY
- rm: remove files or directories
- sed: stands for [S]tream [ED]itor and is a Unix tool used to edit text data streams
- sleep: pauses the executing process (essentially itself) for a specified time
- stat: Used here to determine the file system status instead of the file status
- touch: Unix command-line program for changing access and modification timestamps; we use it to create marker files
- tput: initialize a terminal or query terminfo database
If 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.
Since 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 <source> <dest>. 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.
← Click here to see two output examples with low disk space warning
# Automatically checked
cp large-file.iso /backup/
# ⚠️ Warning: Partition /backup is 85% full!
# Continue anyway? [y/N]
# Prevents write if not enough space
mv bigdata/ /mnt/small-disk/
# ❌ ERROR: Not enough disk space on /mnt/small-disk!
# Required: 5 GiB
# Available: 3 GiB
# Missing: 2048 MiB
# Smart: skips remote targets
rsync -av files/ user@remote:/backup/ # No local check
| 👁️🗨️ Note |
|---|
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 <source> <dest>. 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. |
The 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). |
← click here
Add to your .zshrc:
# (Do not use the following 15 lines along with other plugin managers!)
# <------------------------------------------------------------------------------------>
# ZSH UNPLUGGED start
#
# where do you want to store your plugins?
ZPLUGINDIR=$HOME/.config/zsh/plugins
#
# get zsh_unplugged and store it with your other plugins and source it
if [[ ! -d $ZPLUGINDIR/zsh_unplugged ]]; then
git clone --quiet https://github.com/mattmc3/zsh_unplugged $ZPLUGINDIR/zsh_unplugged
fi
source $ZPLUGINDIR/zsh_unplugged/zsh_unplugged.zsh
#
# extend fpath and load zsh-defer
fpath+=($ZPLUGINDIR/zsh-defer)
autoload -Uz zsh-defer
#
# make list of the Zsh plugins you use (Consider paying attention to the loading order)
repos=(
# ... your other plugins ...
TomfromBerlin/diskguard
)Insert the following code block before autoload -Uz promptinit && promptinit
# insert this block after all completion definitions (the zstyle ':completion [...] stuff)
# for zsh-autocomplete you'll need ZSH Version 5.4 (maybe 5.8) or higher
# read documentation of zsh-autocomplete
if [[ -f "${ZPLUGINDIR}/zsh-autocomplete/zsh-autocomplete.plugin.zsh" ]] ; then
source "${ZPLUGINDIR}/zsh-autocomplete/zsh-autocomplete.plugin.zsh"
else
# this will not work with zsh-autocomplete
# tweak compinit
alias compinit='compinit-tweak'
compinit-tweak() {
grep -q "ZPLUGINDIR/*/*" <<< "${@}" && \compinit "${@}"
}
autoload -Uz compinit && compinit -C -d ${zdumpfile}
fi
#now load plugins
plugin-load $repos
# ZSH UNPLUGGED end
💡 Best practice: place the second code block right before your prompt definitions and - as already mentioned - mandatory before autoload -Uz promptinit && promptinit.
Other pluginmanagers and frameworks:
add to your .zshrc:
antigen bundle TomfromBerlin/diskguardEnter the following command on the command line and confirm with Return
git clone https://github.com/TomfromBerlin/diskguard ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/diskguardthen add to your .zshrc:
plugins=(... diskguard)add to your .zshrc:
zinit light TomfromBerlin/diskguardYou can load the plugin with any other pluginmanagers as well.
git clone https://github.com/TomfromBerlin/diskguard ~/.config/zsh/plugins/diskguard
source ~/.config/zsh/plugins/zsh-disk-guard/diskguard.plugin.zsh← click here
Simply remove from your plugin list and restart Zsh.
zshdg disable
zshdg unload
rm -rf ~/.config/zsh/plugins/diskguard
The plugin performs a quick or deep disk check depending on the data size before write operations.
-
- Uses stat only (fast)
- Warns if disk >80% full
- No size calculation
-
- Calculates actual size with du
- Verifies available space
- Prevents failed operations
-
- Automatically skips checks for:
- Remote targets (rsync user@host:/path)
- Options ending with - (rsync -av files -n)
- Unclear syntax
- Automatically skips checks for:
| Scenario | Overhead | Check Type |
|---|---|---|
| cp small.txt /tmp | ~1ms | Usage only |
| cp file.iso /backup (5 GiB) | ~3ms | Full check |
| cp -r directory/ /tmp | Variable | Full check with du |
This 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.
← click here for more
# This settings can be changed at runtime. To do this, enter one or more of the
# following commands in the command line:
# set disk usage warning threshold to 90% (default value: 80%)
zshdg threshold 90
# set scan threshold for deep check to 500 MiB (default value: 100 MiB)
zshdg scan-threshold 500
# Enable debug output (default: off)
zshdg debug
# disable plugin (default: enable)
zshdg disable
# Run 'zshdg' to display more commands. Each command has several ways
# (long, medium, short) to invoke it.
# After changing a value with on of these commands you'll find a file
# named 'diskguard.conf' in the plugin directory.
# You can edit this file to change the settings, too.
# ──────────────────────────────────────────────────────────────────
# Do not play around with the following settings! I'm serious!
# commands to be wrapped, separated by spaces (default: "cp mv rsync")
export DISKGUARD_COMMANDS="cp mv rsync"
# However, if you want to change the default (not recommended!),
# further customization is required, i.e. you need to create suitable wrappers.
# See the diskguard_cp() function to see how this can be done.
# ──────────────────────────────────────────────────────────────────zshdg status # Shows current configurationzshdg disable # Temporarily disablezshdg enable # Re-enablezshdg color # switch between color mode and B/W modezshdg default # load default valueszshdg threshold N # set warn threshold in percent (N must be a number between 1 and 99)zshdg scan-theshold N # set scan threshold in MB (N must be a number > 1)Issues and PRs welcome at github.com/TomfromBerlin/zsh-disk-guard
License: MIT
Author: Tom (from Berlin)
