rclone touch 命令完全指南创建空文件与批量修正远程存储时间戳【免费下载链接】rclonersync for cloud storage - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone导读rclone touch是 rclone 中一条功能直接但底层实现颇具巧思的命令它的作用与 Unix/Linux 的touch一致——为一个或多个远程文件设置修改时间modification time当目标路径不存在时则自动创建零字节空文件。它尤其适合在对象存储、网盘等场景下“打占位标记”、为缓存类远程强制刷新、或对海量文件统一校准时间戳。阅读本文后你将掌握touch的全部自有参数时间戳格式、递归、禁用创建、元数据写入、它在递归模式下与过滤器/试运行体系的联动方式并能结合 cmd/touch/touch.go 源码理解其创建文件、更新时间与递归调度的真实执行链路。本文对应的命令参考文档为 docs/content/commands/rclone_touch.md该文件由cmd/touch/下的源码在发布时自动生成正文顶部亦有注明 autogenerated - DO NOT EDIT。命令自 v1.39 引入见源码 touch.go 中的versionIntroduced: v1.39注解。一、命令概述与基本用法命令的完整形态为rclone touch remote:path [flags]其核心语义只有一句话把remote:path指定的一个或多个文件的修改时间设置为当前时间。结合不同的参数还可以退化为以下行为若remote:path指向的文件不存在则创建一个零字节文件若同时带了--no-create或--recursive则不创建新文件若路径已存在且是目录则对目录内的文件修改时间是否递归取决于--recursive若指定了--timestamp则把时间设置为指定值而非当前时间创建新文件时可通过--metadata-set附带元数据。由于该命令直接操作远端对象的时间与存在性执行前建议先理解它在源码中的路径解析方式命令参数中remote:之后的部分会被fspath.Split拆成根与相对路径两部分见 newFsDst即使remote:path末尾带斜杠或以目录结尾也不会报错——这正是 touch 允许参数为目录路径的前提。二、touch 自有参数详解touch的专属参数只有 4 个均在 touch.go 的 init 函数 中注册参数简写默认值含义--no-create-Cfalse目标文件不存在时不创建使用--recursive时隐含启用--recursive-Rfalse递归处理路径下所有文件--timestamp string-t空即当前时间使用指定时间替代当前时间--localtime无false解析--timestamp时按本地时区而非 UTC以下逐一说明各参数的语义与使用边界。1.--timestamp/-t指定精确时间戳默认情况下 touch 将时间设为现在。如需设置为过去或未来的某个确定时刻使用--timestamp。该参数支持三种写法源码 parseTimeArgument 中定义了对应的三种 Go 时间布局常量写法格式说明示例YYMMDD6 位紧凑格式171030即 2017-10-30YYYY-MM-DDTHH:MM:SS秒级 ISO 风格长度 192006-01-02T15:04:05YYYY-MM-DDTHH:MM:SS.SSS纳秒级允许小数秒2006-01-02T15:04:05.123456789源码实现根据字符串长度自动选择解析布局长度恰好为 19 时使用秒级布局超过 19 时使用纳秒级布局2006-01-02T15:04:05.999999999末尾零会被自动裁掉否则回退到 6 位的YYMMDD。这意味着你不能用小时精度的中间格式例如2006-01-02这种不带时间成分的写法不会被接受。时区注意--timestamp的值默认按UTC解析。若你想按本地时区解释需要追加--localtime。在代码层面体现为time.ParseUTC与time.ParseInLocation(layout, ts, time.Local)本地时区的分支选择。2.--recursive/-R递归批量更新时间当remote:path指向一个目录时不指定--recursive只处理该目录自身层级下的对象非递归指定--recursive递归遍历该目录下找到的全部已存在文件逐个设置修改时间。递归模式有几个重要的联动特性绝不创建新文件递归只对已存在的文件生效隐含等价于--no-create支持过滤器--recursive生效时rclone 的过滤器体系--include/--exclude/--filter等会自动应用到被遍历的文件集合上试运行安全网递归会成批修改远端对象属于破坏性操作因此官方文档明确建议先用--dry-run空跑或--interactive/-i逐项交互确认验证过滤与范围再正式执行并发控制递归 touch 会按--transfers的取值并发处理文件见下文源码分析。3.--no-create/-C禁止创建新文件行为对照如下目标文件不存在且未加-C创建一个零字节文件唯一的例外是--recursive场景此时不创建目标文件不存在且加了-C跳过不创建、不报错仅在日志中提示 Not touching nonexistent file due to --no-create目标文件存在无论是否加-C都正常更新时间戳——-C只影响创建语义不影响更新语义。4.--localtime本地时区解释时间戳见上文--timestamp的时区说明默认按 UTC 解析加上--localtime后改用系统本地时区time.Local。三、创建文件时写入元数据--metadata-settouch在创建新文件时支持携带元数据命令形态为rclone touch remote:path -M --metadata-set keyvalue逐段拆解-M是--metadata的简写用于开启元数据处理能力命令行开关定义见 configflags.go--metadata-set keyvalue声明要写入的键值对这是一个可重复出现的参数可通过多次传参写入多条元数据底层解析逻辑位于 configflags.go 的 SetFlags 函数每条必须以分隔缺失会直接报错退出键名会被统一转为小写后再存入ci.MetadataSet。需要强调的是元数据能否真正落盘取决于远端后端的能力后端需具备用户元数据能力fs/features.go中定义的ReadMetadata/WriteMetadata/UserMetadata等 Feature见 features.go例如本地文件系统、S3、对象存储等支持元数据的后端可以生效而能力受限的后端会被跳过——对应测试 TestTouchWithMetadata 中if !features.UserMetadata { t.Skip(...) }的处理。四、命令执行入口与核心流程源码级拆解touch的命令逻辑集中在两个层次cmd/touch/touch.go负责单文件与入口调度fs/operations/operations.go提供目录递归实现。1. 入口与时间计算命令的Run回调touch.go严格校验参数必须恰好为 1 个cmd.CheckArgs(1, 1, ...)随后调用核心函数Touch。时间来源有两个分支timeOfTouch未提供--timestamp→time.Now()提供了--timestamp→ 按上一节的格式与时区规则解析解析失败会返回failed to parse timestamp argument错误。2. 三种路径状态的决策树核心函数 Touch 的完整执行流程如下先尝试f.NewObject获取目标对象路径为空例如remote:本身时直接按目录处理对象不存在fs.ErrorObjectNotFound路径为空目录 → 提示 Not touching empty directory 后结束带--no-create→ 日志提示后结束带--recursive→ 为保持一致性同样不创建日志提示后结束否则进入创建路径先经过operations.SkipDestructive的干跑/交互检查再调用 createEmptyObject——它通过object.NewStaticObjectInfo构造一个长度为 0 的静态对象交给f.Put真正写入后端并把这个静态对象的modTime设为 touch 时间对象是目录fs.ErrorIsDir按recursive布尔值进入operations.TouchDir对象存在且是普通文件经SkipDestructive检查后调用file.SetModTime(ctx, t)直接更新时间戳。3. 目录递归并发 深度控制目录场景最终落在 operations.TouchDir。它的关键实现要点是通过walk.ListR遍历目录条目并以ConfigMaxDepth控制深度深度规则见 ConfigMaxDepth非递归时最大深度强制为 1递归时则放开为--max-depth默认 -1即不限深度使用errgroupg.SetLimit(ci.Transfers)实现并发默认同时 touch 的文件数与--transfers一致rclone 默认--transfers为 4这与命令文档中 This will touch--transfersfiles concurrently 的描述完全对应每个文件修改时间失败时调用fs.CountError计数并记录错误日志全部完成后统一g.Wait()汇总。4. 干跑与交互确认创建与更新时间戳都属于破坏性写操作统一经过 SkipDestructive 把关--dry-run被设置时所有 touch 写操作一律跳过并输出日志 Skipped ... as --dry-run is set--interactive-i被设置时会弹出逐项确认选择结果会被缓存复用同一动作只询问一次两者均未设置时才真正执行写操作。五、常用共享参数除touch自有参数外本命令还与其他命令共享下列参数组在命令帮助中touch被标记为属于 Filter、Listing、Important 三个选项组见 touch.go 的 Annotations。1. Important 选项通用关键参数参数简写含义--dry-run-n试运行不做任何永久性修改在 touch 的递归批量场景中强烈推荐先用它验证范围--interactive-i开启交互模式破坏性操作前逐项询问--verbose-v输出更多日志可重复使用-vv进入调试级此外 rclone 还有大量不在本文展开的全局选项可通过rclone help flags查看。2. Filter 选项递归 touch 的过滤器在--recursive遍历时以下过滤参数可精确圈定要更新时间戳的文件集参数含义--delete-excluded同步时删除被排除的 dest 文件此处仅作语法继承说明--exclude stringArray/--exclude-from按模式排除文件 / 从文件-表示 stdin读取排除规则--exclude-if-present若目录中存在指定文件名则排除该目录--files-from/--files-from-raw/--files-from0从文件读源文件名清单raw 不做行处理0以 NUL 分隔--filter/--filter-from增加过滤规则 / 从文件读过滤规则--hash-filter按文件名哈希k/n或随机/n分区--ignore-case过滤时忽略大小写--include/--include-from按模式包含文件 / 从文件读取包含规则--max-age/--min-age仅处理更年轻 / 更老于指定时长的文件支持s/ms/m/h/d/w/M/y后缀--max-depth限制递归深度默认 -1不限--max-size/--min-size仅处理更小 / 更大尺寸的文件--metadata-exclude(-from)/--metadata-filter(-from)/--metadata-include(-from)按元数据模式过滤典型组合如只把某目录下 30 天前的.log文件时间统一为指定时刻rclone touch --recursive --include *.log --min-age 30d \ --timestamp 20240101 --dry-run remote:logs/3. Listing 选项列目录相关语法继承参数含义--default-time Time当文件/目录修改时间未知时展示的时间默认2000-01-01T00:00:00Z--fast-list若后端支持则使用递归列表占用更多内存但事务更少六、测试验证这些行为都是有据可查的cmd/touch/touch_test.go 中的用例逐一锁定了上述行为可用于对照印证测试函数验证的行为TestTouchOneFile对一个不存在的路径执行 touch能创建出文件TestTouchWithNoCreateFlag开启--no-create后不再创建新文件TestTouchWithTimestamp/TestTouchWithLongerTimestampYYMMDD与完整秒级时间戳两种格式均能被正确解析并写入TestTouchUpdateTimestamp对已存在文件 touch 只更新时间戳内容保持不变写入 aaa 后校验仍在TestTouchUpdateTimestampWithCFlag-C不影响已存在文件的更新时间戳TestTouchCreateMultipleDirAndFiletouch 一个深层不存在的路径a/b/c.txt时会自动创建中间目录a、a/b与空文件TestTouchEmptyName/TestTouchEmptyDir空路径、空目录不会产生副作用TestTouchDirWithFiles/TestRecursiveTouchDirWithFiles目录内及递归深层文件被批量处理TestTouchWithMetadata元数据写入仅在支持UserMetadata的后端执行测试通过ci.Metadataci.MetadataSet注入键值并回读校验七、典型实战场景综合上述全部行为rclone touch的典型用途可归纳为三类占位 / 标记文件在存储桶或网盘路径上快速放置零字节文件作为标记或锁例如rclone touch gdrive:backup/.in_progress统一校准历史时间戳迁移或对齐数据后把某个子树所有文件时间批量归一到指定 UTC 时刻先干跑后正式执行rclone touch -R --timestamp 2025-06-01T00:00:00 --dry-run remote:photos/ rclone touch -R --timestamp 2025-06-01T00:00:00 remote:photos/按过滤条件精准触碰借助过滤器 --interactive把修改范围缩小到特定后缀、特定年龄的文件避免误伤rclone touch -R -i --include *.mp4 --min-size 100M remote:videos/无论哪种场景只要涉及递归或新建文件都建议先用--dry-run/-i校验路径与过滤范围在了解后端元数据能力的前提下--metadata-set还能让空文件从创建之初就携带所需的键值标记。如果你需要对照其他命令文档可参考 rclone 主命令帮助文档。【免费下载链接】rclonersync for cloud storage - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files项目地址: https://gitcode.com/GitHub_Trending/rc/rclone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考