shell/docs/cleanup-alias-tracking.md

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

# 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:

   git push origin main
   

2. Regenerate the aliases on the system:

   # Run setup to regenerate aliases from template
   ~/shell/setup/setup.sh
   

3. Verify aliases work:

   # 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:

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