Commit local changes before merging with remote

docs/cleanup-alias-tracking.md

@@ -0,0 +1,148 @@
+# Alias File Tracking Cleanup
+
+## Overview
+
+The `cleanup-alias-tracking.sh` script is designed to clean up the git repository on systems where `dotfiles/my-aliases.zsh` was previously tracked but should now be treated as a dynamically generated file.
+
+## Problem Context
+
+Originally, `my-aliases.zsh` was tracked in git, but this caused conflicts when the bootstrap process tried to update it with system-specific aliases. The file is now:
+
+- **Generated dynamically** from `my-aliases.zsh.original` template
+- **Customized per system** (debian vs ubuntu vs fedora)
+- **Should not be tracked** in git to prevent conflicts
+
+## What This Script Does
+
+1. **Removes git tracking** of `dotfiles/my-aliases.zsh`
+2. **Updates .gitignore** to ignore the file
+3. **Commits the changes** with a descriptive message
+4. **Verifies the cleanup** was successful
+5. **Provides next steps** for pushing and regenerating aliases
+
+## Usage
+
+### On Each System You Manage
+
+```bash
+# Navigate to your shell repository
+cd ~/shell
+
+# Run the cleanup script
+./cleanup-alias-tracking.sh
+```
+
+### What You'll See
+
+The script will:
+- Show current git status
+- Check if the file is currently tracked
+- Check if .gitignore already has the entry
+- Ask for confirmation before making changes
+- Perform the cleanup
+- Verify the results
+
+### Example Output
+
+```
+=== Alias File Tracking Cleanup Script ===
+This script will remove my-aliases.zsh from git tracking
+and update .gitignore to prevent future conflicts.
+
+=== Current Git Status ===
+M  dotfiles/my-aliases.zsh
+
+my-aliases.zsh is currently tracked by git
+.gitignore needs to be updated
+
+Actions that will be performed:
+  1. Remove dotfiles/my-aliases.zsh from git tracking
+  2. Add dotfiles/my-aliases.zsh to .gitignore
+  3. Commit the changes
+
+Continue? (y/N): y
+
+=== Removing my-aliases.zsh from git tracking ===
+✓ Removed dotfiles/my-aliases.zsh from git tracking
+
+=== Updating .gitignore ===
+✓ Added new Generated dotfiles section to .gitignore
+
+=== Committing changes ===
+✓ Changes committed successfully
+
+=== Verification ===
+✓ dotfiles/my-aliases.zsh is no longer tracked
+✓ .gitignore contains entry for dotfiles/my-aliases.zsh
+
+=== Final Git Status ===
+(clean working directory)
+
+=== Cleanup Complete! ===
+```
+
+## After Running the Script
+
+1. **Push the changes** to your repository:
+   ```bash
+   git push origin main
+   ```
+
+2. **Regenerate the aliases** on the system:
+   ```bash
+   # Run setup to regenerate aliases from template
+   ~/shell/setup/setup.sh
+   ```
+
+3. **Verify aliases work**:
+   ```bash
+   # Source your shell config or start a new terminal
+   source ~/.zshrc
+
+   # Test aliases
+   ll  # Should work if aliases were generated correctly
+   ```
+
+## Safety Features
+
+- **Confirmation prompt** before making any changes
+- **Git status checks** to show what will be affected
+- **Verification steps** to ensure cleanup was successful
+- **No data loss** - the script only removes tracking, not the actual file
+- **Idempotent** - safe to run multiple times
+
+## Troubleshooting
+
+### Script Says "No changes needed"
+
+This means the cleanup was already done on this system. You can verify by checking:
+```bash
+git ls-files | grep my-aliases.zsh  # Should return nothing
+grep "my-aliases.zsh" .gitignore    # Should show the ignore entry
+```
+
+### File Still Shows as Modified
+
+If `my-aliases.zsh` still shows as modified after cleanup:
+1. This is normal - the file exists locally but is now ignored
+2. Delete the local file: `rm dotfiles/my-aliases.zsh`
+3. Run setup to regenerate: `~/shell/setup/setup.sh`
+
+### Merge Conflicts on Other Systems
+
+If you get merge conflicts when pulling:
+1. Run this cleanup script first
+2. Then pull the latest changes
+3. The conflicts should be resolved automatically
+
+## Files Modified
+
+- **dotfiles/my-aliases.zsh** - Removed from git tracking
+- **.gitignore** - Added ignore entry with explanatory comment
+- **Git history** - One commit documenting the change
+
+## Related Files
+
+- **dotfiles/my-aliases.zsh.original** - Template file (remains tracked)
+- **setup/setup.sh** - Script that generates aliases from template
+- **~/.oh-my-zsh/custom/aliases.zsh** - Final generated aliases location