Clean and Document aliases and functions

Updated aliases and functions, generated a README to document each

README.md

@@ -1,8 +1,119 @@
 # Shell Aliases and Functions
 
-A repo to keep these files portable
+This repository contains a collection of custom shell aliases and functions designed to enhance productivity and streamline common tasks in a Linux environment, particularly useful for homelab management. These configurations are intended to be sourced by your shell (e.g., Bash or Zsh) upon startup.
 
-I use a couple external programs without which some aliases or functions break:
+## External Dependencies
 
-* FZF - [fzf is a general-purpose command-line fuzzy finder.](https://github.com/junegunn/fzf)
-* LSD - [LS Deluxe](https://github.com/lsd-rs/lsd)
+Some aliases and functions rely on external programs. Ensure these are installed on your system for full functionality:
+
+- **FZF** - [fzf is a general-purpose command-line fuzzy finder.](https://github.com/junegunn/fzf)
+- **LSD** - [LS Deluxe](https://github.com/lsd-rs/lsd)
+- **`curl`**: Used by `weather` and `extip`.
+- **`mail` command**: Used by the `email` function. Requires a configured Mail Transfer Agent (MTA).
+- **`git`**: Essential for `testmerge` and `glog` aliases.
+- **`ip` command**: Used by `myip`. (Part of `iproute2`, usually pre-installed).
+- **`docker`**: Used by `docker_cleanup`.
+- **Archive Tools**: For the `extract` function, you'll need:
+  - `bzip2` (for `.bz2`, `.tar.bz2`)
+  - `unrar` (for `.rar`)
+  - `gzip` (for `.gz`, `.tgz`)
+  - `unzip` (for `.zip`)
+  - `p7zip-full` (for `.7z`, provides `7za`)
+  - `xz-utils` (for `.xz`, `.tar.xz`)
+  - `zstd` (for `.zst`, `.tar.zst`)
+  - `binutils` (for `.deb`, provides `ar`)
+  - `tar` (usually pre-installed)
+
+## Aliases
+
+### File Operations
+
+- `alias cp='cp -iv'` : Interactive, verbose copy. Prompts before overwriting.
+- `alias mv='mv -iv'` : Interactive, verbose move. Prompts before overwriting.
+- `alias rm='rm -iv'` : Interactive, verbose remove. Prompts before every removal.
+
+### Disk Usage
+
+- `alias df='df -h'` : Display disk space in human-readable format.
+- `alias du='du -h'` : Display disk usage in human-readable format.
+
+### Grep
+
+- `alias egrep='egrep --color=auto'` : `egrep` with automatic colorization.
+- `alias fgrep='fgrep --color=auto'` : `fgrep` with automatic colorization.
+
+### File Listing (LSD)
+
+- `alias ls='lsd '` : Uses `lsd` for enhanced directory listings.
+- `alias lla='ls -al'` : Long listing, showing hidden files (`.`, `..`).
+- `alias ll='ls -l'` : Long listing format.
+
+### General Utilities
+
+- `alias ping='ping -c 5'` : Pings a host 5 times and then stops.
+- `alias vi='vim'` : Uses `vim` instead of the default `vi` editor.
+- `alias less='less -r'` : `less` with raw control characters displayed.
+
+### Network Utilities
+
+- `alias extip='curl -s -4 icanhazip.com'` : Quickly get your external IPv4 address.
+
+### Process Management
+
+- `alias mempigs='ps aux | awk '\''{print $6/1024 " MB\t\t" $11 " " $12}'\'' | sort -n | tail -10'` : Lists the top 10 processes by memory usage (Resident Set Size).
+
+### Termpad Integration
+
+- `alias tph=' http https://termpad.planethawleywood.com'` : Send content to Termpad using `httpie`.
+- `alias tpc=' curl --data-binary @- https://termpad.planethawleywood.com'` : Send content to Termpad using `cURL`.
+
+### Git Shortcuts
+
+- `alias gs='git status'` : Show the working tree status.
+- `alias ga='git add .'` : Add all new and modified files in the current directory and subdirectories to the staging area.
+- `alias gc='git commit'` : Record changes to the repository.
+- `alias gp='git push'` : Update remote refs along with associated objects.
+- `alias gl='git pull'` : Fetch from and integrate with another repository or a local branch.
+- `alias glog="git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"` : Display a compact, colorful, and graphical Git log.
+
+### Navigation Shortcuts
+
+- `alias ..='cd ..'` : Change directory up one level.
+- `alias ...='cd ../..'` : Change directory up two levels.
+
+### History
+
+- `alias h='history'` : Display the shell command history.
+
+### Ansible
+
+- `alias apb='ansible-playbook'` : Shortcut for running `ansible-playbook` commands.
+
+## Functions
+
+### File Management Functions
+
+- `tardir <directory>`: Creates a timestamped gzipped tar archive of the specified directory. Useful for backups before deletion.
+- `dudir [directory]`: Lists disk usage (`du -hs`) for each item in the current or specified directory, correctly handling filenames with spaces.
+- `mkcd <directory_name>`: Creates a new directory and immediately changes into it.
+
+### System Utility Functions
+
+- `weather [location_code]`: Displays weather information for a specified location (or default `44113` if none provided) using `wttr.in`.
+- `psaux <pattern>`: A more robust replacement for `ps aux | grep <pattern>`, showing full process information without including the `grep` command itself.
+
+### Git Utility Functions
+
+- `testmerge <branch_to_merge>`: Performs a dry-run merge of a specified branch into the current branch, allowing inspection of changes (`git diff --cached`) before committing or aborting.
+
+### Network Utility Functions
+
+- `myip`: Displays your local IPv4 and IPv6 addresses.
+
+### Archive Management Functions
+
+- `extract <file>`: A universal extractor function that attempts to decompress and extract various archive types (e.g., `.tar.gz`, `.zip`, `.rar`, `.7z`, `.deb`, `.xz`, `.zst`).
+
+### Docker Utility Functions
+
+- `docker_cleanup`: Removes stopped Docker containers, dangling images, and unused volumes to free up disk space.