skip to content
Liu Yang's Blog

用 Stow + Git 管理 dotfiles，多端同步配置

/ 6 min read

View more blogs with the tag linux , View more blogs with the tag vim , View more blogs with the tag dev
Table of Contents

起因

最初是在学 Vim 的时候，看到 The Missing Semester of Your CS Education 里提到：你的配置文件（dotfiles）是你最私人的工具，应该像代码一样被版本控制。

这句话击中了我。我的 .vimrc 已经攒了不少快捷键和插件，换台机器就得重头来一遍。加上开始用 Fish shell、tmux、Git 别名这些东西，零散的配置越来越多，多端一致性几乎做不到。

于是打算正式搭一套 dotfiles 管理方案。

核心思路：Stow + Git

方案其实很简单：

  1. 用一个 Git 仓库存放所有配置文件
  2. 用 GNU Stow 把仓库里的文件以软链接的形式部署到 $HOME

Stow 是一个符号链接管理工具。它的工作原理是：把 ~/dotfiles/<package>/ 目录下的文件，软链接到对应的 $HOME 位置，并且会自动处理嵌套的目录结构。

比如，~/dotfiles/vim/.vimrc 经过 stow vim 之后，就会在 ~/.vimrc 出现一个符号链接，指向 dotfiles 仓库里那个文件。改动只需要在仓库里进行，git push 就同步了。

仓库结构

每个工具作为一个独立的”包”存在：

dotfiles/
├── bash/
├── zsh/
├── fish/
├── vim/
├── tmux/
├── git/
├── ssh/
├── starship/
├── dircolors/
├── inputrc/
├── bootstrap.sh      # 一键初始化脚本
├── Brewfile          # macOS 包清单
└── apt-packages.txt  # Debian/Ubuntu 包清单

要部署某个包，就 cd ~/dotfiles && stow vim。要撤销就 stow -D vim，要重建链接就 stow -R vim。

本机覆盖：local 文件

有些配置需要机器级别的个性化，比如 Git 的用户名和邮箱、SSH 代理的路径、tmux 的字体设置。这些不适合提交到公开仓库。

解决方法是在配置里 include 一个本地文件，而这个文件不进版本控制：

# ~/.gitconfig（由 stow 链接自仓库）
[include]
    path = ~/.gitconfig.local   # 不提交，只在本机存在

tmux 同理，在 ~/.tmux.conf 末尾加一行：

Terminal window
source-if-exists ~/.tmux.conf.local

这样仓库里只保留通用默认值，机器特有的配置放在 .local 文件里，互不干扰。

bootstrap.sh：新机器一键搞定

换新机器时，不想手动 stow 一个个包。bootstrap.sh 做了这几件事：

  1. 检测 macOS / Linux，调用对应的包管理器安装依赖
  2. 对所有包执行 stow，把配置链接到 $HOME
  3. 初始化 Fish 插件（通过 fisher）
Terminal window
git clone https://github.com/imYangliu/dotfiles ~/dotfiles
cd ~/dotfiles
./bootstrap.sh

支持几个跳过选项，方便只做其中一部分：

Terminal window
./bootstrap.sh --no-install      # 不装包，只建链接
./bootstrap.sh --no-stow         # 只装包，不建链接
./bootstrap.sh --no-fish-plugins # 跳过 Fish 插件

探索过程中发现的工具

整理 dotfiles 的过程也是系统性整理 CLI 工具链的过程。记录几个发现后就离不开的：

Shell 导航

  • zoxide：智能 cd，记录访问频率，z foo 直接跳到最常用的 foo 目录，比 autojump 快得多。
  • fzf：模糊搜索器。Ctrl+R 搜历史、Ctrl+T 找文件，接管了我大量手动输路径的操作。
  • starship：跨 shell 的提示符，配置一次在 Zsh / Fish 都生效。

文件和搜索

  • ripgrep (rg)：比 grep 快很多的递归搜索，默认忽略 .gitignore 里的文件，Vim 下搭配 fzf 用体验很好。
  • bat：带语法高亮的 cat，顺手加上了行号和 Git 改动标记。
  • eza：ls 的现代替代，默认带颜色和图标，--tree 看目录树也很方便。
  • fd：find 的友好替代，语法更直觉，速度更快。

Git 相关

  • git-delta：Git diff 的美化 pager，并排显示 + 语法高亮，看 diff 的体验提升明显。
  • lazygit：终端 Git TUI，用键盘完成 staging、commit、rebase 等操作，鼠标都不用碰。

数据处理

  • jq / jaq：JSON 处理的必备工具，API 调试和日志分析时用得很多。
  • yq：把 jq 的语法搬到 YAML / TOML / XML，配置文件批量改动很方便。

其他

  • tealdeer (tldr)：man 的简化版，只看常用示例，忘记参数时比翻 man page 快多了。
  • direnv：进目录自动加载 .envrc 里的环境变量，切项目时不用手动 source。
  • just：项目任务runner，比 Makefile 语法简单，适合存一些常用的项目脚本。

总结

整套方案的核心只有两个工具：Git 管版本，Stow 管链接。没有魔法，没有额外的 dotfiles 框架，足够透明、足够简单。

Missing Semester 里那句”配置文件是你最私人的工具”，现在有了实体：github.com/imYangliu/dotfiles。

本文由 Claude 润色。