Dotfiles Management with Bare Git Repo and Symlinks

This guide explains how to manage and share your configuration files (dotfiles) across Windows and macOS using a bare Git repository and symbolic links (symlinks).

1. Choose a Canonical Config Folder

Use ~/.config/nvim as the canonical Neovim config folder (tracked in your dotfiles repo).

2. Initial Setup on macOS

1. Move your Neovim config to the canonical location:

   mkdir -p ~/.config
   mv ~/AppData/Local/nvim ~/.config/nvim  # Only if you have config in the Windows path on macOS

2. Initialize the bare repo (if not already done):

   git init --bare $HOME/dotfiles

3. Add the alias to your shell config:

   echo "alias gitbare='git --git-dir=\$HOME/dotfiles --work-tree=\$HOME'" >> ~/.zshrc
   source ~/.zshrc

4. Ignore the bare repo folder:

   echo "dotfiles" >> ~/.gitignore
   gitbare config --local core.excludesfile ~/.gitignore

5. Add and commit your config:

   gitbare add .config/nvim
   gitbare commit -m "Add Neovim config"
   gitbare remote add origin https://github.com/yourusername/dotfiles.git
   gitbare branch -M main
   gitbare push -u origin main

3. Setup on Windows

1. Clone the bare repo:

   git clone --bare https://github.com/yourusername/dotfiles.git $HOME\dotfiles

2. Add the function to your PowerShell profile:

   code $PROFILE
   # Add:
   function gitbare {
     git --git-dir=$HOME/dotfiles --work-tree=$HOME $args
   }

3. Ignore the bare repo folder:

   echo "dotfiles" >> $HOME\.gitignore
   gitbare config --local core.excludesfile $HOME\.gitignore

4. Pull your dotfiles:

   gitbare checkout

5. Remove the old Neovim config folder if it exists:

   Remove-Item "$HOME\AppData\Local\nvim" -Recurse -Force

6. Create a symlink from the Windows path to the canonical folder:

   New-Item -ItemType SymbolicLink -Path "$HOME\AppData\Local\nvim" -Target "$HOME\.config\nvim"

4. Daily Usage

• Edit your Neovim config in ~/.config/nvim (macOS) or via the symlinked path on Windows.
• Use gitbare add, gitbare commit, gitbare push and gitbare pull to sync changes.

5. Notes

• Only ~/.config/nvim is tracked in your dotfiles repo.
• On Windows, ~/AppData/Local/nvim is just a symlink (pointer) to ~/.config/nvim.
• On macOS, Neovim reads from ~/.config/nvim directly.

6. Comparison Table: Common Config Paths in $HOME

Software	macOS Path	Windows Path
Neovim	~/.config/nvim	~/AppData/Local/nvim
Neovim	~/.config/nvim-from-scratch/	~/AppData/Local/nvim-from-scratch/
Yazi	~/.config/yazi/	~/AppData/Roaming/yazi/
Vim	~/.vimrc	~/vimfiles/_vimrc or ~/.vimrc
Zsh	~/.zshrc	~/.zshrc
Bash	~/.bashrc	~/.bashrc or ~/.bash_profile
Git Config	~/.gitconfig	~/.gitconfig
VS Code User	~/Library/Application Support/Code/User	~/AppData/Roaming/Code/User
PowerShell	N/A	~/Documents/PowerShell
SSH Config	~/.ssh/config	~/.ssh/config

Tip: For true cross-platform sharing, use symlinks to point platform-specific config paths to a single canonical folder tracked in your dotfiles repo.