Dotfilers

本仓库包含用 Rust 编写的 dotfile 管理工具 dotfilers 的源代码。

获取方法

您可以获取最新版本或自行构建。

$ cargo build --release

您将在 target/release/dotfilers 中找到二进制文件。

将二进制文件添加到您的路径中，即可开始使用！

用法

默认情况下，调用 dotfilers 将在当前目录中查找 dotfilers.yaml 文件。但是，您可以使用 -c/--config PATH 指定自定义文件。请注意，当前工作目录将用于计算相对路径。

当您正在测试某些配置时，您可以通过传递 -d/--dry-run 以不执行任何实际操作。如果以 dry-run 模式调用，dotfilers 将打印要执行的操作，但实际上不会执行任何操作。

此外，如果您只想应用一些 dotfilers.yaml 部分，您可以传递部分名称作为参数。假设您只想执行您的 nvim 和 ssh 部分。为此，您可以运行 dotfilers nvim ssh。

配置

通用配置

您可以在 dotfilers.yaml 中有一个 .dotfilers 部分，它将配置 dotfilers 二进制文件的行为。

以下是一个默认值的示例

.dotfilers:
  # Log level for the dotfilers binary
  # Must be one of:
  # - trace
  # - debug
  # - info
  # - warn
  # - error
  log_level: info
  
  # Strategy to use in case of conflict (the file that would be created already exists)
  # Must be one of:
  # - abort (the program will stop)
  # - overwrite (the already existing file/directory will be removed)
  # - rename-old (the already existing file/directory will be renamed to NAME.bak, and in case it also exists, .bak1, .bak2...)
  conflict_strategy: rename-old

  # Shell that will be used for 'run' directives
  shell: /bin/bash -c

部分配置

在您的 dotfilers.yaml 的根目录中，您可以指定您想要管理的不同部分。

一个部分以一个名称开头，然后是一系列要执行的操作。以下是可以找到的所有操作的示例

# Section for zsh files
zsh:
  # Create a symlink from zsh/.zshrc to ~/.zshrc
  - link_from: zsh/.zshrc
    link_to: ~/.zshrc

  # Only if the os is linux, create a symlink from zsh/.zshrc.linux to ~/.zshrc.local
  - if_os: linux
    link_from: zsh/.zshrc.linux
    link_to: ~/.zshrc.local

  # Only if the os is darwin, create a symlink from zsh/.zshrc.linux to ~/.zshrc.local
  - if_os: darwin
    link_from: zsh/.zshrc.darwin
    link_to: ~/.zshrc.local

# Section for ssh files
ssh:
  # Only if the os is linux:
  # - use the template on ssh/config.tpl
  # - fill it using the vars from ssh/vars_linux
  # - store the result at ~/.ssh/config
  - if_os: linux
    template: ssh/config.tpl
    template_to: ~/.ssh/config
    vars: ssh/vars_linux

  # Only if the os is darwin:
  # - use the template on ssh/config.tpl
  # - fill it using the vars from ssh/vars_darwin
  # - store the result at ~/.ssh/config
  - if_os: darwin
    template: ssh/config.tpl
    template_to: ~/.ssh/config
    vars: ssh/vars_darwin

  # Copy all files that match id_rsa* from the ssh folder into ~/.ssh/
  - copy_from: ssh/id_rsa*
    copy_to: ~/.ssh/

# Section for nvim files
nvim:
  # As this section is too long, run the contents of nvim/deploy.yaml
  - include: nvim/deploy.yaml

# Section for mash files
mash:
  # This will recursively link all files inside the mash directory into ~/mash
  # However, any existing directories will be created rather than symlinked 
  - link_from: mash
    link_to: ~/mash
    link_directory_behaviour: create
    
other:
  # This will symlink all files found inside the 'other' directory,
  # but will ignore any directory found inside the 'other' directory
  - link_from: other/*
    link_to: ~/.config/other
    link_directory_behaviour: ignore

# Section for extra things
extra:
  # Run inline code
  - run: echo "abc" > /tmp/abc

  # Run multiple commands
  - run: |
      echo "some_contents" >> /tmp/abc
      echo "Other contents" >> /tmp/abc

  # You can even invoke other programs/scripts
  - run: /usr/bin/python3 -c "print('a' * 127)" > /tmp/lotsofas

指令

在这里您可以找到所有受支持的指令的详细列表。

请注意，如果在同一指令条目中声明多个选项（例如 link_from，link_to，copy_from，copy_to），则结果操作没有任何一致性保证，因此请避免这样做。

复制

将文件或目录从一个位置复制到另一个位置。此命令在 copy_from 部分支持 glob。

部分

• copy_from：要复制的文件或目录。
  • 它支持 glob，例如 ssh/id_rsa* 或 directory/*.txt。
• copy_to：复制文件的路径。
  • 如果 copy_from 是单个文件，请也写出所需的目标文件名（例如：copy_to: ~/.ssh/authorized_keys）。
  • 如果 copy_from 是 glob，应使用目标目录的路径（例如：copy_from: directory/*.txt 和 copy_to: ~/data）。

链接

将文件或目录从一个位置链接到另一个位置。此命令在 link_from 部分支持 glob。

部分

• link_from：要创建符号链接的文件或目录。
  • 它支持 glob，例如 ssh/id_rsa* 或 directory/*.txt。
• link_to：文件链接的位置。
  • 如果 link_from 是单个文件，请也写出所需的文件名（例如：link_to: ~/.ssh/authorized_keys）。
  • 如果 link_from 是 glob，应使用目标目录的路径（例如：link_from: directory/*.txt 和 link_to: ~/data）。
• link_directory_behaviour：如何处理目录。如果没有指定，默认为 link。
  • 如果设置为 create，dir 内的所有目录将创建为目录而不是链接到目录。然后，原始目录中的文件将递归链接。
  • 如果设置为 link，任何找到的目录都只是链接。
  • 如果设置为 ignore，则忽略与 link_from 匹配的任何目录（特别是如果是 glob）。

模板

您还可以通过填写模板在动态生成文件。 dotfilers 使用 Tera 作为模板引擎，因此请参阅 Tera 文档了解模板。

为了定义变量，您可以创建任何您想要的文件名，并使用以下格式填充变量

variable1=value1

# Comments are ignored, but are only supported
# at the beginning of the line
variable2=value2

有一些变量是由 dotfilers 本身填充的。目前这些变量是

• dotfilers_os：当前操作系统。可以是 linux 或 darwin。

运行

您可以使用 dotfilers 运行任意命令。

没有比一些示例更好的文档了

# Run inline code
- run: echo "abc" > /tmp/abc

# Run multiple commands
- run: |
  echo "some_contents" >> /tmp/abc
  echo "Other contents" >> /tmp/abc

# You can even invoke other programs/scripts
- run: /usr/bin/python3 -c "print('a' * 127)" > /tmp/lotsofas

请记住，如果退出状态码不是 0，则执行将中止。

包含

对于非常长的部分，将指令委托到另一个文件中可能很有用。《code>dotfilers通过使用include指令支持这样做。

包含的文件必须与dotfilers.yaml文件具有相同的结构，这意味着您需要将指令包装到部分中。

# dotfilers.yaml
nvim:
  - include: nvim/directives.yaml
    
# nvim/directives.yaml
nvim:
  - if_os: linux
    run: echo "This is linux"

许可证

MIT License

Copyright (c) 2022 Carlos Quintana

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.