参数设置

工作流概述：基于路径匹配和文件属性筛选后获得的路径列表，进行快捷操作。

工作流关键点：

获取待处理路径列表；
对路径列表进行进一步处理。

快捷功能分类：

只读操作：处理源路径数据，不进行写入修改；

如：list, search, fdups, archive, unarchive, mirror。
读写操作：处理源路径数据，涉及修改或删除；

如：replace, rmdir, clean, wipe。

快捷功能与CLI命令对应关系如下：

快捷功能（Available Commands）
全局选项（Global Options）
命令参数（Arguments）

终端CLI命令：

ft --help
FileTools: cross-platform glob & streams. 
Usage: ft <command> <source> [arguments]

Global options:
-h, --help                        Print this usage information.
-v, --verbose                     Show additional command output.
    --version                     Print the tool version.
    --source=<path>               Specify the source (file|directory)
    --config=<file>               Loads a config file for variable referencing
    --config_txt=<yaml>           Loads a yaml text for variable referencing
    --config_gen                  Generate a custom config on curdir.
    --errexit                     exit on error.
                                  (defaults to on)
    --define                      Define or override a variable from command line
    --pattern                     Glob pattern
                                  (defaults to "**")
    --excludes                    Glob pattern after exclusion (e.g. --excludes='.**')
    --fields                      show fields (ok, action, type, mime, perm, time, size, extra)
    --size_le                     file size less than (in bytes, unit:B|K|M|G|T|P)
    --size_ge                     file size greater than (in bytes, unit:B|K|M|G|T|P)
    --time_le                     file time before (yyyyMMddTHHmmss | yyyyMMdd)
    --time_ge                     file time after (yyyyMMddTHHmmss | yyyyMMdd)
    --time_type=<modified>        file time type (changed | modified | accessed)

          [changed]               ctime - change time
          [modified] (default)    mtime - modification time
          [accessed]              atime - access time

Available commands:
  archive     archive source file|directory to target file. 
  clean       clean source file|diretory 
  execute     execute command blocks defined in `--config`, using `--source` as the working directory.  
  fdups       find duplicate files from source diretory 
  list        listing all entities that match a glob 
  mirror      mirror source file|diretory to target directory 
  rmdir       remove empty source directory 
  search      search with regexp or replace.  
  shell       execute script blocks defined in `--config`, using `--source` as the working directory.  
  unarchive   unarchive tar|tgz source file to target directory 
  wipe        secure wipe source file|diretory 

Run "ft help <command>" for more information about a command.

T1GUI-全局参数-筛选器 (Filter)

prefs-filter-default

--pattern：路径匹配模式
--excludes：排除匹配模式
--size_ge：文件大小大于等于
--size_le：文件大小小于等于
--time_ge：文件时间晚于
--time_le：文件时间早于
--fields：显示字段
保存当前配置
更多选项：
- 另存配置文件
- 预览配置文件
- 加载配置文件
返回并应用当前配置

T2GUI-命令参数-搜索 (Search)

ft help search
Search with regexp or replace.  

Usage: ft search <source> --regexp=<pattern> [arguments]
-h, --help                Print this usage information.
    --regexp=<pattern>    regex pattern
    --extmime             ext mime for search (e.g. --extmine='yaml=text/yaml')
    --[no-]linebyline     line by line file processing
                          (defaults to on)
    --esc                 escape regexp special characters.
    --rei                 regex use case insensitive.
    --reu                 regex use unicode.
    --res                 regex use dot all.
    --rem                 regex use multiLine.
    --replace             regexp has match to replace

Run "ft help" to see global options.

如果仅需搜索，请将替换内容留空。

--regexp：正则表达式
--replace：替换内容
正则表达式选项：
- reI (--rei)：忽略大小写；
- reU (--reu)：使用Unicode；
- reM (--rem)：多行模式；
- reS (--res)：点号匹配所有字符。
--linebyline：逐行处理文件

T3GUI-命令参数-目标路径 (Target)

A. mirror 命令参数
B. unarchive 命令参数
C. archive 命令参数

prefs-target-default

A|B|C 1: --relative：目标路径使用源路径的相对结构
A|B|C 2: --tail：目标路径包含源路径尾部片段层级
A|B|C 3: --target：指定目标目录

效果示例如： --source=~/Downloads/ft --target=~/Downloads/backups

--no-relative：不使用相对路径，源路径完整结构会去根部后被完整复制到目标路径下。

