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
Move your Neovim config to the canonical location:
shmkdir -p ~/.config mv ~/AppData/Local/nvim ~/.config/nvim # Only if you have config in the Windows path on macOS
Initialize the bare repo (if not already done):
shgit init --bare $HOME/dotfiles
Add the alias to your shell config:
shecho "alias gitbare='git --git-dir=\$HOME/dotfiles --work-tree=\$HOME'" >> ~/.zshrc source ~/.zshrc
Ignore the bare repo folder:
shecho "dotfiles" >> ~/.gitignore gitbare config --local core.excludesfile ~/.gitignore
Add and commit your config:
shgitbare 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
Clone the bare repo:
powershellgit clone --bare https://github.com/yourusername/dotfiles.git $HOME\dotfiles
Add the function to your PowerShell profile:
powershellcode $PROFILE # Add: function gitbare { git --git-dir=$HOME/dotfiles --work-tree=$HOME $args }
Ignore the bare repo folder:
powershellecho "dotfiles" >> $HOME\.gitignore gitbare config --local core.excludesfile $HOME\.gitignore
Pull your dotfiles:
powershellgitbare checkout
Remove the old Neovim config folder if it exists:
powershellRemove-Item "$HOME\AppData\Local\nvim" -Recurse -Force
Create a symlink from the Windows path to the canonical folder:
powershellNew-Item -ItemType SymbolicLink -Path "$HOME\AppData\Local\nvim" -Target "$HOME\.config\nvim"
The system cannot find the path specified
shNew-Item -ItemType SymbolicLink -Path "$HOME\AppData\Roaming\yazi\config" -Target "$HOME\.config\yazi"
The warning "The system cannot find the path specified" means that either the target or the parent directory of the link does not exist. Here are the most common issues to check:
Parent Directory Must Exist:
- The parent directory of the link (everything before the last
\
in-Path
) must already exist. PowerShell will not create intermediate directories.
- The parent directory of the link (everything before the last
Target Directory Must Exist:
- The target directory (
$HOME\.config\yazi
) must exist for a directory symlink.
- The target directory (
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
andgitbare 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 | Canonical Folder | macOS Path | Windows Path |
---|---|---|---|
Vim | ~/.vimrc | ~/.vimrc | ~/.vimrc |
Zsh | ~/.zshrc | ~/.zshrc | ~/.zshrc |
Git Config | ~/.gitconfig | ~/.gitconfig | ~/.gitconfig |
Neovim | ~/.config/nvim | ~/.config/nvim | ~/AppData/Local/nvim |
Neovim (alt) | ~/.config/nvim-from-scratch/ | ~/.config/nvim-from-scratch/ | ~/AppData/Local/nvim-from-scratch/ |
Yazi | ~/.config/yazi/ | ~/.config/yazi/ | ~/AppData/Roaming/yazi/config |
Typora Themes | ~/.config/typora-themes/ | ~/Library/Application Support/abnerworks.Typora/themes/ | ~/AppData/Roaming/Typora/themes/ |
Bash | ~/.bashrc | ~/.bashrc | ~/.bashrc or ~/.bash_profile |
VS Code User | ~/.config/vscode-user/ | ~/Library/Application Support/Code/User | ~/AppData/Roaming/Code/User |
PowerShell | ~/Documents/PowerShell | N/A | ~/Documents/PowerShell |
SSH Config | ~/.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.