《folderify项目技术文档》

1. 安装指南

folderify可以通过Homebrew进行安装，这是推荐的安装方式。安装命令如下：

brew install folderify

使用Homebrew安装将自动为您的shell安装folderify的命令行补全。

如果您没有Homebrew，但系统中已经安装了ImageMagick，您可以尝试以下其他安装方式：

使用Rust安装

cargo install folderify

从源代码安装

或者直接下载代码：

git clone https://github.com/lgarron/folderify && cd folderify

# 直接运行
cargo run -- --reveal examples/src/folder_outline.png .

# 安装（假设`cargo`命令在您的路径中）
cargo install --path .
folderify --reveal examples/src/folder_outline.png .

此时，仓库文件夹应该具有一个自定义图标。

for file in examples/src/*.png; do cargo run -- $file; done
open examples/src/

您会看到一系列由.png遮罩自动生成的.iconset文件夹和.icns文件。

2. 项目使用说明

使用folderify为文件夹分配一个图标，您需要一个遮罩图片：

folderify mask.png /path/to/folder

如果要生成.icns和.iconset文件，可以使用以下命令：

folderify mask.png

默认情况下，folderify会使用系统当前的光暗模式。如果需要覆盖此设置，请使用--color-scheme：

folderify --color-scheme dark mask.png

注意：目前没有办法设置一个在切换整个操作系统光暗模式时会自动切换的图标。您只能为文件夹分配一个版本的图标。

使用技巧

• 使用.png遮罩。
• 在透明背景上使用纯黑色设计。
• 确保遮罩图像的角像素是透明的。它们用于设置空白边距。

3. 项目API使用文档

以下是folderify的完整选项说明：

生成一个原生风格的macOS文件夹图标从遮罩文件。

使用方式：folderify [选项] [目标]

参数：
  遮罩图像文件。为获得最佳效果：
  - 使用.png遮罩。
  - 在透明背景上使用纯黑色设计。
  - 确保遮罩图像的非透明像素跨越的高度为384px，使用16px的网格。
  如果高度为384px且宽度为128px的倍数（最多768px），每个64x64图块将精确对齐到最小文件夹大小的一个像素。

[目标]
  目标文件或文件夹。如果指定了目标，生成的图标将应用于目标文件/文件夹。否则（除非指定了--output-icns或--output-iconset），将在遮罩所在的同一文件夹中创建一个.iconset文件夹和.icns文件（您可以使用Finder中的“获取信息”来复制.icns文件的图标）。

选项：
  --output-icns <ICNS文件>
      将.icns文件写入给定路径。（即使也指定了目标，也会写入。）

  --output-iconset <ICONSET文件夹>
      将.iconset文件夹写入给定路径。（即使也指定了目标，也会写入。）

  -r, --reveal
      在Finder中显示目标、.icns或.iconset（按此偏好顺序）。

  --macOS <MACOS版本>
      macOS文件夹图标的版本，例如"14.2.1"。默认为当前运行的版本

  --color-scheme <颜色方案>
      颜色方案 - 自动匹配当前系统值

      [默认：自动]
      [可能的值：自动、浅色、深色]

  --no-trim
      不从遮罩中裁剪边距。
      默认情况下（即不使用此标志），所有四边的透明边距将被裁剪。

  --no-progress
      不显示进度条

  --badge <徽章>
      向图标添加徽章。目前仅支持一次性一个徽章

      [可能的值：别名、锁定]

  -v, --verbose
      详细的输出。也设置了`--no-progress`

  --completions <shell>
      打印给定shell的补全（而不是生成任何图标）。
      这些可以永久加载/存储（例如，当使用Homebrew时），但它们也可以直接源码加载，例如：

      folderify --completions fish | source # fish
      source <(folderify --completions zsh) # zsh

      [可能的值：bash、elvish、fish、powershell、zsh]

  -h, --help
      打印帮助（使用'-h'查看摘要）

  -V, --version
      打印版本

4. 项目安装方式

请参照“安装指南”部分中提供的方式进行安装。推荐使用Homebrew安装，但也可以通过Rust工具或从源代码进行安装。