示例结果：~/Downloads/backups/${HOME}/Donwloads/ft
--relative --tail=0 (默认)：目标路径为指定目标目录本身。

示例结果：~/Downloads/backups
--relative --tail=1：目标路径包含源路径的最后一级目录。

示例结果：~/Downloads/backups/ft
--relative --tail=2：目标路径包含源路径的最后两级目录。

示例结果：~/Downloads/backups/Downloads/ft

例（mirror）：

ft help mirror 

mirror source file|diretory to target directory 
Usage: ft mirror <source> <target> [arguments]
-h, --help                  Print this usage information.
    --target=<directory>    target directory
    --[no-]relative         mirror source use relative directory.
                            (defaults to on)
    --tail=<int>            tail source injection to target.
                            (defaults to "0")

# 默认: --relative --tail=0; 目标路径: ~/Downloads/backups/temp/
ft mirror ~/Downloads/ft ~/Downloads/backups/temp -v --fields=ok,action,type
1  mirror f ~/Downloads/backups/temp/README.md
1  mirror f ~/Downloads/backups/temp/pubspec.yaml

# 示例: --relative --tail=1; 目标路径: ~/Downloads/backups/ft/
ft mirror ~/Downloads/ft ~/Downloads/backups/ --tail=1 -v --fields=ok,action,type
1  mirror f ~/Downloads/backups/ft/README.md
1  mirror f ~/Downloads/backups/ft/pubspec.yaml

T4GUI-全局参数-变量设置 (Variable)

Variable（变量）功能对应CLI中的--define选项。

系统环境变量 > 如: HOME，PATH，HTTP_PROXY
用户自定义变量 > 变量名仅支持小写字母a-z和下划线_； > my_project_dir，my_backup_dir，my_log_dir，my_data_dir
程序运行时变量 > CURDIR, CURDATE, CURDATETIME

变量优先级：用户自定义变量 < 系统环境变量 < 程序运行时变量。 prefs-variable-default

A. 示例如下：

--define='downloads=~/Downloads,ft_target_dir=~/Documents/FileShows,backup_files=**~'

在GUI中，这相当于您分别设置以下三项：

downloads=~/Downloads
ft_target_dir=~/Documents/FileShows
backup_files=**~

变量代入示例：

# 清除 downloads 目录下所有 Emacs 备份文件。
ft clean --source='$downloads' --pattern='$backup_files' -v --define='downloads=~/Downloads,backup_files=**~'

# 每天归档 ~/Downloads/ft 文件夹。
ft archive --source='$downloads/ft' --target='$ft_target_dir/archive/$CURDATE' --tail=1  -v --define='downloads=~/Downloads,ft_target_dir=~/Documents/FileShows'

B. 目标基准目录 (External Data Root)

在 macOS, Android, Linux (如 Snap/Flatpak) 等沙盒系统中，应用程序与外部数据严格隔离，对外部数据的访问需要显式授权。

在此，你可以选择并授权一个外部目录作为本应用的 $ft_target_dir，用于统一读写和管理外部数据。本应用将获得对 $ft_target_dir 及其子目录的持续访问权限。

例如，若设定 $ft_target_dir 为 /storage/emulated/0/Documents，则本应用相关的外部目录将组织如下：

mirror_to -> $ft_target_dir/mirror
archive_to -> $ft_target_dir/archive
unarchive_to -> $ft_target_dir/unarchive

(注意：iOS 系统由于其严格的沙盒模型，通常不支持用户为应用指定外部任意目录作为基准。)

C. 覆写应用内部 HOME 变量 (App-Internal HOME Variable Override)

在 Unix-like 系统中，波浪号 ~ 通常代表由 HOME 环境变量定义的家目录。然而，在沙盒环境下（如 macOS, Android, Linux Snap/Flatpak 等），应用程序可能无法获取到正确的 HOME 环境变量值。

此功能允许你为本应用自定义并覆写内部 HOME 变量。该设置仅在本应用内部生效，不会影响系统环境变量，以确保本应用能正确处理依赖 HOME 路径的操作。

例如：如果文件路径为 /storage/emulated/0/Documents/archive/ft.tgz，且你将本应用内部 HOME 变量设置为 /storage/emulated/0/Documents，那么本应用内对 ~/archive/ft.tgz 的引用将准确指向该文件。

T5GUI-命令参数-批量处理 (Batch)

