Dotfiles

My terminal-first macOS/Linux development environment powered by Zsh, Neovim, LazyVim, tmux, Alacritty, Yazi, LazyGit, Homebrew, and GNU stow.

Installation · Screenshots · Tools · Health check · Backup · Troubleshooting

Why these dotfiles
Preview screenshots
Included tools
Installation
- New macOS setup
- Existing machine setup
- Linux setup
- Install options
Health check
Backup workflow
Folder structure
Stow packages
Homebrew and Brewfile
Neovim and LazyVim
tmux
Alacritty
Yazi
LazyGit
Devlog
Markdown workflow
Command cheat sheet
Developer commands
Updating
Uninstalling
Troubleshooting
Docs
Customization and forking
Contributing
License

Why these dotfiles

This repository is my personal development environment in one place.

It is built around a fast, keyboard-driven workflow:

Neovim / LazyVim for coding
tmux for persistent terminal workspaces
Alacritty for a fast terminal emulator
Yazi for terminal file navigation
LazyGit for Git inside the terminal
Zsh for aliases, helper functions, and shell customization
GNU stow for clean symlink-based config management
Homebrew / Brewfile for repeatable macOS tool installation

The goal is simple: clone the repo, run one script, and get a familiar dev environment on a new machine.

Preview screenshots

Terminal overview	tmux workspace
Yazi	LazyGit

Included tools

Area	Tool	Purpose
Shell	Zsh	Aliases, functions, shell startup, and daily shortcuts
Editor	Neovim / LazyVim	Main coding environment with plugins and keymaps
Terminal	Alacritty	Fast GPU-accelerated terminal emulator
Sessions	tmux	Persistent terminal sessions and pane layouts
Files	Yazi	Fast terminal file manager
Git	LazyGit	Keyboard-driven Git UI inside the terminal
Packages	Homebrew / Brewfile	Install CLI tools, apps, fonts, and dependencies on macOS
Symlinks	GNU stow	Manage dotfiles without copying configs manually
Writing	Devlog / Jekyll	Optional daily Markdown logging and local writing workflow
Formatting	markdownlint / fixer script	Auto-fix Markdown from LazyVim or the shell

Installation

Review install.sh before running it. Dotfiles can install packages, create symlinks, and modify shell/editor configuration.

New macOS setup

Install Xcode Command Line Tools if prompted:

xcode-select --install

Clone the repository:

git clone https://github.com/IntScription/dotfiles.git ~/dotfiles
cd ~/dotfiles

Run the installer:

chmod +x install.sh
./install.sh

The installer is designed to:

Install Homebrew if needed
Install packages from Brewfile using brew bundle
Symlink configs into your home directory using GNU stow
Install tmux plugins through TPM
Bootstrap Neovim/LazyVim plugins in headless mode
Optionally clone and bootstrap the Devlog Jekyll site

After the script completes, restart your terminal or reload Zsh:

source ~/.zshrc

Existing machine setup

Clone the repository first:

git clone https://github.com/IntScription/dotfiles.git ~/dotfiles
cd ~/dotfiles

Back up existing configs before stowing anything:

chmod +x scripts/backup.sh
./scripts/backup.sh --yes

Preview the backup without moving files:

./scripts/backup.sh --dry-run

Then run the installer:

chmod +x install.sh
./install.sh

If you only want to link specific configs, use stow manually:

cd ~/dotfiles
stow -t "$HOME" zsh nvim tmux alacritty yazi

Linux setup

Install core dependencies first.

Ubuntu / Debian:

sudo apt update
sudo apt install -y git curl zsh stow tmux fzf ripgrep fd-find neovim build-essential

Fedora:

sudo dnf install -y git curl zsh stow tmux fzf ripgrep fd-find neovim gcc gcc-c++ make

Arch Linux / Manjaro:

sudo pacman -S git curl zsh stow tmux fzf ripgrep fd neovim base-devel

Clone and install:

git clone https://github.com/IntScription/dotfiles.git ~/dotfiles
cd ~/dotfiles
chmod +x install.sh
./install.sh

Optional Ubuntu/Debian fd alias, because the binary may be named fdfind:

mkdir -p ~/.local/bin
ln -sf "$(command -v fdfind)" ~/.local/bin/fd

Install options

The installer supports a few useful modes:

./install.sh --help
./install.sh --dry-run
./install.sh --stow-only
./install.sh --packages-only
./install.sh --no-brew
./install.sh --no-stow
./install.sh --devlog
./install.sh --no-devlog

Devlog setup is opt-in:

./install.sh --devlog

or:

SETUP_DEVLOG=1 ./install.sh

Health check

Use the doctor script to verify the important tools and config paths:

./scripts/doctor.sh

It checks your shell tools, terminal workflow dependencies, common config paths, and optional Devlog setup.

You can also run it through the Makefile:

make doctor

Backup workflow

Before applying dotfiles on an existing machine, back up current configs:

./scripts/backup.sh --yes

Run a safe preview first:

