diff --git a/apps/website/README.md b/apps/website/README.md index 281a5058..80f513c6 100644 --- a/apps/website/README.md +++ b/apps/website/README.md @@ -29,6 +29,24 @@ Notes: - `@algolia/client-search` is included in **package.json** dependencies only because `@docusaurus/preset-classic` includes it as a peer dependency. +## Managing translations + +Instructions for internationalization with Docusaurus: https://docusaurus.io/docs/i18n/introduction + +The supported locales for this project can be found in the `"i18n"` section of +[docusaurus.config.js](./docusaurus.config.js). + +> **NOTE:** Each locale is built as a distinct standalone single-page application. The localhost +> dev server builds only one locale at a time. To view multiple locales together, you must deploy +> the site. + +Common commands: + +- `rushx start --locale zh-cn` - launch the localhost dev server in the specified language. + +- `rushx write-translations --locale zh-cn` - Update the `i18n/*.json` files with any new strings. + + ## Deployment 1. If you will manually copy the files to a server, you can build the **apps/sparo/build** folder like this: diff --git a/apps/website/docs/index.md b/apps/website/docs/index.md index 44e5e129..a8a87e88 100644 --- a/apps/website/docs/index.md +++ b/apps/website/docs/index.md @@ -49,6 +49,10 @@ Try out Sparo in 5 easy steps: 2. For this demo, we'll use the Azure SDK which is a large public [RushJS](https://rushjs.io/) monorepo from GitHub. The following command will check out the [skeleton folders](./pages/reference/skeleton_folders.md) but not the source code: ```shell + # Globally install the Sparo CLI from NPM + npm install -g sparo + + # Use Sparo to clone your repository sparo clone https://github.com/Azure/azure-sdk-for-js.git cd azure-sdk-for-js diff --git a/apps/website/docs/pages/guide/getting_started.md b/apps/website/docs/pages/guide/getting_started.md index 8d8a149e..a53fec83 100644 --- a/apps/website/docs/pages/guide/getting_started.md +++ b/apps/website/docs/pages/guide/getting_started.md @@ -15,6 +15,10 @@ For macOS, we recommend to use [brew install git](https://git-scm.com/download/m Clone your [RushJS](https://rushjs.io/) monorepo: ```shell +# Globally install the Sparo CLI from NPM +npm install -g sparo + +# Use Sparo to clone your repository sparo clone https://github.com/my-company/my-monorepo.git cd my-monorepo diff --git a/apps/website/docs/pages/reference/skeleton_folders.md b/apps/website/docs/pages/reference/skeleton_folders.md index 68760f64..e9fd239c 100644 --- a/apps/website/docs/pages/reference/skeleton_folders.md +++ b/apps/website/docs/pages/reference/skeleton_folders.md @@ -2,9 +2,9 @@ title: Skeleton folders --- -By default `sparo clones` initializes a sparse checkout that does not include any Sparo profile selections, but does include folders containing essential config files such as **package-lock.yaml** and **package.json**. We call this starting point the checkout **"skeleton"** because it shows the full tree of all project folders in your monorepo, but without their source code subfolders. In other words, although the source files for each project are excluded, the skeleton nonetheless allows engineers to remain aware of other team's projects, and how their own project relates to those other projects. This discourages "tunnel vision" (where engineers pretend their project is the only project in the repository), while still ensuring fast Git performance. +By default `sparo clone` initializes a sparse checkout that does not include any Sparo profile selections, but does include folders containing essential config files such as **package-lock.yaml** and **package.json**. We call this starting point the checkout **"skeleton"** because it shows the full tree of all project folders in your monorepo, but without their source code subfolders. In other words, although the source files for each project are excluded, the skeleton nonetheless allows engineers to remain aware of other team's projects, and how their own project relates to those other projects. This discourages "tunnel vision" (where engineers pretend their project is the only project in the repository), while still ensuring fast Git performance. -Because Sparo enables the "cone mode" optimization for Git sparse checkout, the skeleton uses globs to match entire folders, not individual files. +Because Sparo enables the "cone mode" optimization for Git sparse checkout, the skeleton uses globs to match entire folders, not individual files. ## Skeleton spec diff --git a/apps/website/docusaurus.config.js b/apps/website/docusaurus.config.js index 812999ae..7f499f0a 100644 --- a/apps/website/docusaurus.config.js +++ b/apps/website/docusaurus.config.js @@ -32,7 +32,7 @@ const config = { // may want to replace "en" with "zh-Hans". i18n: { defaultLocale: 'en', - locales: ['en'] + locales: ['en', 'zh-cn'] }, plugins: [ @@ -40,7 +40,7 @@ const config = { require.resolve('docusaurus-lunr-search'), { // language codes - languages: ['en'] + languages: ['en', 'zh'] } ] ], diff --git a/apps/website/i18n/zh-cn/code.json b/apps/website/i18n/zh-cn/code.json new file mode 100644 index 00000000..801b208c --- /dev/null +++ b/apps/website/i18n/zh-cn/code.json @@ -0,0 +1,289 @@ +{ + "theme.ErrorPageContent.title": { + "message": "页面已崩溃。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "回到顶部", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "历史博文", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "历史博文", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "博文列表分页导航", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "较新的博文", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "较旧的博文", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "博文分页导航", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "较新一篇", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "较旧一篇", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "{count} 篇博文", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} 含有标签「{tagName}」", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "查看所有标签", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel": { + "message": "切换浅色/暗黑模式(当前为{mode})", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "暗黑模式", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "浅色模式", + "description": "The name for the light color mode" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "页面路径", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription": { + "message": "{count} 个项目", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "文件选项卡", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "上一页", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "下一页", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "{count} 篇文档带有标签", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged}「{tagName}」", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "版本:{versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版尚未发行的文档。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "此为 {siteTitle} {versionLabel} 版的文档,现已不再积极维护。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新的文档请参阅 {latestVersionLink} ({versionLabel})。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新版本", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "编辑此页", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "{heading}的直接链接", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "于 {date} ", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "由 {user} ", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最后{byUser}{atDate}更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "选择版本", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "找不到页面", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "标签:", + "description": "The label alongside a tag list" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "危险", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "信息", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "备注", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "提示", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "注意", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "关闭", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近博文导航", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.CodeBlock.copied": { + "message": "复制成功", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "复制代码到剪贴板", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "复制", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "切换自动换行", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "展开侧边栏分类 '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "折叠侧边栏分类 '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "主导航", + "description": "The ARIA label for the main navigation" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "选择语言", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.NotFound.p1": { + "message": "我们找不到您要找的页面。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "请联系原始链接来源网站的所有者,并告知他们链接已损坏。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "本页总览", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "阅读更多", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "阅读 {title} 的全文", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "阅读需 {readingTime} 分钟", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.breadcrumbs.home": { + "message": "主页面", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "收起侧边栏", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "文档侧边栏", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "关闭导航栏", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← 回到主菜单", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "切换导航栏", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "展开侧边栏", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "重试", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "跳到主要内容", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "标签", + "description": "The title of the tag list page" + }, + "theme.unlistedContent.title": { + "message": "未列出页", + "description": "The unlisted content banner title" + }, + "theme.unlistedContent.message": { + "message": "此页面未列出。搜索引擎不会对其索引,只有拥有直接链接的用户才能访问。", + "description": "The unlisted content banner message" + } +} diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json new file mode 100644 index 00000000..06443f90 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,30 @@ +{ + "version.label": { + "message": "下一个", + "description": "The label for version current" + }, + "sidebar.docsSidebar.category.Introduction": { + "message": "介绍", + "description": "The label for category Introduction in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.Reference": { + "message": "参考", + "description": "The label for category Reference in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.Config files": { + "message": "配置文件", + "description": "The label for category Config files in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.Commands": { + "message": "命令", + "description": "The label for category Commands in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.CI Commands": { + "message": "CI 命令", + "description": "The label for category CI Commands in sidebar docsSidebar" + }, + "sidebar.docsSidebar.category.Support": { + "message": "支持", + "description": "The label for category Support in sidebar docsSidebar" + } +} diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/index.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/index.md new file mode 100644 index 00000000..b9d5726f --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/index.md @@ -0,0 +1,112 @@ +--- +title: 概述 +hide_title: true +custom_edit_url: null +--- + +import { ThemedImage } from '@site/src/components/ThemedImage'; + +
+ +
+ + + +## 更快的克隆! + +Sparo 优化了 Git 操作在大型前端 monorepo 中的性能。 + + + +## 主要特点 + +- **熟悉的界面:** `sparo` 命令行工具 (CLI) 提供了 **更好的默认设置** 和 **性能建议**,而无需更改熟悉的 `git` 语法。(本地 `git` CLI 也受支持。) +- **经过验证的解决方案:** Git 提供了[许多优化大型仓库的基础能力](https://tiktok.github.io/sparo/pages/reference/git_optimization/); Sparo 基于这些能力提供上层的解决方案。 +- **简化的稀疏签出:** 使用稀疏签出[配置文件](https://tiktok.github.io/sparo/pages/guide/sparo_profiles/) 来定义文件签出范围,而不是复杂的 "cones" 和 globs。 +- **前端集成:** Sparo 利用了 [Rush](https://rushjs.io/) 和 [PNPM](https://pnpm.io/) 的工作区配置,甚至可以自动签出项目依赖项。 +- **双重工作流程:** `sparo-ci` 工具实现了一个专门为持续集成 (CI) 流水线优化的签出模型。 +- **额外的安全措施:** 避免常见的 Git 错误,例如在活动视图之外的暂存文件签出。 +- **超越 Git hooks:** 可选地收集您的 monorepo 中的匿名化 Git 计时数据,使您的构建团队能够为_本地_开发者体验(不仅仅是 CI)设定数据驱动的目标。 + + _(这些指标会传输到您自己的服务,其他任何方都无法访问。)_ + + + + +## 快速演示 + +只需五个简单步骤即可试用 Sparo: + +1. _**升级到最新的 Git 版本!**_ 对于 macOS,我们推荐使用 [brew install git](https://git-scm.com/download/mac)。对于其他操作系统,请参阅 [Git 文档](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) 了解安装说明。 + +2. 在此演示中,我们将使用 Azure SDK,这是 GitHub 上一个大型的公共 [RushJS](https://rushjs.io/) monorepo。以下命令将签出[骨架文件夹](./pages/reference/skeleton_folders.md),但不会签出源代码: + + ```shell + # 从 NPM 全局安装 Sparo CLI + npm install -g sparo + + # 使用 Sparo 克隆你的仓库 + sparo clone https://github.com/Azure/azure-sdk-for-js.git + + cd azure-sdk-for-js + ``` + + > 💡 目前支持 PNPM 和 Yarn 工作区的功能计划中,但尚未实现。欢迎贡献! + +3. 定义一个 [Sparo 配置文件](./pages/configs/profile_json.md),描述 Git 稀疏签出的仓库文件夹子集。 + + ```shell + # 将模板写入 common/sparo-profiles/my-team.json + sparo init-profile --profile my-team + ``` + + 编辑创建的 **my-team.json** 文件并添加以下选择器: + + **common/sparo-profiles/my-team.json** + ```json + { + "selections": [ + { + // 此演示配置文件将签出 "@azure/arm-commerce" 项目及其所有依赖项: + "selector": "--to", + "argument": "@azure/arm-commerce" + } + ] + } + ``` + `--to` [项目选择器](https://rushjs.io/pages/developer/selecting_subsets/#--to) 指示 Sparo 签出工作区中构建 `my-rush-project` 所需的所有依赖项。 + + + +4. 在保存 **my-team.json** 的更改后,现在是应用它的时候了: + + ```shell + sparo checkout --profile my-team + ``` + + 尝试一下!例如: + + ```shell + rush install + + # 构建应该成功,因为 Sparo 确保依赖项目被包含在稀疏签出中: + rush build --to @azure/arm-commerce + ``` + +5. 在日常工作中,考虑选择 [mirrored子命令](./pages/commands/overview.md),例如 `sparo revert` 而不是 `git revert`。Sparo 包装器提供 (1) 更好的默认设置,(2) 更好的性能建议,以及 (3) 可选的匿名化性能指标。 + + 示例: + + ```shell + sparo pull + + sparo commit -m "Example command" + ``` + +👍👍 这就是 **快速演示** 的全部内容。有关更详细的教程,请继续阅读 [入门指南](./pages/guide/getting_started.md)。 diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/overview.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/overview.md new file mode 100644 index 00000000..113bad33 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/overview.md @@ -0,0 +1,18 @@ +--- +title: 概述 +--- + +虽然日常开发涉及多种复杂的 Git 操作,例如在分支之间切换、从服务器获取增量更改以及浏览历史记录。但是相比之下,当持续集成 (CI) 流水线签出一个 Git 分支时,通常是一个更简单的操作。CI 执行任务过程中所用到的文件夹或整个虚拟机可能在作业完成后立即被丢弃。因此,这两种用例需要不同的 Git 优化方法。 + +Sparo 提供了一个单独的命令行工具 `sparo-ci`,专门针对 CI 流水线进行了优化。当前实现采用以下方法: + +- 使用 [treeless clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 而非 **blobless clone**,因为在 CI 环境会很少需要使用完整的 Git 历史记录。 + + _Shallow clone 是一种常见的替代方案,但在支持需要与基准分支进行比较的增量构建或发布操作时会遇到困难。_ + +- 配置了稀疏签出,并包含了[骨架文件夹](../reference/skeleton_folders.md)。 + +目前,`sparo-ci` 支持两个子命令用于 CI: + +- `sparo-ci checkout` +- `sparo-ci clone` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/sparo-ci_checkout.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/sparo-ci_checkout.md new file mode 100644 index 00000000..08a3c442 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/sparo-ci_checkout.md @@ -0,0 +1,16 @@ +--- +title: sparo-ci checkout +--- + +``` +sparo-ci checkout + +用于 CI 场景的签出命令。它目前只接受项目选择器,例如 --to 和 --from。 + +选项: + --help 显示帮助 [boolean] + -t, --to 查看 https://rushjs.io/pages/developer/selecting_subsets/#--to + 了解更多详情。 [array] + -f, --from 查看 https://rushjs.io/pages/developer/selecting_subsets/#--from + 了解更多详情。 [array] +``` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/sparo-ci_clone.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/sparo-ci_clone.md new file mode 100644 index 00000000..559753c5 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/ci_commands/sparo-ci_clone.md @@ -0,0 +1,18 @@ +--- +title: sparo-ci clone +--- + +``` +sparo-ci clone [directory] + +位置参数: + repository 要克隆的远程仓库地址。 [string] [required] + directory 要克隆到的新目录名称。如果未显式指定目录, + 将使用源仓库的“humanish”部分 + (对于 /path/to/repo.gitService 使用 repo,对于 + host.xz:foo/.gitService 使用 foo)。 + 仅当目录为空时才允许克隆到现有目录。 [string] + +选项: + --help 显示帮助 [boolean] +``` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/overview.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/overview.md new file mode 100644 index 00000000..a349df70 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/overview.md @@ -0,0 +1,80 @@ +--- +title: 概述 +--- + +`git` 命令行工具支持各种子命令,例如 `git clone`、`git checkout` 等。`sparo` 命令行旨在完全替代 `git`。 + +Sparo 有四种类型的子命令: + +1. **mirrored子命令**,例如 `sparo branch` 和 `sparo revert`,直接调用相应的 `git` 子命令。使用mirrored子命令的目的是让 Sparo 能够提供有关可能导致性能问题的参数的建议。此外,您还可以选择在 Sparo 中配置埋点数据收集,帮助您衡量在您的代码库中的使用体验。(收集的数据会发送到您自己的服务,其他任何人无法访问。) + +2. **增强子命令**,其基本设计与对应的 `git` 子命令相同,但针对稀疏签出配置文件和更高效的默认设置进行了调整。共有四个增强命令: + - `sparo checkout` + - `sparo clone` + - `sparo fetch` + - `sparo pull` + +3. **重命名子命令** 是四个增强子命令的mirrored版本,它们被重命名为添加了 `git-` 前缀: + - `sparo git-checkout` + - `sparo git-clone` + - `sparo git-fetch` + - `sparo git-pull` + +4. **辅助子命令** 是提供 Sparo 特定功能的新子命令。它们包括: + - `sparo auto-config` + - `sparo init-profile` + - `sparo list-profiles` + - `sparo inspect` _(尚未实现,将报告工作目录状态和诊断信息)_ + - `sparo reclone` _(尚未实现,将有效地恢复到干净的克隆状态)_ + +## mirrored命令 + +每个子命令在本文档中都有自己的页面,mirrored命令除外,它们已经在 Git 文档中进行了介绍。为了方便起见,下面的表格列出了最重要的["porcelain"](https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain)子命令,然而每个 Git 子命令都受支持。 + +| 子命令 | 概述 | +| --- | --- | +| [git add](https://git-scm.com/docs/git-add) | 将文件内容添加到索引 | +| [git am](https://git-scm.com/docs/git-am) | 从邮箱中应用一系列补丁 | +| [git archive](https://git-scm.com/docs/git-archive) | 从指定树创建文件归档 | +| [git bisect](https://git-scm.com/docs/git-bisect) | 使用二分查找找到引入错误的提交 | +| [git branch](https://git-scm.com/docs/git-branch) | 列出、创建或删除分支 | +| [git bundle](https://git-scm.com/docs/git-bundle) | 通过归档移动对象和引用 | +| [git checkout](https://git-scm.com/docs/git-checkout) | 切换分支或还原工作树文件 | +| [git cherry-pick](https://git-scm.com/docs/git-cherry-pick) | 应用某些现有提交引入的更改 | +| [git citool](https://git-scm.com/docs/git-citool) | 图形化替代 git-commit | +| [git clean](https://git-scm.com/docs/git-clean) | 从工作树中删除未跟踪的文件 | +| [git clone](https://git-scm.com/docs/git-clone) | 将仓库克隆到一个新目录中 | +| [git commit](https://git-scm.com/docs/git-commit) | 将更改记录到仓库 | +| [git describe](https://git-scm.com/docs/git-describe) | 基于可用引用为对象赋予一个可读名称 | +| [git diff](https://git-scm.com/docs/git-diff) | 显示提交之间的更改、提交与工作树之间的更改等 | +| [git fetch](https://git-scm.com/docs/git-fetch) | 从另一个仓库下载对象和引用 | +| [git format-patch](https://git-scm.com/docs/git-format-patch) | 为电子邮件提交准备补丁 | +| [git gc](https://git-scm.com/docs/git-gc) | 清理不必要的文件并优化本地仓库 | +| [git gitk](https://git-scm.com/docs/git-gitk) | Git 仓库浏览器 | +| [git grep](https://git-scm.com/docs/git-grep) | 打印匹配模式的行 | +| [git gui](https://git-scm.com/docs/git-gui) | Git 的可移植图形界面 | +| [git init](https://git-scm.com/docs/git-init) | 创建一个空的 Git 仓库或重新初始化现有的仓库 | +| [git log](https://git-scm.com/docs/git-log) | 显示提交日志 | +| [git maintenance](https://git-scm.com/docs/git-maintenance) | 运行任务以优化 Git 仓库数据 | +| [git merge](https://git-scm.com/docs/git-merge) | 将两个或多个开发历史合并在一起 | +| [git mv](https://git-scm.com/docs/git-mv) | 移动或重命名文件、目录或符号链接 | +| [git notes](https://git-scm.com/docs/git-notes) | 添加或查看对象注释 | +| [git pull](https://git-scm.com/docs/git-pull) | 从另一个仓库或本地分支获取并集成 | +| [git push](https://git-scm.com/docs/git-push) | 更新远程引用及其关联对象 | +| [git range-diff](https://git-scm.com/docs/git-range-diff) | 比较两个提交范围(例如分支的两个版本) | +| [git rebase](https://git-scm.com/docs/git-rebase) | 在另一个基底上重新应用提交 | +| [git reset](https://git-scm.com/docs/git-reset) | 将当前 HEAD 重置为指定状态 | +| [git restore](https://git-scm.com/docs/git-restore) | 恢复工作树文件 | +| [git revert](https://git-scm.com/docs/git-revert) | 撤销某些现有的提交 | +| [git rm](https://git-scm.com/docs/git-rm) | 从工作树和索引中删除文件 | +| [git shortlog](https://git-scm.com/docs/git-shortlog) | 总结 'git log' 输出 | +| [git show](https://git-scm.com/docs/git-show) | 显示各种类型的对象 | +| [git sparse-checkout](https://git-scm.com/docs/git-sparse-checkout) | 将工作树减少到跟踪文件的子集 | +| [git stash](https://git-scm.com/docs/git-stash) | 将脏的工作目录中的更改暂存 | +| [git status](https://git-scm.com/docs/git-status) | 显示工作树状态 | +| [git submodule](https://git-scm.com/docs/git-submodule) | 初始化、更新或查看子模块 | +| [git switch](https://git-scm.com/docs/git-switch) | 切换分支 | +| [git tag](https://git-scm.com/docs/git-tag) | 创建、列出、删除或验证使用 GPG 签名的标签对象 | +| [git worktree](https://git-scm.com/docs/git-worktree) | 管理多个工作树 | +| . . . | _...以及许多其他子命令,包括 shell `PATH` 中找到的任何自定义命令_ | + diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_auto-config.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_auto-config.md new file mode 100644 index 00000000..2dac6498 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_auto-config.md @@ -0,0 +1,34 @@ +--- +title: sparo auto-config +--- + +``` +sparo auto-config + +自动设置推荐的 Git 配置 + +选项: + -h, --help 显示帮助 [boolean] + --overwrite [boolean] [default: false] +``` + +通常,您不需要手动调用 `sparo auto-config`。顾名思义,它由 `sparo clone` 自动应用。该命令提供用于在用户可能手动更改了 Sparo 配置的情况下重新应用配置。当调查问题时,这是一个不错的第一步。 + +## 自动配置设置 + +实现可以在 [GitService.ts](https://github.com/tiktok/sparo/blob/main/apps/sparo-lib/src/services/GitService.ts) 中找到。以下是当前应用设置的摘要: + +``` +pull.rebase=true +fetch.prune=true +fetch.showForcedUpdates=false +feature.manyFiles=true +core.fsmonitor=true +core.fscache=true +core.untrackedcache=true +oh-my-zsh.hide-status=1 +oh-my-zsh.hide-dirty=1 +lfs.allowincompletepush=true +lfs.concurrenttransfers=32 +push.autoSetupRemote=true +``` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_checkout.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_checkout.md new file mode 100644 index 00000000..48089eff --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_checkout.md @@ -0,0 +1,33 @@ +--- +title: sparo checkout +--- + +``` +sparo checkout [branch] [start-point] + +更新工作树中的文件,以匹配索引或指定树中的版本。如果未提供路径规范, +git checkout 还将更新 HEAD,将指定分支设置为当前分支。 + +位置参数: + branch [string] + start-point [string] + +选项: + --help 显示帮助 [boolean] + -b 创建一个新分支,并在 处启动 [boolean] + -B 创建一个新分支,并在 处启动;如果已存在, + 将其重置到 [boolean] + --profile 根据指定的配置文件签出项目。这些配置文件将被记录, + 并被其他 sparo 命令重用。例如,在运行 "sparo checkout " + 后,会基于重用的配置文件进行稀疏签出 [array] [default: []] + --add-profile 使用记录的配置文件和指定的附加配置文件签出项目。 + 将指定的附加配置文件添加到 sparo 记录的配置文件中 [array] [default: []] + --no-profile 签出项目时不使用任何配置文件,并清除所有记录的配置文件 [boolean] + --to 签出项目直到(并包括)项目 ,可以与选项 --profile/--add-profile + 一起使用,以形成两个选项的并集选择。此处的项目选择器将 + 永远不会取代配置文件已签出的内容 [array] [default: []] + --from 签出项目从(包括其自身及其所有依赖项)项目 下游开始, + 可以与选项 --profile/--add-profile 一起使用, + 以形成两个选项的并集选择。此处的项目选择器将 + 永远不会取代配置文件已签出的内容 [array] [default: []] +``` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_clone.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_clone.md new file mode 100644 index 00000000..0b824297 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_clone.md @@ -0,0 +1,22 @@ +--- +title: sparo clone +--- + +``` +sparo clone [directory] + +位置参数: + repository 要克隆的远程仓库。 [string] [required] + directory 要克隆到的新目录名称。如果未明确指定目录名称,则使用源仓库的 + 名字部分(对于 /path/to/repo.gitService 使用 repo,对于 + host.xz:foo/.gitService 使用 foo)。仅当目录为空时,才允许克隆 + 到现有目录中。 [string] + +选项: + -h, --help 显示帮助 [boolean] + -s, --skip-git-config 默认情况下,Sparo 会自动配置您即将克隆的仓库的推荐 + git 设置。如果您不希望包含此步骤,可以使用输入参数 + --skip-git-config [boolean] [default: false] + -b, --branch 指定要克隆的分支 [string] + --profile [array] [default: []] +``` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_fetch.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_fetch.md new file mode 100644 index 00000000..01ad26e8 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_fetch.md @@ -0,0 +1,16 @@ +--- +title: sparo fetch +--- + +``` +sparo fetch [remote] [branch] + +将远程分支获取到本地 + +位置参数: + remote [string] + branch [string] + +选项: + -h, --help 显示帮助 [boolean] +``` diff --git a/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_git-checkout.md b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_git-checkout.md new file mode 100644 index 00000000..c49bd398 --- /dev/null +++ b/apps/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/pages/commands/sparo_git-checkout.md @@ -0,0 +1,17 @@ +--- +title: sparo git-checkout +--- + +这是 `git checkout` 的[mirrored子命令](./overview.md)。它具有与相应 Git 子命令相同的功能,但支持 Sparo 可选的匿名计时数据收集。 + +``` +sparo git-checkout [-q] [-f] [-m] [] +sparo git-checkout [-q] [-f] [-m] --detach [] +sparo git-checkout [-q] [-f] [-m] [--detach] +sparo git-checkout [-q] [-f] [-m] [[-b|-B|--orphan] ] [] +sparo git-checkout [-f|--ours|--theirs|-m|--conflict=