beyond-local-file

三月 07, 2026

最近捣鼓了一个小工具，解决了我在日常开发中遇到的一个痛点问题。今天就来跟大家分享一下这个我认为很有意思也很有用的小玩意儿。

缘起：那些不想提交又怕丢失的文件

在日常开发中，我们总会遇到一些不想提交到Git仓库但又非常重要的文件。这些文件可能是：

调试了好几个小时才写出来的测试脚本
包含敏感信息的配置文件
临时的HTTP请求测试文件
项目特有的开发工具配置

把这些文件提交到Git仓库显然不合适，但如果不提交，又担心换电脑、重装系统或者清理项目时不小心丢失。

于是，我就想：能不能有个工具，让我在一个地方集中管理这些文件，同时可以在多个项目中使用它们，还能确保这些文件不会丢失？

解决方案：符号链接魔法

答案当然是有的！beyond-local-file 就是我为这个问题找到的解决方案。它利用符号链接（symbolic links）技术，完美解决了这个两难的问题：

📦 集中管理本地开发文件，不用担心丢失
🔗 在多个目标项目中使用这些文件，无需复制粘贴
🚫 自动将符号链接添加到Git忽略列表，确保临时文件不会被意外提交
🧐 检查同步状态，确保所有项目都使用最新版本的文件

安装：一行命令搞定

由于这个工具还在开发中，尚未发布到PyPI，你可以通过以下方法直接从Git存储库安装。我个人推荐使用 uv 工具安装，因为它真的很快！

# 从Git存储库安装
uv tool install git+https://github.com/xingyuli/beyond-local-file.git

# 现在你可以直接从任何目录使用它
beyond-local-file --help

# 更新到最新版本
uv tool install --force git+https://github.com/xingyuli/beyond-local-file.git

简单上手：三步搞定文件同步

1. 初始化管理项目

首先，创建一个管理项目目录，并在其中创建配置文件：

# 创建管理项目目录
mkdir -p ~/my-dev-files
cd ~/my-dev-files

# 创建配置文件 config.yml
cat > config.yml << EOF
projects:
  project-a:
    target: ~/workspace/project-a
    files:
      - test-scripts/
      - dev-config.yml
  project-b:
    target: ~/workspace/project-b
    files:
      - test-scripts/
      - dev-config.yml
EOF

# 创建相应的文件
mkdir -p project-a/test-scripts
echo "# 测试脚本" > project-a/test-scripts/debug.sh
echo "# 开发配置" > project-a/dev-config.yml
cp -r project-a project-b

2. 创建符号链接

1
2
3

# 在管理项目目录中运行
cd ~/my-dev-files
beyond-local-file symlink create

这将在目标项目中创建符号链接，所有项目都指向同一个源文件。

3. 享受”同步”的快乐

现在，一切尽在掌握，干干净净的Git仓库，没有任何临时文件被提交。

写在最后

beyond-local-file 是一个简单但实用的工具，它解决了我在日常开发中遇到的一个核心痛点：如何在不将临时文件提交到Git仓库的情况下，确保这些文件不会丢失，并且可以在多个项目中共享使用。

通过集中管理本地开发文件，我再也不用担心换电脑或者重装系统时丢失重要的测试脚本和开发配置了。同时，符号链接技术也让我可以在多个项目中使用这些文件，而无需复制粘贴。

未来规划

目前这个工具还在不断完善中，我计划在未来添加以下功能：

配置文件加载

支持从 .blfrc 文件中加载配置，让工具使用更加灵活。

反向链接

添加 revlink 命令，可以在当前工作目录中快速创建反向链接。

可用性优化

优化覆盖提示信息，让用户更清楚地了解当前操作的影响
改进命令行界面，支持自动补全功能
在 --help 中显示当前版本信息

使用建议

推荐将 beyond-local-file 命令别名为 blf，这样使用起来更加快捷：

1	alias blf='beyond-local-file'

如果你也有类似的困扰，不妨试试这个工具。详细的使用说明可以在GitHub仓库中找到，欢迎提出你的想法和建议！

👉 GitHub仓库地址

查看评论