在批量处理中，commands（命令）用于ft execute子命令，scripts（脚本）用于ft shell子命令。

prefs-batch-default

源路径 (sources) > 该字段数据来源于快捷方式页面的源路径输入，便于保存和加载时复用，与execute和shell子命令无直接关联。
命令 (commands) > 仅支持ft内置子命令。
脚本 (scripts) > 支持当前操作系统中的所有CLI命令。

示例（commands）：

假设您有一个网站，存放在/mnt/100G/mywebsite1/下，其下有日志文件夹logs和数据文件夹dbs（使用SQLite）及图像文件夹imagen；您需要每天凌晨将dbs和logs归档到/mnt/100T/archive/mywebsite1/下，然后清除logs，并清除1个月前的图像。

# 归档 logs 和 dbs 文件夹。
ft archive /mnt/100G/mywebsite1/dbs /mnt/100T/archive/mywebsite1/\$CURDATE --tail=1
ft archive /mnt/100G/mywebsite1/logs /mnt/100T/archive/mywebsite1/\$CURDATE --tail=1
# 清除 logs 文件夹中的所有文件。
ft clean /mnt/100G/mywebsite1/logs
# 清除 1 个月前的图像。
ft clean /mnt/100G/mywebsite1/imagen --time_le='1 month ago'

如果您将这些命令保存到配置文件ft_mywebsite1_archive.yaml中，则可以如下运行：

ft execute . --config=ft_mywebsite1_archive.yaml

示例（scripts）：

假设您有一个源代码目录，存放在~/Projects/下；其下有项目文件夹ft和fileshows；fileshows应用需要引入ft这个包；您需要在构建fileshows前，拉取两个项目的最新代码，并更新其依赖库。

cd ~/Projects/ft
# git reset --hard origin/main
git pull
dart pub get --no-example
dart pub upgrade

cd ~/Projects/fileshows
# git reset --hard origin/main
git pull
flutter pub get --no-example
flutter pub upgrade

如果您将这些脚本保存到配置文件ft_fileshows_refresh.yaml中，则可如下运行：

ft shell . --cofnig=ft_fileshows_refresh.yaml

T6GUI-定时任务 (Cronjob)

如果您有需要定时执行的批量操作，可在此处进行设置。

prefs-cronjob-default

操作 (Action)：run | pause | stop | delete
时间频率 (Time)：hourly | daily | weekly | ...
Cron表达式 (Expression)
日志路径 (Logpath)：指定日志保存目录
单次运行 (Run Once)

示例（commands）：

把用户临时桌面工作区内的文档进行增量镜像，以便用户回溯最近几天的文档。
We incrementally mirror documents from the user's temporary desktop workspace, allowing them to revisit documents from the last few days.

# 当前时间 (NOW): 2025-08-29T09:02:26.441496;
# 当前日期 (CURDATE): 20250829; 当前日期时间 (CURDATETIME): 20250829090226
# 1天前日期 (AGODATE1DAY): 20250828; 1天前日期时间 (AGODATETIME1DAY): 20250828090226
# 1周前日期 (AGODATE1WEEK): 20250822; 1周前日期时间 (AGODATETIME1WEEK): 20250822090226
# ft mirror ~/Desktop ~/Documents/FileShows/mirror/Desktop/\$CURDATE/\$CURDATETIME
ft mirror ~/Desktop ~/Documents/FileShows/mirror/Desktop/\$CURDATE/
ft rmdir --force ~/Documents/FileShows/mirror/Desktop/\$AGODATE1WEEK/
# ft rmdir --force --keeptop ~/Documents/FileShows/mirror/Desktop/ --time_type=changed --time_le='1 week ago'

T7GUI-元数据设置 (MetaData)

prefs-metadata-default

示例：

名称 (Name)：
Incremental Desktop Mirroring
描述 (Description)：
Mirrored the past week's desktop files incrementally to another directory.
作者 (Authors)：
crown.hg@gmail.com

T0GUI-macOS：桌面文件访问权限设置

为确保 FileShows 应用能够访问您的桌面文件：

前往 “系统设置” > “隐私与安全性”。
点击 “文件和文件夹”，找到 “FileShows” 并勾选 “桌面文件夹” 选项。
如果 “文件和文件夹” 中未列出 FileShows，请点击 “完全磁盘访问”，然后手动添加并启用 “FileShows” 应用。

完成以上设置后，请重启 FileShows 应用以确保更改生效。