./scripts/backup.sh --dry-run

Backups are stored in timestamped folders under:

~/dotfiles-backup/

Folder structure

.
├── alacritty/
│   └── .config/alacritty/
├── config/
│   └── backup/
├── docs/
│   └── KEYMAPS.md
├── nvim/
│   └── .config/nvim/
├── scripts/
│   ├── backup.sh
│   ├── doctor.sh
│   └── fix_markdown.sh
├── tmux/
│   └── .config/tmux/
├── yazi/
│   └── .config/yazi/
├── zsh/
├── .github/
│   └── workflows/
│       └── ci.yml
├── .markdownlint.json
├── Brewfile
├── Makefile
├── coolnight.itermcolors
├── install.sh
└── README.md

Stow packages

Each top-level folder is a stow package. The directory structure inside each package mirrors where the files should appear in your home directory.

Package	Links to	Purpose
`zsh`	`~/.zshrc` and related shell files	Shell config, aliases, helper functions
`nvim`	`~/.config/nvim`	Neovim / LazyVim config
`tmux`	`~/.config/tmux`	tmux config and plugin setup
`alacritty`	`~/.config/alacritty`	Terminal config
`yazi`	`~/.config/yazi`	Terminal file manager config

Stow everything:

stow -t "$HOME" zsh nvim tmux alacritty yazi

Restow a package after changes:

stow -R -t "$HOME" nvim

Unstow a package:

stow -D -t "$HOME" nvim

Homebrew and Brewfile

Homebrew is used to install CLI tools, GUI apps, fonts, and dependencies on macOS.

Run the Brewfile manually:

brew bundle --file=Brewfile

Check what would be installed without changing anything:

brew bundle check --file=Brewfile

Update installed Homebrew packages:

brew update
brew upgrade
brew bundle --file=Brewfile

Neovim and LazyVim

Neovim is the main editor in this setup, built around a LazyVim-style workflow.

Useful commands:

:Lazy
:LazyHealth
:Mason
:checkhealth

Markdown preview:

:MarkdownPreviewToggle

Keymap:

<leader>mp

tmux

tmux is used for persistent terminal sessions, split panes, and project workspaces.

Reload tmux config:

tmux source-file ~/.config/tmux/tmux.conf

If your setup also links ~/.tmux.conf, you can reload with:

tmux source-file ~/.tmux.conf

Install tmux plugins manually if needed:

git clone https://github.com/tmux-plugins/tpm ~/.config/tmux/plugins/tpm

Then press the TPM install key inside tmux, usually:

prefix + I

Alacritty

Alacritty is the terminal emulator config included in this repo.

Typical config location:

~/.config/alacritty/

Use this section to document your font, theme, opacity, padding, and shell preferences as the config evolves.

Yazi

Yazi is the terminal file manager used in this workflow.

Run it with:

yazi

Typical config location:

~/.config/yazi/

LazyGit

LazyGit gives you a fast terminal UI for Git.

Run it with:

lazygit

This pairs well with tmux and Neovim because you can keep Git, editing, and shell commands inside one terminal workflow.

Devlog

Devlog setup is optional.

Run:

./install.sh --devlog

The installer clones the Devlog repository to:

~/projects/learning/devlog

Repo:

https://github.com/IntScription/devlog

Local preview:

cd ~/projects/learning/devlog
bundle exec jekyll serve

Then open:

http://localhost:4000/devlog/

Daily logging helper:

source ~/.zshrc
devlog

The devlog helper opens today’s logs/YYYY-MM-DD/index.md in Neovim, updates Prev/Next links, refreshes the archive, and updates recent entries.

Optional notes folder:

ln -s ~/Obsidian/Vault/MyNotes ~/projects/learning/devlog/notes/MyNotes

Markdown workflow

A Markdown fixer script lives here:

scripts/fix_markdown.sh

Run it manually:

./scripts/fix_markdown.sh

Or use the alias:

fixmd

The fixer prefers markdownlint-cli2 if installed, falling back to markdownlint from markdownlint-cli.

Command cheat sheet

Command	What it does
`nvim`	Open Neovim
`tmux`	Start tmux
`yazi`	Open terminal file manager
`lazygit`	Open Git terminal UI
`devlog`	Create/open today’s Devlog entry
`fixmd`	Fix Markdown formatting
`brew bundle --file=Brewfile`	Install Brewfile packages
`./scripts/doctor.sh`	Check required tools and config paths
`./scripts/backup.sh --dry-run`	Preview config backup
`./scripts/backup.sh --yes`	Back up existing configs
`make doctor`	Run the doctor script
`make backup`	Run the backup script
`make restow`	Restow all managed packages
`make lint`	Run shell and Markdown checks
`stow -R -t "$HOME" nvim`	Restow Neovim config
`tmux source-file ~/.config/tmux/tmux.conf`	Reload tmux config

Developer commands

This repo includes a small Makefile for common maintenance tasks.

make help
make install
make doctor
make backup
make restow
make unstow
make update
make lint

