Dotfiles - Cross-Platform Shell Configuration

A comprehensive, modular dotfiles repository for managing shell configurations, scripts, and development environment setup across macOS and Linux systems. Built with GNU Stow for easy deployment and maximum portability.

Cross-Platform First: All configurations are designed to work seamlessly on both macOS and Linux systems.

---

📋 Table of Contents

• Features
• Technology Stack
• Quick Start
• Project Structure
• Package Management
• Configuration
• Development Tools
• Testing
• Contributing
• License

---

✨ Features

• 🔄 Cross-Platform Compatibility: Seamless operation on macOS and Linux (Debian-based distributions)
• 📦 Modular Package System: GNU Stow-based deployment for clean, organized configurations
• 🎨 Modern Terminal Experience: Enhanced with fzf, eza, bat, delta, and Oh My Posh
• 🐍 Python Environment Management: Integrated pyenv for version management
• 🔒 Security-First: 1Password CLI integration for secrets management
• ⚡ Performance Optimized: Cached completions and lazy loading for fast shell startup
• 🛠️ Developer-Friendly: Comprehensive tooling for network engineering and development
• 📝 Well-Documented: Extensive inline documentation and GitHub Copilot instructions

---

---

🚀 Technology Stack

Core Technologies

• Shell: Zsh 5.9+ (primary), Bash (scripts)
• Package Managers: Homebrew (macOS), apt/dnf (Linux)
• Deployment: GNU Stow for symlink management
• Plugin Manager: Zinit for Zsh plugins
• Prompt: Oh My Posh with custom themes

Terminal Enhancements

Tool	Purpose	Version
fzf	Fuzzy finder	Latest
eza	Modern ls replacement	Latest
bat	Cat with syntax highlighting	Latest
fd	Fast find alternative	Latest
delta	Enhanced git diff viewer	Latest
yazi	Terminal file manager	Nightly

Development Tools

• Editor: Neovim with custom configuration
• Python: pyenv for version management
• Docker: OrbStack integration (macOS)
• Security: 1Password CLI for secrets management
• Network: Containerlab for network automation
• Version Control: Git with delta integration

---

🚀 Quick Start

Prerequisites

• Git
• Sudo/admin access
• Internet connection

One-Line Installation

git clone https://git.as73.inetsix.net/inetsix-configs/dotfiles.git ~/dotfiles && cd ~/dotfiles && bash scripts/install.sh

Step-by-Step Installation

# Clone repository
git clone https://git.as73.inetsix.net/inetsix-configs/dotfiles.git

# Go to downloaded files
cd dotfiles

# Launch install script to provision tools and deploy dotfiles
bash scripts/install.sh

The install script will automatically:

• Install required packages for your OS (macOS/Linux) from external files
• Sync the repository with latest changes
• Deploy all package-* directories using stow
• Configure zsh as default shell
• Setup FZF integration with key bindings

Installation Options

# Preview changes without applying them
bash scripts/install.sh --dry-run

# Force reinstall with automatic backup
bash scripts/install.sh --force

# Skip package installation, only deploy dotfiles
bash scripts/install.sh --skip-packages

# Get help and see all options
bash scripts/install.sh --help

Manual deployment of dotfiles

If you prefer to deploy packages manually:

# Base dotfiles
stow package-base

# ZSH related dotfiles
stow package-zsh

# Neovim related dotfiles
stow package-nvim

# SSH related dotfiles
stow package-ssh

If you need to change installation path, you can use:

stow --dir=~/dotfiles --target=~/

Deploy all packages at once

# Deploy all package-* directories automatically
for pkg in package-*; do
    echo "Deploying $pkg..."
    stow "$pkg"
done

---

📁 Project Structure

dotfiles/
├── .github/
│   ├── copilot-instructions.md    # GitHub Copilot configuration
│   └── prompts/                   # Reusable Copilot prompts
├── package-base/                  # Core configuration files
├── package-zsh/                   # ZSH shell configuration
│   ├── .zshrc                     # Main Zsh configuration
│   └── .zsh/                      # Modular Zsh configs
│       ├── zsh_options.zsh        # Shell options & keybindings
│       ├── zsh_completion.zsh     # Completion settings
│       └── zsh_functions.zsh      # Custom functions
├── package-nvim/                  # Neovim configuration
├── package-ssh/                   # SSH configuration
├── aliases.d/                     # Modular Zsh aliases
│   ├── basics.zsh                 # Core system aliases
│   ├── git.zsh                    # Git aliases
│   ├── docker.zsh                 # Docker & containers
│   ├── python.zsh                 # Python environment
│   ├── networks.zsh               # Network tools
│   └── arista.zsh                 # Arista-specific tools
├── bin/                           # Custom scripts & utilities
├── scripts/                       # Installation & maintenance
│   ├── install.sh                 # Main installation script
│   └── dotfiles-sync              # Repository sync utility
├── homebrew-packages/             # Homebrew Brewfile
├── linux-packages/                # Linux package lists
└── iterm2-themes/                 # Terminal color schemes

