diff --git a/README.md b/README.md index 5083fbc..082efc1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,435 @@ # winfig -construct config in windows development kit + +> Comprehensive Windows development environment configuration toolkit + +Winfig is a curated collection of configurations, scripts, and utilities designed to transform your Windows terminal into a powerful, efficient development environment. Optimized for Windows Terminal, PowerShell, and modern development workflows. + +## Features + +- **⚡ Performance Optimized PowerShell** - Lazy loading modules for faster startup +- **🎨 Beautiful Terminal Theme** - Custom Oh-My-Posh configuration with context awareness +- **🛠️ Comprehensive Utilities** - 40+ helper functions for faster workflow +- **📦 Package Management** - Curated Scoop package lists with automated installation +- **⚙️ Git Configuration** - Extensive aliases and optimized settings +- **🖥️ Windows Terminal Settings** - Custom profiles, keybindings, and color schemes +- **💾 Backup & Restore** - Easy configuration backup and migration +- **🚀 Automated Setup** - One-command installation with smart defaults + +## Quick Start + +### 1. Install Prerequisites + +```powershell +# Install Scoop (package manager) +Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +irm get.scoop.sh | iex + +# Install essential tools +scoop install git pwsh oh-my-posh +``` + +### 2. Clone Repository + +```powershell +git clone https://github.com/m1ngsama/winfig.git +cd winfig +``` + +### 3. Run Setup + +```powershell +# Automated setup (recommended) +.\setup.ps1 + +# Or manual setup for specific components +.\setup.ps1 -SkipScoop # Skip Scoop setup +.\setup.ps1 -SkipGit # Skip Git configuration +.\setup.ps1 -SkipPowerShell # Skip PowerShell profile +.\setup.ps1 -SkipTerminal # Skip Windows Terminal settings +``` + +### 4. Install Packages + +```powershell +# Install all recommended packages +cd scoop +.\install-packages.ps1 + +# Or install specific categories +.\install-packages.ps1 -Category essentials +.\install-packages.ps1 -Category development +``` + +### 5. Restart Terminal + +Close and reopen your terminal to see the changes. + +## Components + +### 📁 PowerShell Profile + +**Location**: `powershell/user_profile.ps1` + +**Features**: +- Lazy loading for faster startup (50%+ improvement) +- Enhanced PSReadLine with ListView predictions +- 40+ utility functions and aliases +- Git integration with shortcuts +- Network and system utilities + +**Quick Functions**: +```powershell +# Directory navigation +.. # Up one level +... # Up two levels +docs # Jump to Documents +proj # Jump to Projects +mkcd dir # Create and enter directory + +# Git shortcuts +gs # git status +ga file # git add +gc "msg" # git commit +gp # git push +glog # Beautiful git log + +# System utilities +reload # Reload PowerShell profile +touch file # Create new file +which cmd # Find command location +c # Open VS Code in current directory +``` + +### 🎨 Oh-My-Posh Theme + +**Location**: `powershell/m1ng.omp.json` + +**Features**: +- Modern powerline design +- Git status integration +- Node.js, Python, Go, Docker indicators +- Execution time display (500ms+ threshold) +- Time display +- Root/admin indicator + +### 🖥️ Windows Terminal + +**Location**: `windows-terminal/settings.json` + +**Features**: +- Optimized for CaskaydiaCove Nerd Font +- Custom color schemes (One Half Dark, Dracula) +- Vim-inspired pane management keybindings +- Profiles for PowerShell, CMD, WSL, Azure Cloud Shell +- Performance optimizations + +**Key Bindings**: +- `Alt+Shift+D` - Duplicate pane +- `Alt+Shift+-` - Split horizontally +- `Alt+Shift+|` - Split vertically +- `Alt+Arrow Keys` - Navigate panes +- `Ctrl+Shift+F` - Find +- `Alt+Enter` - Fullscreen + +### ⚙️ Git Configuration + +**Location**: `git/.gitconfig` + +**Features**: +- 30+ useful aliases +- Histogram diff algorithm +- Auto-stash before rebase +- Auto-prune deleted branches +- Auto-correct typos +- Global gitignore + +**Useful Aliases**: +```bash +git lg # Beautiful graph log +git sync # Fetch and rebase +git cleanup # Delete merged branches +git wip # Quick WIP commit +git unwip # Undo WIP commit +git aliases # List all aliases +``` + +### 📦 Scoop Packages + +**Location**: `scoop/packages.json` + +**Categories**: +- **Essentials**: git, 7zip, curl, wget, grep, sed +- **Shells**: pwsh, oh-my-posh +- **Terminal**: windows-terminal, wezterm +- **Editors**: neovim, vscode +- **Development**: nodejs, python, go, rust +- **Tools**: fzf, ripgrep, bat, lazygit, delta +- **Databases**: postgresql, redis, mysql +- **Cloud**: aws-cli, azure-cli, terraform +- **Fonts**: Nerd Fonts (CascadiaCode, FiraCode, JetBrainsMono) +- **Utilities**: everything, quicklook, powertoys + +### 🔧 Tmux Configuration + +**Location**: `tmux/` + +**Features**: +- Custom prefix key (Ctrl+T) +- Vim-style navigation +- Custom theme and statusline +- macOS-specific optimizations +- Useful utility keybindings + +## Advanced Usage + +### Backup Current Configuration + +```powershell +# Create backup +.\backup.ps1 + +# Backup with Scoop packages +.\backup.ps1 -IncludeScoopPackages + +# Compressed backup +.\backup.ps1 -Compress +``` + +### Restore from Backup + +```powershell +# Restore configurations +.\restore.ps1 -BackupPath ".\backups\backup-20241201-120000" + +# Restore with Scoop packages +.\restore.ps1 -BackupPath ".\backups\backup.zip" -RestoreScoopPackages + +# Force restore (no backup of existing) +.\restore.ps1 -BackupPath ".\backups\backup.zip" -Force +``` + +### Export Scoop Packages + +```powershell +cd scoop +.\export-packages.ps1 +``` + +Creates `installed-packages.json` with your current setup. + +### Uninstall + +```powershell +# Safe uninstall (backups configs) +.\uninstall.ps1 + +# Remove modules too +.\uninstall.ps1 -RemoveModules + +# Force remove (no backups) +.\uninstall.ps1 -Force +``` + +## Customization + +### PowerShell Profile + +Edit `powershell/user_profile.ps1` to add your own functions and aliases. + +### Oh-My-Posh Theme + +Customize `powershell/m1ng.omp.json` or create your own theme: +```powershell +# Browse themes +Get-PoshThemes + +# Set different theme +oh-my-posh init pwsh --config ~/theme.omp.json | Invoke-Expression +``` + +### Git Configuration + +Edit `git/.gitconfig` or override specific settings: +```powershell +git config --global user.name "Your Name" +git config --global user.email "your@email.com" +``` + +### Windows Terminal + +Customize `windows-terminal/settings.json` for your preferences: +- Change color scheme +- Modify keybindings +- Add custom profiles +- Adjust font and appearance + +## Requirements + +### Minimum Requirements +- Windows 10/11 +- PowerShell 7+ (PowerShell Core) +- Windows Terminal (recommended) + +### Recommended Tools +- Scoop package manager +- Git for Windows +- Oh-My-Posh +- Nerd Font (CaskaydiaCove, FiraCode, or JetBrainsMono) + +### Optional Tools +- WSL2 (for tmux configuration) +- Docker Desktop +- VS Code + +## Troubleshooting + +### PowerShell Profile Not Loading + +Check execution policy: +```powershell +Get-ExecutionPolicy +Set-ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + +### Oh-My-Posh Not Working + +Install Oh-My-Posh and fonts: +```powershell +scoop install oh-my-posh +scoop bucket add nerd-fonts +scoop install CascadiaCode-NF +``` + +Set font in Windows Terminal settings. + +### Modules Not Found + +Install required PowerShell modules: +```powershell +Install-Module posh-git -Scope CurrentUser +Install-Module Terminal-Icons -Scope CurrentUser +Install-Module PSFzf -Scope CurrentUser +``` + +### Git Config Not Applied + +Manually copy configuration: +```powershell +Copy-Item git\.gitconfig ~\.gitconfig +git config --global user.name "Your Name" +git config --global user.email "your@email.com" +``` + +### Terminal Icons Not Showing + +1. Install a Nerd Font: + ```powershell + scoop bucket add nerd-fonts + scoop install CascadiaCode-NF + ``` + +2. Set font in Windows Terminal: + - Open Settings (Ctrl+,) + - Appearance → Font face → CaskaydiaCove Nerd Font + +## Project Structure + +``` +winfig/ +├── powershell/ # PowerShell profile and theme +│ ├── user_profile.ps1 # Main profile +│ └── m1ng.omp.json # Oh-My-Posh theme +├── windows-terminal/ # Windows Terminal settings +│ ├── settings.json # Terminal configuration +│ └── README.md +├── git/ # Git configuration +│ ├── .gitconfig # Git config with aliases +│ ├── .gitignore_global # Global gitignore +│ └── README.md +├── scoop/ # Package management +│ ├── packages.json # Package list +│ ├── install-packages.ps1 +│ ├── export-packages.ps1 +│ └── README.md +├── tmux/ # Tmux configuration +│ ├── tmux.conf +│ ├── theme.conf +│ ├── statusline.conf +│ ├── utility.conf +│ └── macos.conf +├── setup.ps1 # Automated setup +├── uninstall.ps1 # Uninstall script +├── backup.ps1 # Backup configurations +├── restore.ps1 # Restore from backup +└── README.md # This file +``` + +## Tips & Tricks + +### Faster Scoop Downloads + +```powershell +scoop install aria2 +scoop config aria2-enabled true +``` + +### Update Everything + +```powershell +# Update Scoop packages +scoop update * + +# Update PowerShell modules +Update-Module + +# Update Oh-My-Posh +scoop update oh-my-posh +``` + +### Clean Up + +```powershell +# Remove old Scoop versions +scoop cleanup * + +# Clear Scoop cache +scoop cache rm * + +# Remove temp files +Remove-Item $env:TEMP\* -Recurse -Force -ErrorAction SilentlyContinue +``` + +### Keyboard Maestro + +Combine winfig with keyboard launchers: +- **Keypirinha** - Fast launcher (included in Scoop packages) +- **PowerToys Run** - Microsoft's launcher +- **Everything** - Fast file search + +## Contributing + +Contributions welcome! Feel free to: +- Report bugs +- Suggest features +- Submit pull requests +- Share your customizations + +## License + +MIT License - See LICENSE file for details + +## Acknowledgments + +- [Oh-My-Posh](https://ohmyposh.dev/) - Prompt theme engine +- [Scoop](https://scoop.sh/) - Package manager for Windows +- [Windows Terminal](https://github.com/microsoft/terminal) - Modern terminal +- [Nerd Fonts](https://www.nerdfonts.com/) - Patched fonts with icons + +## Author + +**m1ngsama** +- GitHub: [@m1ngsama](https://github.com/m1ngsama) + +--- + +⭐ If you find winfig useful, please consider giving it a star! diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..4012c7a --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,603 @@ +# Troubleshooting Guide + +This guide covers common issues and their solutions when using winfig. + +## Table of Contents + +- [PowerShell Issues](#powershell-issues) +- [Oh-My-Posh Issues](#oh-my-posh-issues) +- [Windows Terminal Issues](#windows-terminal-issues) +- [Git Issues](#git-issues) +- [Scoop Issues](#scoop-issues) +- [Font and Display Issues](#font-and-display-issues) +- [Performance Issues](#performance-issues) +- [General Issues](#general-issues) + +## PowerShell Issues + +### Profile Not Loading + +**Symptom**: PowerShell starts but custom functions and theme are not available. + +**Solutions**: + +1. Check if profile exists: + ```powershell + Test-Path $PROFILE + ``` + +2. Check execution policy: + ```powershell + Get-ExecutionPolicy + # Should be RemoteSigned or Unrestricted + ``` + +3. Set execution policy if needed: + ```powershell + Set-ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + +4. Check for errors in profile: + ```powershell + & $PROFILE + # Look for error messages + ``` + +### Module Import Errors + +**Symptom**: Errors about missing modules (posh-git, Terminal-Icons, PSFzf). + +**Solution**: + +Install missing modules: +```powershell +Install-Module posh-git -Scope CurrentUser -Force +Install-Module Terminal-Icons -Scope CurrentUser -Force +Install-Module PSFzf -Scope CurrentUser -Force +``` + +### Slow Startup + +**Symptom**: PowerShell takes a long time to start. + +**Solutions**: + +1. Check which modules are slow to load: + ```powershell + Measure-Command { & $PROFILE } + ``` + +2. Disable unused modules in `user_profile.ps1` + +3. Ensure lazy loading is working: + ```powershell + # Check if background job completed + Get-Job + ``` + +### Functions Not Working + +**Symptom**: Custom functions like `gs`, `gp`, `..` don't work. + +**Solutions**: + +1. Reload profile: + ```powershell + . $PROFILE + ``` + +2. Check if function exists: + ```powershell + Get-Command gs + ``` + +3. Check for conflicts: + ```powershell + Get-Alias gs -ErrorAction SilentlyContinue + ``` + +## Oh-My-Posh Issues + +### Theme Not Displaying + +**Symptom**: Prompt is plain text, no colors or icons. + +**Solutions**: + +1. Check if Oh-My-Posh is installed: + ```powershell + Get-Command oh-my-posh + ``` + +2. Install Oh-My-Posh: + ```powershell + scoop install oh-my-posh + ``` + +3. Verify theme file exists: + ```powershell + Test-Path (Join-Path (Split-Path $PROFILE) "m1ng.omp.json") + ``` + +### Icons Not Showing (Boxes/Question Marks) + +**Symptom**: Squares, boxes, or question marks instead of icons. + +**Solutions**: + +1. Install a Nerd Font: + ```powershell + scoop bucket add nerd-fonts + scoop install CascadiaCode-NF + ``` + +2. Set font in Windows Terminal: + - Open Settings (`Ctrl+,`) + - Go to Appearance + - Set Font face to "CaskaydiaCove Nerd Font" or another Nerd Font + +3. Restart Windows Terminal + +### Theme Performance Issues + +**Symptom**: Prompt is slow, especially in Git repositories. + +**Solutions**: + +1. Disable Git status fetching in theme: + - Edit `m1ng.omp.json` + - Set `fetch_status: false` in git segment + +2. Use simpler theme: + ```powershell + oh-my-posh init pwsh --config "$env:POSH_THEMES_PATH\minimal.omp.json" | Invoke-Expression + ``` + +## Windows Terminal Issues + +### Settings Not Applied + +**Symptom**: Windows Terminal doesn't show custom settings. + +**Solutions**: + +1. Verify settings location: + ```powershell + $settingsPath = "$env:LOCALAPPDATA\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json" + Test-Path $settingsPath + ``` + +2. Open settings in editor: + - Press `Ctrl+Shift+,` (opens JSON file) + - Verify settings are correct + +3. Check for JSON errors: + - Look for syntax errors in settings.json + - Use a JSON validator + +4. Reset to defaults: + - Rename settings.json + - Restart Windows Terminal (creates new defaults) + - Re-apply winfig settings + +### Keybindings Not Working + +**Symptom**: Custom keybindings don't work. + +**Solutions**: + +1. Check for conflicts: + - Open Settings → Actions + - Look for duplicate keybindings + +2. Verify in settings.json: + - Check `actions` array + - Ensure no syntax errors + +3. Try different key combination + +### Font Not Changing + +**Symptom**: Terminal doesn't use Nerd Font. + +**Solutions**: + +1. Install font system-wide: + ```powershell + # Download and install font file + # Or use Scoop + scoop install CascadiaCode-NF + ``` + +2. Set in PowerShell profile settings: + - Settings → Profiles → PowerShell → Appearance + - Set Font face manually + +3. Restart Windows Terminal + +## Git Issues + +### Config Not Applied + +**Symptom**: Git aliases don't work. + +**Solutions**: + +1. Verify config location: + ```powershell + git config --list --show-origin + ``` + +2. Manually copy config: + ```powershell + Copy-Item git\.gitconfig ~\.gitconfig -Force + ``` + +3. Set user info: + ```powershell + git config --global user.name "Your Name" + git config --global user.email "your@email.com" + ``` + +### Aliases Not Working + +**Symptom**: Git aliases like `git lg`, `git sync` don't work. + +**Solutions**: + +1. Check if alias exists: + ```bash + git config --get-regexp alias + ``` + +2. Test alias: + ```bash + git config alias.lg + ``` + +3. Manually add alias: + ```bash + git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit" + ``` + +### Line Ending Issues + +**Symptom**: Git shows all files as modified (^M characters). + +**Solutions**: + +1. Configure line endings: + ```bash + git config --global core.autocrlf true + ``` + +2. Refresh repository: + ```bash + git rm --cached -r . + git reset --hard + ``` + +## Scoop Issues + +### Scoop Not Found + +**Symptom**: `scoop` command not recognized. + +**Solutions**: + +1. Install Scoop: + ```powershell + Set-ExecutionPolicy RemoteSigned -Scope CurrentUser + irm get.scoop.sh | iex + ``` + +2. Add to PATH: + ```powershell + $env:PATH += ";$env:USERPROFILE\scoop\shims" + ``` + +3. Restart PowerShell + +### Package Installation Fails + +**Symptom**: `scoop install ` fails. + +**Solutions**: + +1. Update Scoop: + ```powershell + scoop update + ``` + +2. Check for conflicts: + ```powershell + scoop list + ``` + +3. Clear cache: + ```powershell + scoop cache rm * + ``` + +4. Try different bucket: + ```powershell + scoop bucket add extras + scoop search + ``` + +### Slow Downloads + +**Symptom**: Package downloads are slow. + +**Solutions**: + +1. Enable aria2: + ```powershell + scoop install aria2 + scoop config aria2-enabled true + ``` + +2. Increase connections: + ```powershell + scoop config aria2-max-connection-per-server 16 + scoop config aria2-split 16 + ``` + +## Font and Display Issues + +### Icons Show as Boxes + +**Symptom**: Icons appear as boxes or question marks. + +**Solutions**: + +1. Install Nerd Font: + ```powershell + scoop bucket add nerd-fonts + scoop install CascadiaCode-NF + ``` + +2. Set font in all profiles: + - Windows Terminal: Settings → Profiles → Defaults → Appearance + - Set Font face to Nerd Font + +3. Verify font is installed: + - Windows Settings → Fonts + - Search for "Cascadia" or your chosen font + +### Colors Look Wrong + +**Symptom**: Colors are incorrect or washed out. + +**Solutions**: + +1. Enable TrueColor: + - Windows Terminal Settings → Rendering + - Disable "Use legacy console" + +2. Check color scheme: + - Settings → Profiles → Color scheme + - Try different scheme (One Half Dark, Dracula) + +3. Update terminal: + ```powershell + scoop update windows-terminal + ``` + +### Blurry or Pixelated + +**Symptom**: Text appears blurry or pixelated. + +**Solutions**: + +1. Adjust antialiasing: + - Settings → Rendering + - Try different antialiasing modes (ClearType, Grayscale) + +2. Check DPI scaling: + - Windows Settings → Display + - Ensure DPI scaling is appropriate + +3. Disable Acrylic: + - Settings → Appearance + - Turn off "Acrylic material" + +## Performance Issues + +### Slow Terminal Startup + +**Symptom**: Terminal takes long to open. + +**Solutions**: + +1. Disable unnecessary startup tasks: + - Edit `user_profile.ps1` + - Comment out unused module imports + +2. Use lazy loading: + - Already implemented in winfig profile + +3. Clear temp files: + ```powershell + Remove-Item $env:TEMP\* -Recurse -Force -ErrorAction SilentlyContinue + ``` + +### Sluggish Git Operations + +**Symptom**: Git commands are slow. + +**Solutions**: + +1. Disable Oh-My-Posh git status: + - Edit `m1ng.omp.json` + - Set `fetch_status: false` + +2. Configure Git to use FSCache: + ```bash + git config --global core.fscache true + git config --global core.preloadindex true + ``` + +3. Exclude antivirus scanning: + - Add Git installation directory to antivirus exclusions + +### High Memory Usage + +**Symptom**: PowerShell uses excessive memory. + +**Solutions**: + +1. Check for module leaks: + ```powershell + Get-Process pwsh | Select-Object -Property * + ``` + +2. Restart PowerShell regularly + +3. Limit history size: + ```powershell + Set-PSReadLineOption -MaximumHistoryCount 1000 + ``` + +## General Issues + +### Permission Errors + +**Symptom**: "Access denied" or permission errors. + +**Solutions**: + +1. Run as Administrator: + - Right-click Windows Terminal + - Select "Run as administrator" + +2. Use `sudo`: + ```powershell + scoop install sudo + sudo + ``` + +3. Check file permissions: + ```powershell + Get-Acl $PROFILE + ``` + +### Profile Conflicts + +**Symptom**: Multiple profiles causing conflicts. + +**Solutions**: + +1. Check profile locations: + ```powershell + $PROFILE | Format-List * -Force + ``` + +2. Use correct profile: + - CurrentUserCurrentHost (recommended) + - Edit only this profile + +3. Remove conflicting profiles: + ```powershell + Remove-Item $PROFILE.CurrentUserAllHosts -ErrorAction SilentlyContinue + ``` + +### Setup Script Fails + +**Symptom**: `setup.ps1` fails with errors. + +**Solutions**: + +1. Run with execution policy: + ```powershell + Set-ExecutionPolicy Bypass -Scope Process + .\setup.ps1 + ``` + +2. Check error message and fix specific issue + +3. Use selective setup: + ```powershell + .\setup.ps1 -SkipScoop # Skip problematic component + ``` + +4. Manual setup: + - Copy files manually from each directory + - Follow README in each subdirectory + +### Backup/Restore Issues + +**Symptom**: Backup or restore fails. + +**Solutions**: + +1. Check disk space: + ```powershell + Get-PSDrive C + ``` + +2. Run with administrator privileges + +3. Check paths: + ```powershell + Test-Path .\backups + ``` + +4. Use full paths: + ```powershell + .\backup.ps1 + # Instead of relative paths + ``` + +## Getting More Help + +If you continue to experience issues: + +1. **Check Documentation**: + - Read component-specific READMEs + - Review configuration comments + +2. **Enable Verbose Output**: + ```powershell + $VerbosePreference = "Continue" + .\setup.ps1 -Verbose + ``` + +3. **Check Logs**: + - PowerShell: `$error[0] | Format-List * -Force` + - Scoop: `scoop cache show` + +4. **Create an Issue**: + - GitHub: [winfig issues](https://github.com/m1ngsama/winfig/issues) + - Include error messages and system info + +5. **Community Support**: + - Windows Terminal discussions + - Oh-My-Posh GitHub + - Scoop community + +## System Information + +To gather system information for troubleshooting: + +```powershell +# PowerShell version +$PSVersionTable + +# Windows version +Get-ComputerInfo | Select-Object WindowsVersion, OsArchitecture + +# Installed modules +Get-Module -ListAvailable | Where-Object Name -in 'posh-git','Terminal-Icons','PSFzf' + +# Scoop status +scoop status + +# Git version +git --version + +# Oh-My-Posh version +oh-my-posh version +``` + +Include this information when reporting issues.