The lint target uses available tools such as shellcheck, shfmt, and markdownlint-cli2. Missing linters are skipped locally, while GitHub Actions installs them in CI.

Updating

Pull the latest changes:

cd ~/dotfiles
git pull

Or use:

make update

Re-run the installer:

./install.sh

Or restow only configs:

stow -R -t "$HOME" zsh nvim tmux alacritty yazi

Update Homebrew packages:

brew update
brew upgrade
brew bundle --file=Brewfile

Update Neovim plugins:

:Lazy sync

Uninstalling

Unstow all managed configs:

cd ~/dotfiles
stow -D -t "$HOME" zsh nvim tmux alacritty yazi

Restore backups if you created them:

mv ~/dotfiles-backup/<timestamp>/.zshrc ~/.zshrc
mv ~/dotfiles-backup/<timestamp>/.config/nvim ~/.config/nvim
mv ~/dotfiles-backup/<timestamp>/.config/tmux ~/.config/tmux
mv ~/dotfiles-backup/<timestamp>/.config/alacritty ~/.config/alacritty
mv ~/dotfiles-backup/<timestamp>/.config/yazi ~/.config/yazi

Remove the repo if you no longer need it:

rm -rf ~/dotfiles

Troubleshooting

Run the doctor first

Most setup issues are easier to diagnose with:

./scripts/doctor.sh

or:

make doctor

Tmux is using the default config

Tmux 3.1+ reads:

~/.config/tmux/tmux.conf

If tmux cannot find your config, recreate the symlink from the repo root:

mkdir -p ~/.config
ln -sfn "$HOME/dotfiles/tmux/.config/tmux" "$HOME/.config/tmux"
ln -sfn "$HOME/.config/tmux/tmux.conf" "$HOME/.tmux.conf"
tmux source-file ~/.config/tmux/tmux.conf

Neovim closes when pressing H or yanking

If pressing H or yanking closes Neovim and the terminal shows kill, check your mappings:

:verbose map H
:verbose map y

Test without plugins:

nvim -u NONE

If you use iTerm2, also check key mappings under:

iTerm2 → Settings → Profiles → Keys → Key Mappings

Stow says a file already exists

Back up the existing file, then restow:

mv ~/.zshrc ~/.zshrc.bak
stow -R -t "$HOME" zsh

Or use the backup script:

./scripts/backup.sh --dry-run
./scripts/backup.sh --yes

Neovim plugins are missing

Open Neovim and run:

:Lazy sync
:checkhealth

Homebrew command not found

Install Homebrew or re-run the installer:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then follow the shell instructions printed by Homebrew.

fd command not found on Ubuntu or Debian

The binary may be installed as fdfind:

mkdir -p ~/.local/bin
ln -sf "$(command -v fdfind)" ~/.local/bin/fd

Docs

Extra documentation lives in the docs/ folder.

File	Purpose
`docs/KEYMAPS.md`	Neovim, tmux, shell, and workflow shortcuts

Keep the README focused on setup and use the docs folder for deeper workflow notes as the config grows.

Customization and forking

Feel free to fork this repo and adapt it to your workflow.

Good places to customize:

Zsh aliases and helper functions
Neovim plugins, keymaps, and LSP tools
tmux prefix, statusline, panes, and plugins
Alacritty fonts, theme, padding, and opacity
Yazi layout and previews
Brewfile packages and apps
Devlog paths and helper commands

Contributing

Suggestions, issues, and improvements are welcome.

Open an issue or pull request if you have an idea that improves the setup, fixes an install edge case, or makes the docs clearer.

License

MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
.github/workflows		.github/workflows
alacritty/.config/alacritty		alacritty/.config/alacritty
assets		assets
config/backup		config/backup
docs		docs
nvim/.config/nvim		nvim/.config/nvim
scripts		scripts
tmux/.config/tmux		tmux/.config/tmux
yazi/.config/yazi		yazi/.config/yazi
zsh		zsh
.markdownlint.json		.markdownlint.json
Brewfile		Brewfile
Makefile		Makefile
README.md		README.md
coolnight.itermcolors		coolnight.itermcolors
install.sh		install.sh
package-lock.json		package-lock.json
tmux-client-52198.log		tmux-client-52198.log

Folders and files

Latest commit

History

Repository files navigation

Dotfiles

Contents

Why these dotfiles

Preview screenshots

Included tools

Installation

New macOS setup

Existing machine setup

Linux setup

Install options

Health check

Backup workflow

Folder structure

Stow packages

Homebrew and Brewfile

Neovim and LazyVim

tmux

Alacritty

Yazi

LazyGit

Devlog

Markdown workflow

Command cheat sheet

Developer commands

Updating

Uninstalling

Troubleshooting

Run the doctor first

Tmux is using the default config

Neovim closes when pressing H or yanking

Stow says a file already exists

Neovim plugins are missing

Homebrew command not found

fd command not found on Ubuntu or Debian

Docs

Customization and forking

Contributing

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages