Personal shell, Git, editor, and terminal settings for Ubuntu on WSL 2. Native Ubuntu uses the same Linux setup. macOS and other Linux distributions are untested.
Run these commands in Ubuntu as your regular user. On WSL, keep the checkout under your Linux home directory so the checkout and home directory share a filesystem.
sudo apt update
sudo apt install git python3 zsh
git clone https://github.com/gbgabiola/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
bash install.sh --dry-run
bash install.shThe installer links entries from home/ into your home directory. It skips
local overrides and templates. If a destination already exists, the installer
asks before replacing it and saves the original in a new backup/sync-*
directory. Noninteractive runs skip conflicts. You can rerun the installer:
existing links to the same checkout are kept. Backing up a conflict requires
the backup location and the destination to share a filesystem.
To use Zsh as your login shell, run chsh -s "$(command -v zsh)" once and
start a new login session. Package installation and Windows app setup are
separate from linking dotfiles.
If an older install linked ~/.localrc to a tracked file, make it a regular
file before updating the checkout. From Ubuntu, run:
if [ -L "$HOME/.localrc" ] && [ -f "$HOME/.localrc" ]; then
tmp=$(mktemp "$HOME/.localrc.XXXXXX") &&
cp -- "$HOME/.localrc" "$tmp" &&
mv -f -- "$tmp" "$HOME/.localrc"
fiIf the old link is already dangling, inspect it with ls -l ~/.localrc, remove
the link with unlink ~/.localrc, then use the template below.
- Zsh overrides: Copy
home/.localrc.exampleto~/.localrcif you don't already have one. Add editor, locale, or machine-specific environment settings there. Zsh reads it at the end ofhome/.zshrc. - Git identity: The
[include]block at the end ofhome/.gitconfigreads~/.gitlocal. Set your identity there and remove any oldGIT_AUTHOR_NAMEorGIT_AUTHOR_EMAILexports from~/.localrcso they don't override the Git settings.
git config --file ~/.gitlocal user.name "Your Name"
git config --file ~/.gitlocal user.email "you@example.com"Run zsh scripts/nodejs.zsh to install nvm and the current Node.js LTS.
The nvm release is pinned near the top of that script. To load nvm in new
Zsh sessions, add this to your own ~/.localrc:
export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
[ ! -s "$NVM_DIR/nvm.sh" ] || . "$NVM_DIR/nvm.sh"For a project that needs a separate Python version, install the
pyenv build dependencies
first. Then run zsh scripts/python.zsh for the latest Python 3.15 patch
known to your pyenv, or pass another version such as 3.14. The script
pins pyenv for new installs and reuses an existing installation. It leaves
your global Python selection in place.
To make pyenv available in Zsh, add this to your own ~/.localrc:
export PYENV_ROOT="${PYENV_ROOT:-$HOME/.pyenv}"
[[ ! -d "$PYENV_ROOT/bin" ]] || path=("$PYENV_ROOT/bin" "${path[@]}")
if command -v pyenv >/dev/null 2>&1; then
eval "$(pyenv init - zsh)"
fiOpen a new shell and run the pyenv local command printed by the installer
from the project directory.
From your checkout, run zsh scripts/update.zsh. It requires a clean
checkout with an upstream branch, pulls with --ff-only, and reruns the
installer. Update Ubuntu packages and language tooling separately.
To undo replacements made during a sync, use the snapshot path printed by the installer:
python3 restore.py backup/sync-REPLACE-WITH-YOUR-SNAPSHOTRestore moves the saved entries back, consuming those entries from the snapshot. It skips any destination that is neither missing nor still linked to this checkout. New links that replaced nothing have no backup; remove those links individually if you no longer want them. Keep the checkout in place while its links are in use.
Restore requires Linux with filesystem support for atomic no-replace renames. Keep the snapshot and destination on the same filesystem. If another process creates or replaces a destination during restore, the backup is kept and restore reports an error. A temporary recovery path is printed before moving a managed link. If automatic rollback cannot put that entry back, the entry remains at the printed path beside the snapshot. Inspect both paths before resolving the conflict and retrying. After an interrupted run, check the printed recovery path as well as the snapshot.
| What | Where to edit or apply it |
|---|---|
| Shared shell settings | Edit home/.zshrc. Put environment and PATH changes near the top; keep the local override block last. |
| Shared Git settings | Edit the relevant section in home/.gitconfig. Add identity only to ~/.gitlocal. |
| New shared home files | Add them to home/ and preview with bash install.sh --dry-run. Put samples in files ending in .example. |
| Commands and tooling | Add commands to bin/; add standalone setup utilities to scripts/. |
| WSL settings | Review .wslconfig for the Windows user profile and etc/wsl.conf for /etc/wsl.conf inside Ubuntu. Merge only the settings you need. |
| Windows Terminal and VS Code | Use windows-terminal/settings.json and vscode/User/ as references; merge the relevant settings into your app's existing configuration. |
| Windows startup | Review Startup/ before applying its Windows startup files manually. |
For Linux GUI applications on supported Windows 11 and WSL 2 installations, use WSLg. The legacy access-control-disabled XLaunch reference has been retired.
Run server [port] from the directory you want to preview in Ubuntu. It listens
on 127.0.0.1 and defaults to port 8000.
For a Windows folder you use from WSL, create one link with a new name.
WSL's default automount root places the C drive at /mnt/c. Applying this
repository's etc/wsl.conf sets root = /, which places it at /c.
Check your active mount path and replace YourName with your Windows username.
windows_documents='/mnt/c/Users/YourName/Documents'
# With this repository's automount setting, use /c/Users/YourName/Documents.
if [ -d "$windows_documents" ]; then
ln -sT -- "$windows_documents" "$HOME/windows-documents"
else
printf 'Windows Documents directory not found: %s\n' "$windows_documents" >&2
fiSee the WSL automount documentation for the mount-root setting.
To apply VS Code settings, open Preferences: Open User Settings (JSON)
or Preferences: Open Remote Settings (JSON) in a WSL window. Merge the
keys you want from vscode/User/settings.json into that JSON object. The
optional scripts/vscode.zsh helper only prompts to install extensions.
If you delete or rename a file under home/, check the corresponding link
in your home directory. Sync does not prune links; remove the old link after
verifying it points into this checkout.
Apply these references in the application where you use them. Review the following fields before copying settings.
| Reference | Prerequisites and fields to adapt |
|---|---|
vscode/User/settings.json |
Install VS Code and the formatter extensions you enable. Replace terminal.external.windowsExec with your Windows Terminal path. Select installed profiles for terminal.integrated.defaultProfile.windows and .linux. Install the fonts named in editor.fontFamily and terminal.integrated.fontFamily, or select installed fonts. |
windows-terminal/settings.json |
Run wsl --list --quiet in Windows to find your distro names. Adapt commandline and startingDirectory for your distro and Linux username. Keep your existing profile GUIDs and set defaultProfile to the GUID you use. Install MesloLGS NF or change fontFace. Supply your own backgroundImage, or remove the background-image settings. |
Startup/hotkeys.ahk |
The reference uses AutoHotkey v1 command syntax. Check interpreter compatibility before enabling it. Replace the GIMP executable, Chrome and foobar2000 commands, D: paths, and the Ubuntu-20.04 path containing nick. Remove individual hotkeys for applications or folders you do not use. |
home/.hyper.js |
Install Hyper on the OS where you use it. The supplied shell: 'wsl.exe' targets Windows. For Linux, choose an installed shell or an empty shell value for the login-shell default. Review plugins before enabling their downloads, and choose installed fonts. |
The VS Code reference selects Dracula and Material Icon Theme. The optional extension helper does not install these appearance extensions. To use them, run these commands in the terminal associated with your intended VS Code installation:
code --install-extension dracula-theme.theme-dracula
code --install-extension PKief.material-icon-themeAlternatively, choose installed themes for workbench.colorTheme and
workbench.iconTheme. Extension details are available from the
Dracula listing
and Material Icon Theme listing.
For Hyper, open its configuration from the application and merge the reference
there. Current configuration locations are %APPDATA%/Hyper/.hyper.js on
Windows and ~/.config/Hyper/.hyper.js on Linux. The home-directory link made
by this installer belongs to the Linux user and does not configure Windows
Hyper. An existing application-directory configuration takes precedence over
~/.hyper.js. See the Hyper configuration documentation.
With Python 3, Git, Vim, Bash, and Zsh installed, run from the checkout:
python3 -B -m unittest discover -s tests -vTests use temporary directories and stub privileged commands. Run as a regular user so the installer integration tests execute. GitHub Actions runs the suite and shell syntax checks for pull requests and pushes to main.
Copyright © 2019–2026 gbgabiola.
This repository is licensed under the MIT License.