gogcligog upload命令完全指南从本地文件上传到 Google Drive 与条件式内容替换【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog upload是 gogcli 中把本地文件上传到 Google Drive 的命令同时是drive upload的别名还支持up、put缩写它把新建上传和内容替换两种场景统一到一条命令里。本文以 docs/commands/gog-upload.md 为骨架结合 internal/cmd/drive_upload.go 的源码实现与 internal/cmd/drive_upload_replace_test.go 的测试用例完整讲解命令用法、每个 flag 的作用与限制、MIME 类型推断与格式转换规则、frontmatter 剥离逻辑以及基于版本号ETag的原子条件替换原理读完即可在生产与脚本场景中安全使用。命令概览gog upload上传本地文件到 Drive源文档将其定位为 alias for drive upload——也就是说它挂在gog drive命令组下见 internal/cmd/drive.go#L66 中Upload DriveUploadCmd的注册同时作为顶层命令暴露。该文档由gog schema --json自动生成页首注明 Generated fromgog schema --json. Do not edit this page by hand; runmake docs-commands因此文档中的 flag 列表与命令行实际行为保持一致。基本用法gog upload (up,put) localPath [flags]其中up、put是upload的别名。命令的父命令是 gog完整命令索引见 Command index。从源码看上传的执行入口是DriveUploadCmd.Runinternal/cmd/drive_upload.go#L159整体流程为解析参数 → 打开本地文件并确定大小 → 构造 dry-run 描述 → 按需走创建或替换或条件替换三条分支。一个最简上传示例gog upload ./report.pdf # 输出示例文本模式 # id 1abcXYZ... # name report.pdf # link https://drive.google.com/file/d/1abcXYZ.../view命令结束后会输出文件id、name以及可用的webViewLink详见writeDriveUploadResultinternal/cmd/drive_upload.go#L422。Flag 完整参考以下表格完整继承自原文档并补充了类型、默认值与语义说明Flag类型默认值说明--access-tokenstring直接使用提供的访问令牌绕过已存储的 refresh token令牌约 1 小时过期-a--account--acctstring指定账户邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth client 名称选择已存储的凭据 token bucket--colorstringauto颜色输出auto|always|never--convertbool根据文件扩展名自动转换为 Google 原生格式仅创建场景--convert-tostring转换为指定的 Google 格式doc|sheet|slides仅创建场景--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n--dry-run--dryrun--noop--previewbool不做实际修改打印将要执行的操作并以成功退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 范围--enable-commands-exactstring逗号分隔的精确启用命令列表点路径生效且父命令不会启用子命令-y--force--assume-yes--yesbool跳过破坏性命令的确认提示--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关-h--helpkong.helpFlag显示上下文相关帮助--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME--if-version*int64仅当当前 Drive 版本匹配时才替换使用原子前置条件若文件被改动则报告冲突需要--replace冲突时重新读取并重试-j--json--machineboolfalse输出 JSON 到 stdout最适合脚本化--keep-frontmatterboolMarkdown 转 Google Doc 时保留 YAML frontmatter---配合--convert或--convert-to doc默认剥离--keep-revision-foreverbool永久保留新的 head revision仅二进制文件--mime-typestring覆盖 MIME 类型推断--namestring覆盖文件名创建时或重命名目标替换时--no-input--non-interactive--noninteractivebool从不提示失败即报错适合 CI--parentstring目标文件夹 ID仅创建场景-p--plain--tsvboolfalse输出稳定的、可解析的纯文本到 stdoutTSV无颜色--quota-projectstring用于 API 计费的 Google Cloud 项目作为X-Goog-User-Project发送某些 API 在使用--access-token或 ADC 时需要它--readonlyboolfalse运行时阻止变更类 API 请求auth add也只会请求只读 OAuth scope--replacestring替换已存在 Drive 文件 ID 的内容保留共享链接/权限除非设置--if-version否则无条件替换--results-onlyboolJSON 模式下仅输出主要结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径。多数命令推荐使用--fields-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取的文本字段包裹在外部不可信内容标记中其中--access-token、--client、--quota-project、--readonly、--home、--enable-commands、--no-input等属于 internal/cmd/root.go 中的全局根 flag适用于所有命令而下面这些 flag 是upload特有的定义于DriveUploadCmdinternal/cmd/drive_upload.go#L25localPath位置参数必填本地文件路径--name创建时覆盖文件名 / 替换时重命名目标--parent目标文件夹 ID仅创建--replace要替换内容的已存在文件 ID--if-version条件替换的前置版本号要求--replace--mime-type覆盖 MIME 推断--keep-revision-forever永久保留 head revision仅二进制--convert/--convert-toGoogle 原生格式转换仅创建--keep-frontmatter转换时保留 YAML frontmatter上传模式一新建文件create不带--replace时命令创建新文件。核心实现在runDriveCreateUploadinternal/cmd/drive_upload.go#L299meta : drive.File{Name: opts.fileName} if opts.parent ! { meta.Parents []string{opts.parent} } call : svc.Files.Create(meta). SupportsAllDrives(true). Media(file, gapi.ContentType(opts.mimeType)). Fields(id, name, mimeType, size, webViewLink). Context(ctx)要点默认文件名未指定--name时使用本地文件的 base namefilepath.Base。指定父目录通过--parent folderId指定目标文件夹否则上传到根目录。支持共享盘所有 Drive 调用都设置了SupportsAllDrives(true)因此可以上传到 Shared Drive / 团队成员盘。返回字段id, name, mimeType, size, webViewLink其中webViewLink即网页查看地址。创建示例# 上传到根目录 gog upload ~/backup.tar.gz # 上传到指定文件夹 gog upload report.pdf --parent 1AbC...folderId # 自定义云端文件名 gog upload report.pdf --name 2026 年度报告.pdf # 指定 MIME 类型覆盖推断 gog upload data.bin --mime-type application/octet-streamMIME 类型推断规则未指定--mime-type时guessMimeTypeinternal/cmd/drive_upload.go#L52根据扩展名小写推断规则如下常量定义见 internal/cmd/drive.go#L26-L55扩展名MIME 类型.pdfapplication/pdf.docapplication/msword.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document.xlsapplication/vnd.ms-excel.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet.pptapplication/vnd.ms-powerpoint.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation.pngimage/png.jpg/.jpegimage/jpeg.gifimage/gif.txttext/plain.htmltext/html.csstext/css.jsapplication/javascript.jsonapplication/json.zipapplication/zip.csvtext/csv.mdtext/markdown其他application/octet-stream--mime-type的作用是覆盖这里的推断结果并通过gapi.ContentType(opts.mimeType)作为上传媒体类型发送。上传模式二替换已有文件内容replace--replace fileId用本地文件内容替换一个已存在的 Drive 文件其设计意图是保留原文件的 ID、共享链接与权限而不是新建文件。实现位于runDriveReplaceUploadinternal/cmd/drive_upload.go#L327gog upload new-version.pdf --replace 1AbC...fileId源码要点先Files.Get读取目标元数据id, mimeType拒绝替换 Google Workspace 原生文件若目标 MIME 以application/vnd.google-apps.开头如 Google Doc/Sheet/Slides直接报错cannot replace content for Google Workspace files——这些文件的内容不能通过上传媒体流覆盖相关校验逻辑见 internal/cmd/drive_upload.go#L336-L338通过Files.Update更新内容同样SupportsAllDrives(true)支持用--name顺带重命名目标文件meta.Name opts.fileName输出中额外带replaced true字段。替换模式的参数限制prepareDriveUpload中的校验internal/cmd/drive_upload.go#L234-L245--if-version必须与--replace一起使用否则报--if-version requires --replace且版本号必须为正整数--parent不能与--replace组合否则报--parent cannot be combined with --replace (use drive move)提示改用drive move--convert/--convert-to不能与--replace组合。上传模式三条件式替换--if-version原子防冲突--if-version n提供基于版本的前置条件替换解决多人协作中覆盖了别人刚改过的内容这一类竞态问题。核心实现在runDriveConditionalReplaceUploadinternal/cmd/drive_upload.go#L360。工作流程用 Drive v2 API 读取目标文件的id, mimeType, version, etag同样拒绝替换 Google Workspace 原生文件fail-closed 检查若元数据响应中没有 version 或 etagexisting.Version 0或 etag 为空直接报错并不做任何更新no update was attempted见 internal/cmd/drive_upload.go#L372-L378预检版本若existing.Version ! *opts.ifVersion报冲突conditional Drive replacement conflict ... expected version %d, current version is %d; re-read the file and reapply your edit不发请求原子更新通过Files.UpdateIf-Match: etag头发送服务端若发现文件已变化会返回 412 Precondition Failed代码将其映射为用户可读的冲突错误internal/cmd/drive_upload.go#L400-L411。原子性保障源码中的关键注释internal/cmd/drive_upload.go#L387-L390// Conditional replacement must be a single atomic attempt. ChunkSize(0) // prevents the generated client from switching large media to its internally // retrying resumable uploader, while the request context disables retries in // gogs authenticated RetryTransport. updateCtx : gogapi.WithoutRetries(ctx) call : svc.Files.Update(opts.replaceFileID, meta). SupportsAllDrives(true). Media(file, gapi.ContentType(opts.mimeType), gapi.ChunkSize(0)). Fields(id, title, mimeType, fileSize, alternateLink). Context(updateCtx)即ChunkSize(0)阻止大文件媒体走会自动重试的 resumable uploaderWithoutRetries关闭重试传输层配合If-Match保证一次尝试、要么成功要么冲突绝不会有后台重试造成二次覆盖。--keep-revision-forever在该分支映射为 v2 的Pinned(true)。该行为的测试覆盖非常完整internal/cmd/drive_upload_replace_test.goTestDriveUpload_ConditionalReplace_MatchingVersionUsesETagL421版本匹配时使用 ETag 头执行替换TestDriveUpload_ConditionalReplace_StaleVersionStopsBeforePatchL467版本过期时在发起更新前就停止TestDriveUpload_ConditionalReplace_PreconditionFailureIsConflictL503412 被识别为冲突TestDriveUpload_ConditionalReplace_RetryableFailureIsNotRetriedL557可重试错误也不会被自动重试TestDriveUpload_ConditionalReplace_LargeMediaUsesSingleRequestL621大媒体仍走单请求TestDriveUpload_ConditionalReplace_MissingPreconditionMaterialFailsClosedL677缺少 version/etag 时 fail-closed。典型用法是先读版本再条件写入的乐观锁模式先gog drive get fileId拿到当前版本号编辑后执行gog upload edited.md --replace 1AbC...fileId --if-version 42若返回冲突说明自读取版本号后文件已被他人修改需要重新读取最新内容后再决定是否重试。格式转换--convert 与 --convert-to仅创建场景不能与--replace组合支持把 Office/文本格式转换为 Google 原生格式。转换目标 MIME 常量定义见 internal/cmd/drive.go#L29-L31Google Docapplication/vnd.google-apps.documentGoogle Sheetapplication/vnd.google-apps.spreadsheetGoogle Slidesapplication/vnd.google-apps.presentation--convert-to doc|sheet|slides显式指定目标格式googleConvertTargetMimeTypeinternal/cmd/drive_upload.go#L114非法值报--convert-to: invalid value %q (use doc|sheet|slides)。--convert按扩展名自动判断目标格式googleConvertMimeTypeinternal/cmd/drive_upload.go#L98本地扩展名转换结果.docx、.docGoogle Doc.xlsx、.xls、.csvGoogle Sheet.pptx、.pptGoogle Slides.txt、.html、.mdGoogle Doc不支持的扩展名报--convert: unsupported file type %q (supported: docx, xlsx, pptx, doc, xls, ppt, csv, txt, html, md)。转换时的文件名处理stripOfficeExt与driveUploadRemoteNameinternal/cmd/drive_upload.go#L149、L262自动转换时若未显式指定--name会去掉 Office 扩展名使云端文件名更干净例如report.docx→reportGoogle Doc显式指定了--name则保留原名。# 按扩展名自动转换docx → Google Doc gog upload spec.docx --convert # 显式转换csv → Google Sheet gog upload data.csv --convert-to sheet # 保留显式名称 gog upload spec.docx --convert --name 产品规格书Markdown 与 YAML frontmatter 处理当上传 Markdowntext/markdown并触发转换--convert或--convert-to doc时默认会剥离文件头部的 YAML frontmatter---包裹的块因为 frontmatter 对 Google Doc 是噪音。判断条件见driveUploadShouldStripMarkdownFrontmatterinternal/cmd/drive_upload.go#L269return !keepFrontmatter opts.convert opts.mimeType mimeTextMarkdown剥离实现在stripYAMLFrontmatterinternal/cmd/drive_markdown_frontmatter.go#L13允许文件以 UTF-8 BOM 开头第一行 trim 后必须等于---随后找到下一个 trim 后为---的行即视为闭合找不到闭合分隔符则原样返回不剥离。剥离后文件大小按剥离结果重新计算见openDriveUploadMediainternal/cmd/drive_upload.go#L273。如需保留 frontmatter加--keep-frontmattergog upload post.md --convert --keep-frontmatter输出格式与脚本化使用命令支持三种输出形态由writeDriveUploadResult处理internal/cmd/drive_upload.go#L4221. 默认文本输出id/name/link键值对id 1AbC...fileId name report.pdf link https://drive.google.com/file/d/1AbC.../view替换场景额外输出replaced true并可用preservedFileId确认 ID 是否保留。2. 纯文本 TSV 输出-p/--plain/--tsv稳定可解析、无颜色适合 shell 管道。3. JSON 输出-j/--json/--machine结构化数据最适合脚本gog upload report.pdf -j # {file: {id: ..., name: ..., mimeType: ..., size: ..., webViewLink: ...}}替换场景 JSON 中还会出现replaced: true与preservedFileId: true/false。可配合--results-only只保留主结果、--select选择字段点路径详见上文的全局 flag 说明。CI / 无人值守--no-input保证任何需要交互提示的场景直接失败而非挂起--dry-run别名-n/--dryrun/--noop/--preview打印将要执行的操作描述含 path、name、parent、replace_file_id、mime_type、size、convert、convert_mime_type、keep_revision_forever、if_version 等字段而不实际写入构造逻辑见 internal/cmd/drive_upload.go#L172-L188。gog upload big.tar.gz --dry-run # 只预览 gog upload big.tar.gz --no-input -j # CI 中失败即报错参数校验与常见错误速查所有校验集中在prepareDriveUploadinternal/cmd/drive_upload.go#L209可据此快速排查报错报错信息含义与处理empty localPath位置参数为空必须提供本地文件路径--if-version requires --replace条件替换必须同时指定--replace--if-version must be a positive integer版本号必须为正整数--parent cannot be combined with --replace (use drive move)替换时不支持改父目录改目录请用drive move--convert/--convert-to cannot be combined with --replace转换仅限创建场景--convert-to: invalid value %q (use doc\|sheet\|slides)转换目标只能取doc/sheet/slides--convert: unsupported file type %q (...)扩展名不在可转换列表中cannot replace content for Google Workspace files (mimeType...)不允许用媒体流覆盖 Google 原生文档conditional Drive replacement conflict ... expected version N, current version M版本不匹配需重新读取后重试metadata response did not include a version/ETag; no update was attempted元数据缺失导致 fail-closed未执行任何更新另外本地路径支持config.ExpandPath展开~等--access-token的令牌约 1 小时过期长时间任务应优先使用存储的凭据或--client指定 OAuth client。测试与实现验证上传相关的行为有大量自动化测试保障均在 internal/cmd/drive_upload_replace_test.go替换场景TestDriveUpload_Replace_JSONL25、TestDriveUpload_Replace_TextL107验证 JSON/文本输出TestDriveUpload_Replace_ParentValidationL169验证--parent与--replace互斥TestDriveUpload_Replace_GoogleWorkspaceUnsupportedL192验证拒绝覆盖 Google 原生文件TestDriveUpload_Replace_ConvertValidationL238验证转换限制TestDriveUpload_Replace_KeepRevisionForeverAndMimeTypeL261验证--keep-revision-forever与 MIME 覆盖条件替换前述 6 个ConditionalReplace_*测试覆盖版本匹配、过期版本、412 冲突、禁止重试、大媒体单请求、fail-closeddry-runTestDriveUpload_IfVersionValidationAndDryRunL331同时覆盖--if-version的入参校验与 dry-run 描述输出创建场景TestDriveUpload_Create_KeepRevisionForeverL763验证创建时保留 revision。除单测外gog upload也被纳入端到端 dry-run 测试internal/cmd/dryrun_e2e_test.go与更多命令校验测试internal/cmd/drive_validation_more_test.go读者可以以此为模板扩展自己的脚本。小结gog upload用一条命令统一了 Drive 的新建上传与内容替换两类操作创建gog upload localPath [--parent id] [--name n] [--mime-type m]支持--convert/--convert-to转为 Google 原生格式并自动剥离 Markdown frontmatter可用--keep-frontmatter保留无条件替换gog upload localPath --replace fileId保留文件 ID 与共享权限但不能用于 Google 原生文件条件替换--replace fileId --if-version n基于 version/ETag 的原子更新适合乐观锁协作场景脚本化-j输出 JSON、-p输出 TSV、--no-input失败即报错、--dry-run安全预览。深入阅读推荐命令参考 docs/commands/gog-upload.md、父命令 gog、核心实现 internal/cmd/drive_upload.go、frontmatter 剥离 internal/cmd/drive_markdown_frontmatter.go、条件替换测试 internal/cmd/drive_upload_replace_test.go。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考