authelia-gen docs date 命令完全指南基于 Git 提交历史自动同步 Authelia 文档日期【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本指南围绕 Authelia 仓库中authelia-gen工具位于 cmd/authelia-gen的docs date子命令展开讲解其完整用法、全部命令行参数以及它如何通过 Git 提交历史为 Hugo 文档自动计算并回填 frontmatter 中的date字段。读完本文你将掌握该命令的调用方式、父命令持久标志的作用并能从 cmd_docs_date.go 的源码层面理解其“读取 frontmatter → 查询 Git 日志 → 回写日期”的完整实现链路。命令概述与适用场景authelia-gen docs date是 Authelia 文档自动生成工具链中的一个子命令官方定义其作用为Generate doc dates生成文档日期。它的职责非常聚焦扫描文档内容目录下的所有 Markdown 文件读取每个文件 frontmatter 中已有的date字段再通过git log查询该文件首次被加入仓库的提交时间最后用 Git 时间替换或校验frontmatter 中的日期。该命令解决了文档维护中的典型痛点当文档被迁移、复制或在较晚的提交中才正式纳入版本库时手工维护的date字段常常与实际提交时间不一致。docs date让文档的发布日期与 Git 历史严格对齐从而保证站点时间线、订阅排序等依赖 frontmatterdate的功能准确可靠。命令语法与本地选项该命令的基本语法为authelia-gen docs date [flags]本地选项Options选项类型默认值说明--commit-since stringstring空从哪个提交开始检查日志--commit-until stringstringHEAD检查日志截止到哪个提交默认HEAD-h, --helpbool—显示date命令的帮助信息其中--commit-since与--commit-until用于限定 Git 日志查询的提交范围。查看源码 cmd_docs_date.go 可以看到--commit-until的默认值在代码中被设置为fasthttp.MethodHead即字符串HEADcmd.Flags().String(commit-until, fasthttp.MethodHead, The commit to check the logs until) cmd.Flags().String(commit-since, , The commit to check the logs since)当且仅当显式指定了--commit-since时命令才会构造一个until...since形式的提交区间过滤器见下文实现原理。如果只设置--commit-until而不设置--commit-since则不会启用区间过滤。继承自父命令的选项与authelia-gen的其它子命令一样docs date会继承根命令cmd_root.go中定义的全部持久标志persistent flags这些标志决定命令运行时的路径与行为上下文实际使用中几乎总是需要配合--dir.root等路径参数运行路径类持久标志标志默认值说明-C, --cwd string空设置执行 git 命令的工作目录CWD-d, --dir.root string./仓库根目录--dir.docs stringdocs文档目录相对根目录--dir.docs.content stringcontent文档内容目录相对 docs 目录--dir.docs.adr stringreference/architecture-decision-logADR 数据目录--dir.docs.cli-reference stringreference/cliCLI 参考 Markdown 存储目录--dir.docs.data stringdata文档数据目录--dir.docs.static stringstatic文档静态文件目录--dir.docs.static.json-schemas stringschemas文档静态 JSONSchema 文件目录--dir.authentication stringinternal/authentication认证目录相对根目录--dir.locales stringinternal/server/locales语言文件目录相对根目录--dir.schema stringinternal/configuration/schema配置 schema 目录相对根目录--dir.web stringwebWeb 前端目录相对根目录需要特别指出docs date扫描的文档内容路径由--dir.root、--dir.docs、--dir.docs.content三个标志逐级拼接而成。源码中通过getPFlagPath辅助函数helpers.go按顺序用filepath.Join组合这三个值默认情况下即仓库中的docs/content目录。文件与模板类持久标志标志默认值说明--file.configuration-keys stringinternal/configuration/schema/keys.go配置键文件路径--file.commit-lint-config stringcommitlint.config.mjscommit lint JS 配置文件相对根目录--file.docs-commit-msg-guidelines stringdocs/content/contributing/guidelines/commit-message.md提交信息规范文档--file.docs.data.keys stringconfigkeys.json文档键数据文件--file.docs.data.languages stringlanguages.json语言文档数据相对 docs data 目录--file.docs.data.misc stringmisc.json杂项文档数据相对 docs data 目录--file.docs.static.json-schemas.configuration stringconfiguration配置 JSONSchema 路径--file.docs.static.json-schemas.exports.identifiers stringexports.identifiers标识符导出 JSONSchema 路径--file.docs.static.json-schemas.exports.totp stringexports.totpTOTP 导出 JSONSchema 路径--file.docs.static.json-schemas.exports.webauthn stringexports.webauthnWebAuthn 导出 JSONSchema 路径--file.docs.static.json-schemas.user-database stringuser-database用户数据库 JSONSchema 路径--file.bug-report string.github/ISSUE_TEMPLATE/bug-report.ymlBug 报告 issue 模板--file.feature-request string.github/ISSUE_TEMPLATE/feature-request.yml功能请求 issue 模板--file.scripts.gen stringcmd/authelia-scripts/cmd/gen.goauthelia-scripts gen 文件--file.server.generated stringinternal/server/gen.go服务端生成文件--file.web.i18n stringsrc/i18n/index.tsWeb i18n TS 配置相对 web 目录--file.web.package stringpackage.jsonNode 包配置相对 web 目录生成行为类持久标志标志默认值说明-X, --exclude strings—排除指定名称的生成器--latest—启用若干生成器如 JSON Schema 生成器的 latest 功能--next—启用若干生成器如 JSON Schema 生成器的 next 功能--package.configuration.keys stringschema键文件的包名--package.scripts.gen stringcmdauthelia-scripts gen 文件的包名--version-count int5输出模板中列出的最大次要版本数量--versions strings—指定生成器运行的版本特殊值current与next互斥这些持久标志大多服务于其它子命令如code、docs json-schemadocs date实际直接依赖的是其中的路径类标志--dir.root、--dir.docs、--dir.docs.content、--cwd其余标志作为统一 CLI 入口的一部分被继承展示。源码级实现原理docs date的完整逻辑集中在 cmd_docs_date.go 的docsDateRunE函数中整体是一个“遍历 → 解析 → 查 Git → 回写”的四步流水线1. 计算文档内容路径命令首先通过getPFlagPath将--dir.root、--dir.docs、--dir.docs.content三个标志值逐级拼接得到待扫描的文档内容绝对路径同时读取--cwd作为后续 git 命令的工作目录。2. 递归遍历 Markdown 文件使用filepath.Walk递归遍历内容目录仅处理以.md结尾的文件见 cmd_docs_date.go。对每个文件调用getFrontmatterhelpers.go它通过识别---分隔符常量delimiterLineFrontMatter见 const.go提取 frontmatter 原始字节。3. 解析并校验 frontmatter 的 date 字段frontmatter 字节被yaml.Unmarshal解析为map[string]any。若存在date键则断言其必须为time.Time类型否则返回带完整文件路径的错误信息frontmatter for %s has an invalid date value。这保证了写回操作前原日期格式合法cmd_docs_date.go。4. 从 Git 历史查询文件添加日期核心函数getDateFromGitcmd_docs_date.go构造并执行如下形式的 git 命令git [-C cwd] log [until...since] -1 --diff-filterA --prettyformat:%cD -- path各参数含义-C cwd切换 git 工作目录对应--cwd标志until...since当显式设置--commit-since时以fmt.Sprintf(%s...%s, commitUtil, commitSince)构造提交区间过滤器-1只取一条记录--diff-filterA只匹配**新增Added**该文件的提交这正是“文档首次入库时间”的语义来源--prettyformat:%cD输出提交者日期committer date格式为 RFC 2822-- path限定该文件路径。getTimeFromGitCmd随后用dateFmtRFC2822Mon, _2 Jan 2006 15:04:05 -0700见 const.go解析 git 输出若 git 命令执行失败或日期解析失败则返回nil。5. 回写 frontmatter 日期replaceDatescmd_docs_date.go将 Git 时间格式化为dateFmtYAML2006-01-02T15:04:05-07:00后调用replaceFrontMatterhelpers.go若 Git 查询成功用 Git 日期替换 frontmatter 中的date:行若 Git 查询失败如文件从未被-A记录或不在任何提交内则保留原 frontmatter 中的日期保证命令在历史数据缺失时也能幂等安全地运行替换仅发生在 frontmatter 区域两次---分隔符之间且仅匹配以date:前缀开头的行正文中的内容与格式不受影响。时间格式细节命令涉及两种时间格式理解它们的差异有助于排查问题常量格式串用途dateFmtRFC2822Mon, _2 Jan 2006 15:04:05 -0700解析git log --prettyformat:%cD的输出dateFmtYAML2006-01-02T15:04:05-07:00回写到 frontmatter 的date:字段ISO 8601 风格仓库中实际文档的 frontmatter 即采用第二种格式例如本参考页自身的date: 2026-04-02T15:48:2211:00见 authelia-gen_docs_date.md印证了写回格式与现有文档保持一致。与 docs 子命令族的关系docs date隶属于authelia-gen docs命令族。查看 cmd_docs.go 可知docs父命令共注册了六个子命令cmd.AddCommand(newDocsCLICmd(), newDocsDataCmd(), newDocsDateCmd(), newDocsSEOCmd(), newDocsJSONSchemaCmd(), newDocsManageCmd())即docs cli、docs data、docs date、docs seo、docs json-schema与docs manage分别负责 CLI 参考页生成、数据文件生成、日期同步、SEO 信息生成、JSON Schema 生成与托管文档管理。docs date的完整帮助入口为authelia-gen docs date --help相关命令详见 authelia-gen docs 参考页。实际使用示例在 Authelia 仓库根目录下最典型的用法是让 Git 日期与全部文档同步# 在仓库根目录运行扫描 docs/content 下所有 .md 文件并按首次提交时间回填 date authelia-gen docs date # 显式指定仓库根目录若从子目录调用 authelia-gen authelia-gen docs date -d /path/to/authelia # 限定 Git 日志查询区间从 v4.38.0 到 HEAD authelia-gen docs date --commit-since v4.38.0 --commit-until HEAD # 指定 git 命令的工作目录适用于 git 工作树与仓库根不一致的场景 authelia-gen docs date -C /path/to/authelia从 cmd_docs_date.go 的实现看只有当--commit-since被显式设置时提交区间才会生效单独使用默认参数时命令等价于对每个文件查询其在全部历史中首次添加的提交日期这是日常维护最常用、也最安全的调用方式。注意事项与局限只处理 frontmatter 合法的文件若date字段不是合法的time.Time命令会直接报错并指出具体文件路径便于定位问题依赖 Git 历史完整性文档日期完全来自git log --diff-filterA若仓库是浅克隆shallow clone或文件经由 squash 合并首次添加提交可能无法正确定位此时命令会保留原 frontmatter 日期而非报错修改的是仓库内文件replaceFrontMatter通过os.Create覆写原文件运行时会对文档内容目录内的 Markdown 文件就地写入建议在干净的工作区中执行并复核 git diff格式对齐写回日期使用2006-01-02T15:04:05-07:00的 ISO 8601 格式与仓库现有文档 frontmatter 约定一致可直接被 Hugo 解析。总体而言authelia-gen docs date是一个小而有用的工程化命令它把“文档发布时间”这一元数据从人工维护转变为由 Git 提交历史自动推导配合authelia-gen工具链中其它文档生成器构成了 Authelia 文档站点自动化维护的基础设施之一。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 authelia-gen docs date 命令完全指南：基于 Git 提交历史自动同步 Authelia 文档日期
authelia-gen docs date 命令完全指南基于 Git 提交历史自动同步 Authelia 文档日期【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本指南围绕 Authelia 仓库中authelia-gen工具位于 cmd/authelia-gen的docs date子命令展开讲解其完整用法、全部命令行参数以及它如何通过 Git 提交历史为 Hugo 文档自动计算并回填 frontmatter 中的date字段。读完本文你将掌握该命令的调用方式、父命令持久标志的作用并能从 cmd_docs_date.go 的源码层面理解其“读取 frontmatter → 查询 Git 日志 → 回写日期”的完整实现链路。命令概述与适用场景authelia-gen docs date是 Authelia 文档自动生成工具链中的一个子命令官方定义其作用为Generate doc dates生成文档日期。它的职责非常聚焦扫描文档内容目录下的所有 Markdown 文件读取每个文件 frontmatter 中已有的date字段再通过git log查询该文件首次被加入仓库的提交时间最后用 Git 时间替换或校验frontmatter 中的日期。该命令解决了文档维护中的典型痛点当文档被迁移、复制或在较晚的提交中才正式纳入版本库时手工维护的date字段常常与实际提交时间不一致。docs date让文档的发布日期与 Git 历史严格对齐从而保证站点时间线、订阅排序等依赖 frontmatterdate的功能准确可靠。命令语法与本地选项该命令的基本语法为authelia-gen docs date [flags]本地选项Options选项类型默认值说明--commit-since stringstring空从哪个提交开始检查日志--commit-until stringstringHEAD检查日志截止到哪个提交默认HEAD-h, --helpbool—显示date命令的帮助信息其中--commit-since与--commit-until用于限定 Git 日志查询的提交范围。查看源码 cmd_docs_date.go 可以看到--commit-until的默认值在代码中被设置为fasthttp.MethodHead即字符串HEADcmd.Flags().String(commit-until, fasthttp.MethodHead, The commit to check the logs until) cmd.Flags().String(commit-since, , The commit to check the logs since)当且仅当显式指定了--commit-since时命令才会构造一个until...since形式的提交区间过滤器见下文实现原理。如果只设置--commit-until而不设置--commit-since则不会启用区间过滤。继承自父命令的选项与authelia-gen的其它子命令一样docs date会继承根命令cmd_root.go中定义的全部持久标志persistent flags这些标志决定命令运行时的路径与行为上下文实际使用中几乎总是需要配合--dir.root等路径参数运行路径类持久标志标志默认值说明-C, --cwd string空设置执行 git 命令的工作目录CWD-d, --dir.root string./仓库根目录--dir.docs stringdocs文档目录相对根目录--dir.docs.content stringcontent文档内容目录相对 docs 目录--dir.docs.adr stringreference/architecture-decision-logADR 数据目录--dir.docs.cli-reference stringreference/cliCLI 参考 Markdown 存储目录--dir.docs.data stringdata文档数据目录--dir.docs.static stringstatic文档静态文件目录--dir.docs.static.json-schemas stringschemas文档静态 JSONSchema 文件目录--dir.authentication stringinternal/authentication认证目录相对根目录--dir.locales stringinternal/server/locales语言文件目录相对根目录--dir.schema stringinternal/configuration/schema配置 schema 目录相对根目录--dir.web stringwebWeb 前端目录相对根目录需要特别指出docs date扫描的文档内容路径由--dir.root、--dir.docs、--dir.docs.content三个标志逐级拼接而成。源码中通过getPFlagPath辅助函数helpers.go按顺序用filepath.Join组合这三个值默认情况下即仓库中的docs/content目录。文件与模板类持久标志标志默认值说明--file.configuration-keys stringinternal/configuration/schema/keys.go配置键文件路径--file.commit-lint-config stringcommitlint.config.mjscommit lint JS 配置文件相对根目录--file.docs-commit-msg-guidelines stringdocs/content/contributing/guidelines/commit-message.md提交信息规范文档--file.docs.data.keys stringconfigkeys.json文档键数据文件--file.docs.data.languages stringlanguages.json语言文档数据相对 docs data 目录--file.docs.data.misc stringmisc.json杂项文档数据相对 docs data 目录--file.docs.static.json-schemas.configuration stringconfiguration配置 JSONSchema 路径--file.docs.static.json-schemas.exports.identifiers stringexports.identifiers标识符导出 JSONSchema 路径--file.docs.static.json-schemas.exports.totp stringexports.totpTOTP 导出 JSONSchema 路径--file.docs.static.json-schemas.exports.webauthn stringexports.webauthnWebAuthn 导出 JSONSchema 路径--file.docs.static.json-schemas.user-database stringuser-database用户数据库 JSONSchema 路径--file.bug-report string.github/ISSUE_TEMPLATE/bug-report.ymlBug 报告 issue 模板--file.feature-request string.github/ISSUE_TEMPLATE/feature-request.yml功能请求 issue 模板--file.scripts.gen stringcmd/authelia-scripts/cmd/gen.goauthelia-scripts gen 文件--file.server.generated stringinternal/server/gen.go服务端生成文件--file.web.i18n stringsrc/i18n/index.tsWeb i18n TS 配置相对 web 目录--file.web.package stringpackage.jsonNode 包配置相对 web 目录生成行为类持久标志标志默认值说明-X, --exclude strings—排除指定名称的生成器--latest—启用若干生成器如 JSON Schema 生成器的 latest 功能--next—启用若干生成器如 JSON Schema 生成器的 next 功能--package.configuration.keys stringschema键文件的包名--package.scripts.gen stringcmdauthelia-scripts gen 文件的包名--version-count int5输出模板中列出的最大次要版本数量--versions strings—指定生成器运行的版本特殊值current与next互斥这些持久标志大多服务于其它子命令如code、docs json-schemadocs date实际直接依赖的是其中的路径类标志--dir.root、--dir.docs、--dir.docs.content、--cwd其余标志作为统一 CLI 入口的一部分被继承展示。源码级实现原理docs date的完整逻辑集中在 cmd_docs_date.go 的docsDateRunE函数中整体是一个“遍历 → 解析 → 查 Git → 回写”的四步流水线1. 计算文档内容路径命令首先通过getPFlagPath将--dir.root、--dir.docs、--dir.docs.content三个标志值逐级拼接得到待扫描的文档内容绝对路径同时读取--cwd作为后续 git 命令的工作目录。2. 递归遍历 Markdown 文件使用filepath.Walk递归遍历内容目录仅处理以.md结尾的文件见 cmd_docs_date.go。对每个文件调用getFrontmatterhelpers.go它通过识别---分隔符常量delimiterLineFrontMatter见 const.go提取 frontmatter 原始字节。3. 解析并校验 frontmatter 的 date 字段frontmatter 字节被yaml.Unmarshal解析为map[string]any。若存在date键则断言其必须为time.Time类型否则返回带完整文件路径的错误信息frontmatter for %s has an invalid date value。这保证了写回操作前原日期格式合法cmd_docs_date.go。4. 从 Git 历史查询文件添加日期核心函数getDateFromGitcmd_docs_date.go构造并执行如下形式的 git 命令git [-C cwd] log [until...since] -1 --diff-filterA --prettyformat:%cD -- path各参数含义-C cwd切换 git 工作目录对应--cwd标志until...since当显式设置--commit-since时以fmt.Sprintf(%s...%s, commitUtil, commitSince)构造提交区间过滤器-1只取一条记录--diff-filterA只匹配**新增Added**该文件的提交这正是“文档首次入库时间”的语义来源--prettyformat:%cD输出提交者日期committer date格式为 RFC 2822-- path限定该文件路径。getTimeFromGitCmd随后用dateFmtRFC2822Mon, _2 Jan 2006 15:04:05 -0700见 const.go解析 git 输出若 git 命令执行失败或日期解析失败则返回nil。5. 回写 frontmatter 日期replaceDatescmd_docs_date.go将 Git 时间格式化为dateFmtYAML2006-01-02T15:04:05-07:00后调用replaceFrontMatterhelpers.go若 Git 查询成功用 Git 日期替换 frontmatter 中的date:行若 Git 查询失败如文件从未被-A记录或不在任何提交内则保留原 frontmatter 中的日期保证命令在历史数据缺失时也能幂等安全地运行替换仅发生在 frontmatter 区域两次---分隔符之间且仅匹配以date:前缀开头的行正文中的内容与格式不受影响。时间格式细节命令涉及两种时间格式理解它们的差异有助于排查问题常量格式串用途dateFmtRFC2822Mon, _2 Jan 2006 15:04:05 -0700解析git log --prettyformat:%cD的输出dateFmtYAML2006-01-02T15:04:05-07:00回写到 frontmatter 的date:字段ISO 8601 风格仓库中实际文档的 frontmatter 即采用第二种格式例如本参考页自身的date: 2026-04-02T15:48:2211:00见 authelia-gen_docs_date.md印证了写回格式与现有文档保持一致。与 docs 子命令族的关系docs date隶属于authelia-gen docs命令族。查看 cmd_docs.go 可知docs父命令共注册了六个子命令cmd.AddCommand(newDocsCLICmd(), newDocsDataCmd(), newDocsDateCmd(), newDocsSEOCmd(), newDocsJSONSchemaCmd(), newDocsManageCmd())即docs cli、docs data、docs date、docs seo、docs json-schema与docs manage分别负责 CLI 参考页生成、数据文件生成、日期同步、SEO 信息生成、JSON Schema 生成与托管文档管理。docs date的完整帮助入口为authelia-gen docs date --help相关命令详见 authelia-gen docs 参考页。实际使用示例在 Authelia 仓库根目录下最典型的用法是让 Git 日期与全部文档同步# 在仓库根目录运行扫描 docs/content 下所有 .md 文件并按首次提交时间回填 date authelia-gen docs date # 显式指定仓库根目录若从子目录调用 authelia-gen authelia-gen docs date -d /path/to/authelia # 限定 Git 日志查询区间从 v4.38.0 到 HEAD authelia-gen docs date --commit-since v4.38.0 --commit-until HEAD # 指定 git 命令的工作目录适用于 git 工作树与仓库根不一致的场景 authelia-gen docs date -C /path/to/authelia从 cmd_docs_date.go 的实现看只有当--commit-since被显式设置时提交区间才会生效单独使用默认参数时命令等价于对每个文件查询其在全部历史中首次添加的提交日期这是日常维护最常用、也最安全的调用方式。注意事项与局限只处理 frontmatter 合法的文件若date字段不是合法的time.Time命令会直接报错并指出具体文件路径便于定位问题依赖 Git 历史完整性文档日期完全来自git log --diff-filterA若仓库是浅克隆shallow clone或文件经由 squash 合并首次添加提交可能无法正确定位此时命令会保留原 frontmatter 日期而非报错修改的是仓库内文件replaceFrontMatter通过os.Create覆写原文件运行时会对文档内容目录内的 Markdown 文件就地写入建议在干净的工作区中执行并复核 git diff格式对齐写回日期使用2006-01-02T15:04:05-07:00的 ISO 8601 格式与仓库现有文档 frontmatter 约定一致可直接被 Hugo 解析。总体而言authelia-gen docs date是一个小而有用的工程化命令它把“文档发布时间”这一元数据从人工维护转变为由 Git 提交历史自动推导配合authelia-gen工具链中其它文档生成器构成了 Authelia 文档站点自动化维护的基础设施之一。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考