Package System

All dotfiles packages follow the naming convention package-*:

• package-base: Core configuration files
• package-zsh: ZSH shell configuration
• package-nvim: Neovim configuration with Python IDE setup (docs/neovim-python-ide.md)
• package-ssh: SSH configuration

---

📦 Package Management

macOS Packages

Packages are managed via Homebrew using homebrew-packages/Brewfile. This includes all CLI tools, applications, fonts, and VS Code extensions.

Linux Packages

Packages are listed in linux-packages/packages.txt and installed via apt. Additional packages (eza, fd, yazi) are installed from external sources when not available in standard repositories:

• Eza: Installed from community repository with GPG verification
• Fd: Installed as fd-find from apt with symlink creation
• Yazi: Installed from official GitHub releases (nightly build)

---

⚙️ Configuration

Zsh Configuration Order

The .zshrc loads components in this specific order (critical for proper operation):

1. Path setup (before any tools)
2. Homebrew initialization (macOS)
3. pyenv initialization (after Homebrew, before Oh My Posh)
4. Oh My Posh (prompt)
5. Zinit (plugin manager)
6. Zinit plugins (syntax highlighting, completions, autosuggestions)
7. compinit (completion initialization with caching)
8. Custom configurations (aliases, functions, options)
9. Tool integrations (fzf, direnv, OrbStack)

FZF Integration

FZF is automatically configured with enhanced key bindings and preview options:

FZF Keybindings

Keystroke	Description
CTRL-T	Fuzzy find all files and subdirectories with preview
ALT-C	Fuzzy find all subdirectories with tree preview and cd into selection
CTRL-R	Fuzzy find through your shell history

FZF Configuration:

• Border and inline info display
• File preview using bat or cat
• Directory preview using eza or tree
• Reverse layout for better visibility
• Custom trigger sequence (// instead of **)

---

🛠️ Included Development Tools

---

🛠️ Included Development Tools

Command-Line Utilities

• Delta - Enhanced git diff display with syntax highlighting
• Eza - Modern ls replacement with icons and git integration
• Yazi - Blazing fast terminal file manager (nightly build)
• Bat - Cat clone with syntax highlighting
• Fd - Fast and user-friendly alternative to find
• Fzf - Command-line fuzzy finder
• Neovim - Hyperextensible Vim-based text editor

Development Environment

• Python: pyenv for managing multiple Python versions
• Docker: OrbStack integration for container management
• Network: Containerlab for network lab automation
• Security: 1Password CLI for secure credential management
• Git: Enhanced with delta for better diff visualization

---

🧪 Testing

Test the configuration in a containerized environment:

# Build Docker image
docker build -t titom73/dotfiles .

# Run container interactively
docker run -it --rm titom73/dotfiles

# Test specific features
docker run -it --rm titom73/dotfiles zsh -c "fzf --version"

---

🤝 Contributing

Contributions are welcome! This repository follows specific coding standards and conventions.

Coding Standards

All code must adhere to the standards defined in .github/copilot-instructions.md:

• Cross-Platform Compatibility: All changes MUST work on both macOS and Linux
• Shell Scripts: Use #!/bin/bash for bash scripts, check tool existence before use
• Zsh Configuration: Follow the critical configuration loading order
• Aliases: Always use conditional aliases with tool existence checks
• Error Handling: Include proper error messages and exit codes
• Documentation: Comment WHY, not WHAT; document workarounds

Before Contributing

1. Test changes on both macOS and Linux when possible
2. Run shellcheck on any modified scripts: shellcheck script.sh
3. Ensure no syntax errors: bash -n script.sh
4. Test zsh configuration reload: source ~/.zshrc
5. Follow conventional commit message format

Commit Message Format

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, refactor, chore, style

Example:

feat(zsh): add pyenv configuration with Homebrew support
fix(aliases): resolve command existence check for eza
docs(readme): update installation instructions

---

📝 License

APACHE 2.0

---

🙏 Acknowledgments

• Inspired by countless dotfiles repositories in the community
• Built with best practices from GitHub awesome-copilot
• Terminal enhancements powered by the Rust ecosystem

---

📚 Additional Resources

• GNU Stow Documentation
• Zsh Documentation
• Oh My Posh Documentation
• Zinit Wiki
• GitHub Copilot Instructions

---

Made with ❤️ for developers who love their terminal