Clean and Document aliases and functions

Updated aliases and functions, generated a README to document each

.shell_aliases

@@ -7,12 +7,11 @@ alias rm='rm -iv'
 alias df='df -h'
 alias du='du -h'
 
-# Greps
+# Greps should always be colorized
-alias egrep='egrep --color=auto'              # show differences in colour
+alias egrep='egrep --color=auto'
-alias fgrep='fgrep --color=auto'              # show differences in colour
+alias fgrep='fgrep --color=auto'
 
-# File Listing
+# File Listing with LSD (https://github.com/lsd-rs/lsd)
-# Must have lsd installed (https://github.com/lsd-rs/lsd)
 alias ls='lsd '
 alias lla='ls -al'	# ll with . and ..
 alias ll='ls -l'    # long list
@@ -28,32 +27,26 @@ alias extip='curl -s -4 icanhazip.com'
 # Memory Pigs (top 10)
 alias mempigs='ps aux | awk '\''{print $6/1024 " MB\t\t" $11 " " $12}'\''  | sort -n | tail -10'
 
-# dir -v (part of pushd/popd)
-alias dir='dir -v'
-
 # send things to termpad
   # with httpie
 alias tph=' http https://termpad.planethawleywood.com'
   # with cURL
 alias tpc=' curl --data-binary @- https://termpad.planethawleywood.com'
 
+# Git Aliases (very common and highly recommended)
+alias gs='git status'
+alias ga='git add .' # Adds all new and modified files in the current directory and subdirectories
+alias gc='git commit'
+alias gp='git push'
+alias gl='git pull'
+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"
 
-# Do lots of things with FZF
+# Navigation Shortcuts
+alias ..='cd ..'
+alias ...='cd ../..'
 
-# CD with the help of fzf
+# History
-alias cdf='cd ~ && cd "$(find . -type d -print0 | fzf --read0 --print0)"'
+alias h='history'
 
-# VIM
+# Ansible
-alias vimf='vim "`fzf`"'
+alias apb='ansible-playbook'
-
-# LESS
-alias lessf='less "`fzf`"'
-
-# CAT
-alias catf='cat "`fzf`"'
-
-# GLOW
-alias glowf='glow "`fzf`"'
-
-# VS Code on the Chromebook
-alias code='code --password-store="gnome-libsecret"'

.shell_functions

@@ -1,85 +1,5 @@
 # Shell Functions
 
