Merge pull request #407 from zong-zhe/add-private-repo

Peefy · web-flow · commit e3e70ed39db5 · 2024-07-09T00:09:30.000+08:00
feat: add doc for integration with private git repo or oci registry
diff --git a/docs/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md b/docs/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md
@@ -0,0 +1,65 @@
+# Integrate Private Git Repo and OCI Registry
+
+KCL package management tool supports saving and sharing KCL modules through the OCI registry and Git repository. This section will introduce how to integrate the KCL package management tool with the private OCI registry and Git repository.
+
+## Private Git Repository
+
+KCL package management tool depends on the Git tool in the local environment to interact with the Git repository. Therefore, before using the KCL package management tool, ensure the Git tool is installed in the local environment and the Git command can be found in the environment variable $PATH.
+
+More Details - [How to Install Git Tool](https://git-scm.com/downloads)
+
+KCL package management tool shares the same login credentials with the Git tool in the local environment. When you use the KCL package management tool to interact with a private Git repository, you need to check whether the Git tool can interact with the private Git repository normally. If you can successfully download the private Git repository using the `git clone` command, you can directly use the KCL package management tool without any login operation.
+
+More Details - [Download Private Repository Using Git](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## Private OCI Registry
+
+The KCL package management tool supports saving and sharing KCL packages through private OCI Registries. mainly including two parts.
+
+1. Login to the private OCI Registry using the `kcl registry login` command.
+
+    More Details - [kcl registry login Login OCI Registry](https://www.kcl-lang.io/docs/tools/cli/package-management/command-reference/login)
+
+2. Replace the OCI Registry used by the KCL package management tool. The KCL package management tool supports specifying the OCI registry used to download KCL packages in three ways.
+
+    - Use the OCI Url to specify the OCI registry in the command line or `kcl.mod`.
+
+      You can specify the OCI Registry as `ghcr.io` by the following command.
+
+      ```shell
+      kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+      ```
+
+      Or add the following content to the `kcl.mod` file to specify the OCI Registry as `ghcr.io`.
+
+      ```toml
+      helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
+      ```
+
+    - By environment variable
+
+      You can adjust the configuration of the OCI Registry by setting the three environment variables `KPM_REG`, `KPM_REGO`, and `OCI_REG_PLAIN_HTTP`.
+
+      ```shell
+      # set default registry
+      export KPM_REG="ghcr.io"
+      # set default repository
+      export KPM_REPO="kcl-lang"
+      # set support for 'http'
+      export OCI_REG_PLAIN_HTTP=off
+      ```
+
+    - By configuration file
+
+      The configuration file of the KCL package management tool is located at `$KCL_PKG_PATH/.kpm/config/kpm.json`, if the environment variable `KCL_PKG_PATH` is not set, it is saved by default in `$HOME/.kcl/kpm/.kpm/config/kpm.json`.
+
+      The default content of the configuration file is as follows:
+
+      ```json
+      {
+        "DefaultOciRegistry": "ghcr.io",
+        "DefaultOciRepo": "kcl-lang",
+        "DefaultOciPlainHttp": true
+      }
+      ```
+
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md
@@ -0,0 +1,64 @@
+# 集成私有的 Git Repo 与 OCI registry
+
+KCL 包管理工具支持通过 OCI registry 和 Git 仓库保存和分享 KCL 包。本文将介绍如何使用 KCL 包管理工具与私有 OCI registry 和 Git 仓库集成。
+
+## 私有 Git 仓库
+
+KCL 包管理工具依赖本地环境中的 Git 工具完成与 Git 仓库的交互。因此，在使用 KCL 包管理工具之前，确保本地环境中完成了 Git 工具的安装，并且在环境变量 $PATH 中能够找到 Git 命令。
+
+更多信息 - [如何安装 Git 工具](https://git-scm.com/downloads)
+
+KCL 包管理工具与本地环境中的 Git 工具公用一份登录凭证，当您使用 KCL 包管理工具与私有 Git 仓库交互时，您需要先检查 Git 工具能否正常与私有 Git 仓库交互。如果您使用 `git clone` 命令能够成功下载私有 Git 仓库，您可以直接使用 KCL 包管理工具而不需要进行任何登录操作。
+
+更多信息 - [使用 Git 下载私有仓库](https://docs.github.com/zh/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## 私有 OCI Registry
+
+关于私有的 OCI Registry, 主要包括两个部分
+
+1. 需要先使用 `kcl registry login` 命令登录私有 Registry。
+
+    更多信息 - [kcl registry login 登录 OCI registry](https://www.kcl-lang.io/zh-CN/docs/tools/cli/package-management/command-reference/login)
+
+2. 更换 KCL 包管理工具使用的 OCI Registry，KCL 包管理工具支持通过三种方式指定下载 KCL 包时使用的 OCI registry.
+
+    - 命令行或者 kcl.mod 中使用 OCI Url 指定使用的 OCI registry
+
+      你可以通过以下命令行，指定 OCI Registry 为`ghcr.io`。
+
+      ```shell
+      kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+      ```
+
+      或者在 `kcl.mod` 文件中添加如下内容，指定 OCI Registry 为`ghcr.io`。
+
+      ```toml
+      helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
+      ```
+
+    - 通过环境变量
+
+      你可以通过设置三个环境变量 KPM_REG、KPM_REGO 和 OCI_REG_PLAIN_HTTP 来调整配置。
+
+      ```shell
+      # 设置默认仓库地址
+      export KPM_REG="ghcr.io"
+      # 设置默认仓库
+      export KPM_REPO="kcl-lang"
+      # 设置支持 'http'
+      export OCI_REG_PLAIN_HTTP=off
+      ```
+
+    - 通过配置文件
+
+      KCL 包管理工具的配置文件位于 `$KCL_PKG_PATH/.kpm/config/kpm.json`，如果环境变量 `KCL_PKG_PATH` 没有设置，它默认保存在 `$HOME/.kcl/kpm/.kpm/config/kpm.json`。
+
+      配置文件的默认内容如下：
+
+      ```json
+      {
+        "DefaultOciRegistry": "ghcr.io",
+        "DefaultOciRepo": "kcl-lang",
+        "DefaultOciPlainHttp": true
+      }
+      ```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md
@@ -0,0 +1,64 @@
+# 集成私有的 Git Repo 与 OCI registry
+
+KCL 包管理工具支持通过 OCI registry 和 Git 仓库保存和分享 KCL 包。本文将介绍如何使用 KCL 包管理工具与私有 OCI registry 和 Git 仓库集成。
+
+## 私有 Git 仓库
+
+KCL 包管理工具依赖本地环境中的 Git 工具完成与 Git 仓库的交互。因此，在使用 KCL 包管理工具之前，确保本地环境中完成了 Git 工具的安装，并且在环境变量 $PATH 中能够找到 Git 命令。
+
+更多信息 - [如何安装 Git 工具](https://git-scm.com/downloads)
+
+KCL 包管理工具与本地环境中的 Git 工具公用一份登录凭证，当您使用 KCL 包管理工具与私有 Git 仓库交互时，您需要先检查 Git 工具能否正常与私有 Git 仓库交互。如果您使用 `git clone` 命令能够成功下载私有 Git 仓库，您可以直接使用 KCL 包管理工具而不需要进行任何登录操作。
+
+更多信息 - [使用 Git 下载私有仓库](https://docs.github.com/zh/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## 私有 OCI Registry
+
+关于私有的 OCI Registry, 主要包括两个部分
+
+1. 需要先使用 `kcl registry login` 命令登录私有 Registry。
+
+    更多信息 - [kcl registry login 登录 OCI registry](https://www.kcl-lang.io/zh-CN/docs/tools/cli/package-management/command-reference/login)
+
+2. 更换 KCL 包管理工具使用的 OCI Registry，KCL 包管理工具支持通过三种方式指定下载 KCL 包时使用的 OCI registry.
+
+    - 命令行或者 kcl.mod 中使用 OCI Url 指定使用的 OCI registry
+
+      你可以通过以下命令行，指定 OCI Registry 为`ghcr.io`。
+
+      ```shell
+      kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+      ```
+
+      或者在 `kcl.mod` 文件中添加如下内容，指定 OCI Registry 为`ghcr.io`。
+
+      ```toml
+      helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
+      ```
+
+    - 通过环境变量
+
+      你可以通过设置三个环境变量 KPM_REG、KPM_REGO 和 OCI_REG_PLAIN_HTTP 来调整配置。
+
+      ```shell
+      # 设置默认仓库地址
+      export KPM_REG="ghcr.io"
+      # 设置默认仓库
+      export KPM_REPO="kcl-lang"
+      # 设置支持 'http'
+      export OCI_REG_PLAIN_HTTP=off
+      ```
+
+    - 通过配置文件
+
+      KCL 包管理工具的配置文件位于 `$KCL_PKG_PATH/.kpm/config/kpm.json`，如果环境变量 `KCL_PKG_PATH` 没有设置，它默认保存在 `$HOME/.kcl/kpm/.kpm/config/kpm.json`。
+
+      配置文件的默认内容如下：
+
+      ```json
+      {
+        "DefaultOciRegistry": "ghcr.io",
+        "DefaultOciRepo": "kcl-lang",
+        "DefaultOciPlainHttp": true
+      }
+      ```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.8/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.8/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md
@@ -0,0 +1,64 @@
+# 集成私有的 Git Repo 与 OCI registry
+
+KCL 包管理工具支持通过 OCI registry 和 Git 仓库保存和分享 KCL 包。本文将介绍如何使用 KCL 包管理工具与私有 OCI registry 和 Git 仓库集成。
+
+## 私有 Git 仓库
+
+KCL 包管理工具依赖本地环境中的 Git 工具完成与 Git 仓库的交互。因此，在使用 KCL 包管理工具之前，确保本地环境中完成了 Git 工具的安装，并且在环境变量 $PATH 中能够找到 Git 命令。
+
+更多信息 - [如何安装 Git 工具](https://git-scm.com/downloads)
+
+KCL 包管理工具与本地环境中的 Git 工具公用一份登录凭证，当您使用 KCL 包管理工具与私有 Git 仓库交互时，您需要先检查 Git 工具能否正常与私有 Git 仓库交互。如果您使用 `git clone` 命令能够成功下载私有 Git 仓库，您可以直接使用 KCL 包管理工具而不需要进行任何登录操作。
+
+更多信息 - [使用 Git 下载私有仓库](https://docs.github.com/zh/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## 私有 OCI Registry
+
+关于私有的 OCI Registry, 主要包括两个部分
+
+1. 需要先使用 `kcl registry login` 命令登录私有 Registry。
+
+    更多信息 - [kcl registry login 登录 OCI registry](https://www.kcl-lang.io/zh-CN/docs/tools/cli/package-management/command-reference/login)
+
+2. 更换 KCL 包管理工具使用的 OCI Registry，KCL 包管理工具支持通过三种方式指定下载 KCL 包时使用的 OCI registry.
+
+    - 命令行或者 kcl.mod 中使用 OCI Url 指定使用的 OCI registry
+
+      你可以通过以下命令行，指定 OCI Registry 为`ghcr.io`。
+
+      ```shell
+      kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+      ```
+
+      或者在 `kcl.mod` 文件中添加如下内容，指定 OCI Registry 为`ghcr.io`。
+
+      ```toml
+      helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
+      ```
+
+    - 通过环境变量
+
+      你可以通过设置三个环境变量 KPM_REG、KPM_REGO 和 OCI_REG_PLAIN_HTTP 来调整配置。
+
+      ```shell
+      # 设置默认仓库地址
+      export KPM_REG="ghcr.io"
+      # 设置默认仓库
+      export KPM_REPO="kcl-lang"
+      # 设置支持 'http'
+      export OCI_REG_PLAIN_HTTP=off
+      ```
+
+    - 通过配置文件
+
+      KCL 包管理工具的配置文件位于 `$KCL_PKG_PATH/.kpm/config/kpm.json`，如果环境变量 `KCL_PKG_PATH` 没有设置，它默认保存在 `$HOME/.kcl/kpm/.kpm/config/kpm.json`。
+
+      配置文件的默认内容如下：
+
+      ```json
+      {
+        "DefaultOciRegistry": "ghcr.io",
+        "DefaultOciRepo": "kcl-lang",
+        "DefaultOciPlainHttp": true
+      }
+      ```
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.9/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md
@@ -0,0 +1,64 @@
+# 集成私有的 Git Repo 与 OCI registry
+
+KCL 包管理工具支持通过 OCI registry 和 Git 仓库保存和分享 KCL 包。本文将介绍如何使用 KCL 包管理工具与私有 OCI registry 和 Git 仓库集成。
+
+## 私有 Git 仓库
+
+KCL 包管理工具依赖本地环境中的 Git 工具完成与 Git 仓库的交互。因此，在使用 KCL 包管理工具之前，确保本地环境中完成了 Git 工具的安装，并且在环境变量 $PATH 中能够找到 Git 命令。
+
+更多信息 - [如何安装 Git 工具](https://git-scm.com/downloads)
+
+KCL 包管理工具与本地环境中的 Git 工具公用一份登录凭证，当您使用 KCL 包管理工具与私有 Git 仓库交互时，您需要先检查 Git 工具能否正常与私有 Git 仓库交互。如果您使用 `git clone` 命令能够成功下载私有 Git 仓库，您可以直接使用 KCL 包管理工具而不需要进行任何登录操作。
+
+更多信息 - [使用 Git 下载私有仓库](https://docs.github.com/zh/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## 私有 OCI Registry
+
+关于私有的 OCI Registry, 主要包括两个部分
+
+1. 需要先使用 `kcl registry login` 命令登录私有 Registry。
+
+    更多信息 - [kcl registry login 登录 OCI registry](https://www.kcl-lang.io/zh-CN/docs/tools/cli/package-management/command-reference/login)
+
+2. 更换 KCL 包管理工具使用的 OCI Registry，KCL 包管理工具支持通过三种方式指定下载 KCL 包时使用的 OCI registry.
+
+    - 命令行或者 kcl.mod 中使用 OCI Url 指定使用的 OCI registry
+
+      你可以通过以下命令行，指定 OCI Registry 为`ghcr.io`。
+
+      ```shell
+      kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+      ```
+
+      或者在 `kcl.mod` 文件中添加如下内容，指定 OCI Registry 为`ghcr.io`。
+
+      ```toml
+      helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
+      ```
+
+    - 通过环境变量
+
+      你可以通过设置三个环境变量 KPM_REG、KPM_REGO 和 OCI_REG_PLAIN_HTTP 来调整配置。
+
+      ```shell
+      # 设置默认仓库地址
+      export KPM_REG="ghcr.io"
+      # 设置默认仓库
+      export KPM_REPO="kcl-lang"
+      # 设置支持 'http'
+      export OCI_REG_PLAIN_HTTP=off
+      ```
+
+    - 通过配置文件
+
+      KCL 包管理工具的配置文件位于 `$KCL_PKG_PATH/.kpm/config/kpm.json`，如果环境变量 `KCL_PKG_PATH` 没有设置，它默认保存在 `$HOME/.kcl/kpm/.kpm/config/kpm.json`。
+
+      配置文件的默认内容如下：
+
+      ```json
+      {
+        "DefaultOciRegistry": "ghcr.io",
+        "DefaultOciRepo": "kcl-lang",
+        "DefaultOciPlainHttp": true
+      }
+      ```
diff --git a/versioned_docs/version-0.7/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md b/versioned_docs/version-0.7/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md
@@ -0,0 +1,64 @@
+# Integrate Private Git Repo and OCI Registry
+
+KCL package management tool supports saving and sharing KCL modules through the OCI registry and Git repository. This section will introduce how to integrate the KCL package management tool with the private OCI registry and Git repository.
+
+## Private Git Repository
+
+KCL package management tool depends on the Git tool in the local environment to interact with the Git repository. Therefore, before using the KCL package management tool, ensure the Git tool is installed in the local environment and the Git command can be found in the environment variable $PATH.
+
+More Details - [How to Install Git Tool](https://git-scm.com/downloads)
+
+KCL package management tool shares the same login credentials with the Git tool in the local environment. When you use the KCL package management tool to interact with a private Git repository, you need to check whether the Git tool can interact with the private Git repository normally. If you can successfully download the private Git repository using the `git clone` command, you can directly use the KCL package management tool without any login operation.
+
+More Details - [Download Private Repository Using Git](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## Private OCI Registry
+
+The KCL package management tool supports saving and sharing KCL packages through private OCI Registries. mainly including two parts.
+
+1. Login to the private OCI Registry using the `kcl registry login` command.
+
+    More Details - [kcl registry login Login OCI Registry](https://www.kcl-lang.io/docs/tools/cli/package-management/command-reference/login)
+
+2. Replace the OCI Registry used by the KCL package management tool. The KCL package management tool supports specifying the OCI registry used to download KCL packages in three ways.
+
+    - Use the OCI Url to specify the OCI registry in the command line or `kcl.mod`.
+
+      You can specify the OCI Registry as `ghcr.io` by the following command.
+
+      ```shell
+      kcl mod add oci://ghcr.io/kcl-lang/helloworld --tag 0.1.0
+      ```
+
+      Or add the following content to the `kcl.mod` file to specify the OCI Registry as `ghcr.io`.
+
+      ```toml
+      helloworld = { oci = "oci://ghcr.io/kcl-lang/helloworld", tag = "0.1.0" }
+      ```
+
+    - By environment variable
+
+      You can adjust the configuration of the OCI Registry by setting the three environment variables `KPM_REG`, `KPM_REGO`, and `OCI_REG_PLAIN_HTTP`.
+
+      ```shell
+      # set default registry
+      export KPM_REG="ghcr.io"
+      # set default repository
+      export KPM_REPO="kcl-lang"
+      # set support for 'http'
+      export OCI_REG_PLAIN_HTTP=off
+      ```
+
+    - By configuration file
+
+      The configuration file of the KCL package management tool is located at `$KCL_PKG_PATH/.kpm/config/kpm.json`, if the environment variable `KCL_PKG_PATH` is not set, it is saved by default in `$HOME/.kcl/kpm/.kpm/config/kpm.json`.
+
+      The default content of the configuration file is as follows:
+
+      ```json
+      {
+        "DefaultOciRegistry": "ghcr.io",
+        "DefaultOciRepo": "kcl-lang",
+        "DefaultOciPlainHttp": true
+      }
+      ```
diff --git a/versioned_docs/version-0.8/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md b/versioned_docs/version-0.8/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md
diff --git a/versioned_docs/version-0.9/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md b/versioned_docs/version-0.9/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md
