{"id":17584726,"url":"https://github.com/cssmagic/kup","last_synced_at":"2025-04-28T16:23:02.831Z","repository":{"id":39605419,"uuid":"491373351","full_name":"cssmagic/kup","owner":"cssmagic","description":"A CLI tool to sync local Markdown files to GitHub issues.","archived":false,"fork":false,"pushed_at":"2024-09-11T03:45:08.000Z","size":30,"stargazers_count":7,"open_issues_count":11,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T08:14:34.890Z","etag":null,"topics":["cli","github-issue","markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cssmagic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-12T05:16:01.000Z","updated_at":"2025-02-01T18:58:57.000Z","dependencies_parsed_at":"2024-10-22T23:03:02.022Z","dependency_job_id":null,"html_url":"https://github.com/cssmagic/kup","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"9ffe9890f054d893036cc4a16b46365016dca1fa"},"previous_names":["cssmagic/tou"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cssmagic%2Fkup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cssmagic","download_url":"https://codeload.github.com/cssmagic/kup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251343148,"owners_count":21574314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","github-issue","markdown"],"created_at":"2024-10-22T02:07:53.363Z","updated_at":"2025-04-28T16:23:02.813Z","avatar_url":"https://github.com/cssmagic.png","language":"JavaScript","readme":"# Kup\n\n\u003cimg src=\"https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png\" width=\"150\" height=\"80\" align=\"right\" alt=\"Kup logo\"\u003e\n\n\u003e A CLI tool to sync local Markdown files to GitHub issues.\n\u003e\n\u003e 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。\n\n## 谁需要它\n\n* 利用 GitHub issue 写博客的作者们，可以方便地在本地编辑原稿，并随时发布新博文或更新已有博文。\n* 通过 GitHub issue 发布文档的开源软件作者们，可以把代码仓库中的文档更新到指定 issue。\n* 其它需要频繁更新 GitHub issue 的人。\n\n\n## 安装\n\n需要全局安装，以便随时在命令行调用：\n\n```sh\nnpm i -g kup-cli\n```\n\n（当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）\n\n\n## 使用方法\n\n### 发布新 issue\n\n```sh\nkup ./path/to/file.md --repo foo/bar\n```\n\nKup 会把 `file.md` 文件的内容发布为 `foo/bar` 仓库的一个新 issue，发布成功后会告知新 issue 的编号。\n\n### 更新已有 issue\n\n```sh\nkup ./path/to/file.md --repo foo/bar --id 123\n```\n\nKup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123` 的 issue。\n\n### 准备工作\n\n操作 GitHub issue 是需要权限认证的，因此你需要向 Kup 提供 GitHub token，以便 Kup 调用 GitHub API。\n\n1. 在 GitHub 的 “[Personal access tokens](https://github.com/settings/tokens)” 页面生成一个新 token，权限范围需要选中 “repo”。（详细说明参见 [这篇文档](https://github.com/cssmagic/kup/issues/17)。）\n\n2. 把获取到的 token 写入环境变量：\n\n\t```sh\n\texport GITHUB_TOKEN=ghp_**********\n\t```\n\n如果 Kup 未能从环境变量获取 token，会在命令行向你询问。\n\n\n## 命令行参数\n\n参数 | 短名 | 值类型 | 含义 | 备注\n---|---|---|---|---\n`--repo` | `-r` | 字符串 | 指定 GitHub 仓库\n`--id` | `-i` | 整数 | 指定 issue 的编号 | \u003cli\u003e指定编号表示更新已有 issue\u003cli\u003e未指定编号则表示发布新 issue\n`--version` | `-v` | - | 显示版本号\n`--help` | `-h` | - | 显示帮助信息\n\n\n## 进阶\n\n### 如何更方便地指定 `repo` 参数？\n\n有以下方式可以指定 `repo` 参数，优先级递减：\n\n1. 调用命令行时指定的 `--repo` 参数。\n1. Markdown 文件内的 [元数据](https://github.com/cssmagic/kup/issues/1) 的 `repo` 字段。\n1. 当前项目的 `package.json` 文件内的 `kup.repo` 字段。Kup 会从当前目录向上逐级寻找 `package.json` 文件。\n\n如果整个项目的同步目标都是同一个仓库，则可以采用最后一种方式统一指定 `repo` 参数。\n\n### 如何更方便地指定 `id` 参数？\n\n有以下方式可以指定 `id` 参数，优先级递减：\n\n1. 调用命令行时指定的 `--id` 参数。\n1. Markdown 文件内的元数据的 `id` 字段。\n\n当一个文件发布成功后，建议立即把 id 写入它的元数据。\n\n### Issue 的标题是怎么确定的？\n\nKup 通过以下线索来确定 issue 的标题，优先级递减：\n\n1. Markdown 文件内的元数据的 `title` 字段。\n1. Markdown 正文的第一个标记如果是一级标题（`# Title` 格式），则取它的内容。\n\n如果通过以上方式无法确定 issue 标题，Kup 会怎么处理？\n\n* 如果是在发布新 issue，则 Kup 会自己生成一个标题。\n* 如果是在更新已有 issue，则 Kup 会忽略标题（也就是说，不会修改已有标题）。\n\n### 如何为 issue 指定 label？\n\n不论是在写博客，还是在发表 issue，你常常都会有打标签的需求。于是 Kup 也实现了这个功能。\n\n你需要在 Markdown 文件的元数据中添加 `tags` 字段，指定一个或多个 label。这些 label 不需要事先在 GitHub 仓库里创建好——如果你指定了不存在的 label，会在发布 issue 时自动创建。\n\n如果元数据中没有 `tags` 字段，Kup 会怎么处理？\n\n* 如果是在发布新 issue，则 Kup 不会为 issue 设置任何 label。\n* 如果是在更新已有 issue 时，Kup 会忽略标签（也就是说，不会修改已有标签）。\n\n在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。\n\n## 文档\n\n* [Markdown 文件内的元数据示例](https://github.com/cssmagic/kup/issues/1)\n* [如何为 Kup 生成合适的 GitHub token](https://github.com/cssmagic/kup/issues/17)\n\n\n## 其它\n\n### 开发计划\n\n请参考 [本项目的 issue](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)。欢迎提出你的需求，或参与 RFC 讨论。\n\n### 关于名字\n\n* Kup 取自 “皮卡” 的英文词 pickup，喻意是 “轻便地运载”。\n* Kup 是变形金刚人物 “杯子” 的英文名。\n\n### 关于 Logo\n\n* 作者 [Fasil](https://freeicons.io/profile/722)，由 [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893) 免费提供。\n\n***\n\n## License\n\n\u003e Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.\n\u003e\n\u003e 任何贡献到本项目的代码，均视为授权本项目作者及其名下公司用于商业用途、并按本项目协议分发。\n\nMIT\n","funding_links":[],"categories":["工具"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssmagic%2Fkup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcssmagic%2Fkup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcssmagic%2Fkup/lists"}