-# Shell note pad for Bash
-noteb () {
-  local notes_file="$HOME/.notes"
-  local timestamp=$(date +"%F %T")
-  local input_line
-
-  if [[ $# -eq 0 ]]; then
-    # No arguments, display the notes file
-    tac "$notes_file"
-    return 0
-  elif [[ "$1" == "-a" ]]; then
-    # Add a note with prompting (using Bash's read -p)
-    read -r -p "$(date +"%F %T | ") " input_line
-    if [[ -n "$input_line" ]]; then
-      echo "$timestamp | $input_line" >> "$notes_file"
-      echo "Note added to $notes_file"
-      return 0
-    else
-      echo "No note entered."
-      return 1
-    fi
-  elif [[ "$1" == "-c" ]]; then
-    # Clear the notes file
-    read -r -p "Clear notes file? [Y/n] " clear_response
-    if [[ "$clear_response" =~ ^[Yy]$ ]]; then
-      > "$notes_file" # Truncate the file
-      echo "Notes file cleared."
-    else
-      echo "Notes file not cleared."
-    fi
-    return 0
-  else
-    # Treat arguments as the note (default action if not -a or -c)
-    input_line="$*"
-    echo "$timestamp | $input_line" >> "$notes_file"
-    echo "Note added to $notes_file"
-    return 0
-  fi
-}
-
-# Shell Note Pad for ZSH
-notez () {
-  local notes_file="$HOME/.notes"
-  local timestamp=$(date +"%F %T")
-  local input_line
-
-  if [[ $# -eq 0 ]]; then
-    # No arguments, display the notes file
-    tac "$notes_file"
-    return 0
-  elif [[ "$1" == "-a" ]]; then
-    # Add a note with prompting
-    read -r "?$(date +"%F %T | ") " input_line
-    if [[ -n "$input_line" ]]; then
-      echo "$timestamp | $input_line" >> "$notes_file"
-      echo "Note added to $notes_file"
-      return 0
-    else
-      echo "No note entered."
-      return 1
-    fi
-  elif [[ "$1" == "-c" ]]; then
-    # Clear the notes file
-    read -r "?Clear notes file? [Y/n] " clear_response
-    if [[ "$clear_response" =~ ^[Yy]$ ]]; then
-      > "$notes_file" # Truncate the file
-      echo "Notes file cleared."
-    else
-      echo "Notes file not cleared."
-    fi
-    return 0
-  else
-    # Treat arguments as the note (default action if not -a or -c)
-    input_line="$*"
-    echo "$timestamp | $input_line" >> "$notes_file"
-    echo "Note added to $notes_file"
-    return 0
-  fi
-}
-
 # tar/gzip a directory
 # I use this before 'rm -rf'ing a directory I think is useless
 # if nothing breaks after a predetermined amount of time, then the tar file is safe to delete
@@ -91,9 +11,10 @@ tardir() {
     fi
     #strip trailing slash
     target="${1%/}"
+    current_date=$(date +%Y-%m-%d)
     echo "Dir size: $(du -hs ${target})"
-    tar czf "${target}".tar.gz "${target}"
+    tar czf "${target}.${current_date}".tar.gz "${target}"
-    echo "Archive size: $(du -hs ${target}.tar.gz)"
+    echo "Archive size: $(du -hs ${target}.${current_date}.tar.gz)"
 }
 
 # Replacement for 'for i in $(ls); do du -hs $i; done' that handles spaces
@@ -131,7 +52,10 @@ psaux () { pgrep -f "$@" | xargs ps -fp 2>/dev/null; }
 
 # mail a file
 email() {
-if ! (($#)); then
+    if ! command -v mail &> /dev/null; then
+        echo "Error: 'mail' command not found. Please ensure a Mail Transfer Agent (MTA) is installed and configured."
+        return 1
+    elif ! (($#)); then
         echo "USAGE: email {filename} {email-address}"
         return 1
     else
@@ -143,9 +67,86 @@ fi
 
 # git testmerge
 testmerge() {
-    echo "git merge --no-commit --no-ff $1"
+    if [ -z "$1" ]; then
-    git merge --no-commit --no-ff $1
+        echo "Usage: testmerge <branch_to_merge>"
-    echo "git diff --cached"
+        echo "       (e.g., 'testmerge feature/my-new-feature')"
+        return 1
+    fi
+
+    echo "Attempting a dry-run merge of '$1' into the current branch..."
+    # Perform the merge without committing, and force a merge commit even if fast-forward is possible
+    git merge --no-commit --no-ff "$1"
+
+    # Check the exit status of the merge command
+    if [ $? -eq 0 ]; then
+        echo ""
+        echo "--- Proposed Changes (git diff --cached) ---"
         git diff --cached
-    echo "'git merge --abort' when done"
+        echo "--------------------------------------------"
+        echo ""
+        echo "Merge state is now active. You can inspect the changes above."
+        echo "To finalize the merge, run: 'git commit'"
+        echo "To abort the merge and return to the previous state, run: 'git merge --abort'"
+    else
+        echo ""
+        echo "Merge encountered issues (e.g., conflicts). Please resolve them manually."
+        echo "To abort the merge and return to the previous state, run: 'git merge --abort'"
+    fi
+}
+
+# Quickly display local IP addresses
+myip() {
+    echo "IPv4 Addresses:"
+    ip -4 addr show | grep -oP '(?<=inet\s)\d+(\.\d+){3}' | grep -v '127.0.0.1'
+    echo ""
+    echo "IPv6 Addresses:"
+    ip -6 addr show | grep -oP '(?<=inet6\s)[0-9a-fA-F:]+' | grep -v '::1'
+}
+
+# Universal archive extractor
+extract() {
+    if [ -z "$1" ]; then
+        echo "Usage: extract <file>"
+        return 1
+    fi
+
+    if [ -f "$1" ]; then
+        case "$1" in
+            *.tar.bz2)   tar xvjf "$1"    ;;
+            *.tar.gz)    tar xvzf "$1"    ;;
+            *.bz2)       bunzip2 "$1"     ;;
+            *.rar)       unrar x "$1"     ;;
+            *.gz)        gunzip "$1"      ;;
+            *.tar)       tar xvf "$1"     ;;
+            *.tbz2)      tar xvjf "$1"    ;;
+            *.tgz)       tar xvzf "$1"    ;;
+            *.zip)       unzip "$1"       ;;
+            *.Z)         uncompress "$1"  ;;
+            *.7z)        7za x "$1"       ;;
+            *.deb)       ar x "$1"        ;;
+            *.tar.xz)    tar xvJf "$1"    ;;
+            *.tar.zst)   tar --use-compress-program=zstd -xvf "$1" ;;
+            *.xz)        unxz "$1"        ;;
+            *.zst)       zstd -d "$1"     ;;
+            *)           echo "'$1' cannot be extracted via extract()" ;;
+        esac
+    else
+        echo "'$1' is not a valid file"
+    fi
+}
+
+# Make a directory and change into it
+mkcd() {
+    mkdir -p "$1" && cd "$1"
+}
+
+# Docker cleanup: remove stopped containers, dangling images, and unused volumes
+docker_cleanup() {
+    echo "Removing stopped containers..."
+    docker rm $(docker ps -aq) 2>/dev/null || echo "No stopped containers to remove."
+    echo "Removing dangling images..."
+    docker rmi $(docker images -f "dangling=true" -q) 2>/dev/null || echo "No dangling images to remove."
+    echo "Removing unused volumes..."
+    docker volume rm $(docker volume ls -f "dangling=true" -q) 2>/dev/null || echo "No unused volumes to remove."
+    echo "Docker cleanup complete."
 }

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)
+Some aliases and functions rely on external programs. Ensure these are installed on your system for full functionality:
-* LSD - [LS Deluxe](https://github.com/lsd-rs/lsd)
+
+- **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.