Skip to content

Repository files navigation

Genesis Gabiola's dotfiles

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.

Install on Ubuntu or WSL

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.sh

The 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.

Personalize this machine

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"
fi

If 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.example to ~/.localrc if you don't already have one. Add editor, locale, or machine-specific environment settings there. Zsh reads it at the end of home/.zshrc.
  • Git identity: The [include] block at the end of home/.gitconfig reads ~/.gitlocal. Set your identity there and remove any old GIT_AUTHOR_NAME or GIT_AUTHOR_EMAIL exports from ~/.localrc so they don't override the Git settings.
git config --file ~/.gitlocal user.name "Your Name"
git config --file ~/.gitlocal user.email "you@example.com"

Optional development tools

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)"
fi

Open a new shell and run the pyenv local command printed by the installer from the project directory.

Update and restore

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-SNAPSHOT

Restore 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.

Where to make changes

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
fi

See 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.

Optional profile prerequisites

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-theme

Alternatively, 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.

Validation

With Python 3, Git, Vim, Bash, and Zsh installed, run from the checkout:

python3 -B -m unittest discover -s tests -v

Tests 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.

Credits

License

Copyright © 2019–2026 gbgabiola.

This repository is licensed under the MIT License.