docs: describe token helper auth and the update fetch warning

0.25.12 changes two things users can notice that the docs never covered.
Token auth now goes through a host-scoped credential helper (#566), so the
token stays out of ps and git skips the user's own helper or keychain for
that host. Grouped updates now warn when a repository cannot be fetched
(#570), with credentials removed from the URL and error. Note both on the
install and update pages in every locale.
This commit is contained in:
Willie
2026-10-15 00:58:54 +08:00
parent 0c69dad6c2
commit 4e3076df3f
10 changed files with 15 additions and 5 deletions
@@ -535,6 +535,8 @@ skillshare install https://github.com/org/private-skills.git --track
Platform-specific variables take priority over `SKILLSHARE_GIT_TOKEN`.
The token reaches git through a credential helper scoped to the host, so it never appears in process arguments such as `ps` output. While a token applies to a host, git does not ask your own credential helper or keychain for that host and stores nothing there.
Official token documentation:
- GitHub: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- GitLab: [Token overview](https://docs.gitlab.com/security/tokens/)
+1 -1
View File
@@ -224,7 +224,7 @@ This updates:
1. All tracked repositories (git pull)
2. All skills with source metadata (reinstall when upstream changed)
`update --all` and `update --group` group remote skills by repository and clone each repository once. They leave alone any skill whose folder did not change upstream and count it as up to date. A skill whose folder contains a symlink is the exception: its files can change without the folder changing, so it is reinstalled whenever the upstream commit moves. Several skills named in project mode (`-p`) work the same way. Use `--force` to reinstall every skill anyway. A single skill, and skills named in global mode, are always reinstalled.
`update --all` and `update --group` group remote skills by repository and clone each repository once. They leave alone any skill whose folder did not change upstream and count it as up to date. A skill whose folder contains a symlink is the exception: its files can change without the folder changing, so it is reinstalled whenever the upstream commit moves. Several skills named in project mode (`-p`) work the same way. Use `--force` to reinstall every skill anyway. A single skill, and skills named in global mode, are always reinstalled. When a repository cannot be fetched, its skills count as skipped and `update` prints a warning naming the repository and the error, with any credentials in the URL removed.
### Example Output
@@ -529,6 +529,8 @@ skillshare install https://github.com/org/private-skills.git --track
プラットフォーム固有の環境変数は `SKILLSHARE_GIT_TOKEN` より優先されます。
token はホスト単位の credential helper を通じて git に渡されるため、`ps` の出力などのプロセス引数には現れません。token がホストに適用されている間、git はそのホストについて自分の credential helper やキーチェーンに問い合わせず、何も保存しません。
公式のトークンドキュメント:
- GitHub: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- GitLab: [Token overview](https://docs.gitlab.com/security/tokens/)
@@ -224,7 +224,7 @@ skillshare update --all
1. すべての tracked repositories(git pull)
2. source metadata を持つすべての skill(upstream が変わったときに再インストール)
`update --all` と `update --group` はリモート skill をリポジトリごとにまとめ、各リポジトリを 1 回だけ clone します。フォルダが upstream で変わっていない skill には手を付けず、up to date として数えます。ただし、フォルダに symlink を含む skill は例外です。フォルダが変わらなくてもファイルが変わることがあるため、upstream の commit が進むたびに再インストールします。プロジェクトモード(`-p`)で複数の skill を名前で指定した場合も同じです。すべてを再インストールするには `--force` を使います。skill が 1 つだけのときと、グローバルモードで名前を指定したときは常に再インストールします。
`update --all` と `update --group` はリモート skill をリポジトリごとにまとめ、各リポジトリを 1 回だけ clone します。フォルダが upstream で変わっていない skill には手を付けず、up to date として数えます。ただし、フォルダに symlink を含む skill は例外です。フォルダが変わらなくてもファイルが変わることがあるため、upstream の commit が進むたびに再インストールします。プロジェクトモード(`-p`)で複数の skill を名前で指定した場合も同じです。すべてを再インストールするには `--force` を使います。skill が 1 つだけのときと、グローバルモードで名前を指定したときは常に再インストールします。リポジトリを取得できなかった場合、その skill は skipped として数え、リポジトリ名とエラーを示す警告を表示します。URL に含まれる認証情報は取り除かれます。
### 出力例
@@ -529,6 +529,8 @@ skillshare install https://github.com/org/private-skills.git --track
플랫폼별 변수가 `SKILLSHARE_GIT_TOKEN`보다 우선합니다.
token은 호스트 범위의 credential helper를 통해 git에 전달되므로 `ps` 출력 같은 프로세스 인자에 나타나지 않습니다. 호스트에 token이 적용되는 동안 git은 해당 호스트에 대해 사용자의 credential helper나 키체인에 묻지 않으며 아무것도 저장하지 않습니다.
공식 토큰 문서:
- GitHub: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- GitLab: [Token overview](https://docs.gitlab.com/security/tokens/)
@@ -224,7 +224,7 @@ skillshare update --all
1. 모든 tracked 저장소(git pull)
2. source metadata가 있는 모든 skill(upstream이 바뀌었을 때 재설치)
`update --all`과 `update --group`은 원격 skill을 저장소별로 묶어 저장소마다 한 번만 clone합니다. upstream에서 폴더가 바뀌지 않은 skill은 그대로 두고 up to date로 집계합니다. 단, 폴더에 symlink가 있는 skill은 예외입니다. 폴더가 바뀌지 않아도 파일이 바뀔 수 있으므로 upstream commit이 바뀔 때마다 다시 설치합니다. 프로젝트 모드(`-p`)에서 여러 skill을 이름으로 지정해도 같습니다. 모든 skill을 다시 설치하려면 `--force`를 사용하세요. skill이 하나뿐이거나 글로벌 모드에서 이름으로 지정하면 항상 다시 설치합니다.
`update --all`과 `update --group`은 원격 skill을 저장소별로 묶어 저장소마다 한 번만 clone합니다. upstream에서 폴더가 바뀌지 않은 skill은 그대로 두고 up to date로 집계합니다. 단, 폴더에 symlink가 있는 skill은 예외입니다. 폴더가 바뀌지 않아도 파일이 바뀔 수 있으므로 upstream commit이 바뀔 때마다 다시 설치합니다. 프로젝트 모드(`-p`)에서 여러 skill을 이름으로 지정해도 같습니다. 모든 skill을 다시 설치하려면 `--force`를 사용하세요. skill이 하나뿐이거나 글로벌 모드에서 이름으로 지정하면 항상 다시 설치합니다. 저장소를 가져오지 못하면 해당 skill은 skipped로 집계되고, 저장소와 오류를 알려 주는 경고가 표시됩니다. URL에 포함된 인증 정보는 제거됩니다.
### 출력 예시
@@ -529,6 +529,8 @@ skillshare install https://github.com/org/private-skills.git --track
平台专属变量的优先级高于 `SKILLSHARE_GIT_TOKEN`。
token 通过限定于该主机的 credential helper 传给 git,因此不会出现在 `ps` 输出等进程参数中。token 作用于某个主机期间,git 不会向你自己的 credential helper 或钥匙串查询该主机,也不会在其中存储任何内容。
官方 token 文档:
- GitHub: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- GitLab: [Token overview](https://docs.gitlab.com/security/tokens/)
@@ -224,7 +224,7 @@ skillshare update --all
1. 所有 tracked repositories(git pull)
2. 所有带来源 metadata 的 skills(upstream 有变化时重新安装)
`update --all` 和 `update --group` 会按仓库对远程 skill 分组,每个仓库只 clone 一次。文件夹在 upstream 中没有变化的 skill 保持不变,并计为 up to date。文件夹中含有 symlink 的 skill 例外:文件夹不变时文件也可能变化,因此只要 upstream commit 有变动就会重新安装。在项目模式(`-p`)下按名称指定多个 skill 时也一样。使用 `--force` 可重新安装所有 skill。只更新一个 skill,或在全局模式下按名称指定时,总是重新安装。
`update --all` 和 `update --group` 会按仓库对远程 skill 分组,每个仓库只 clone 一次。文件夹在 upstream 中没有变化的 skill 保持不变,并计为 up to date。文件夹中含有 symlink 的 skill 例外:文件夹不变时文件也可能变化,因此只要 upstream commit 有变动就会重新安装。在项目模式(`-p`)下按名称指定多个 skill 时也一样。使用 `--force` 可重新安装所有 skill。只更新一个 skill,或在全局模式下按名称指定时,总是重新安装。无法获取某个仓库时,其 skill 计为 skipped,`update` 会显示一条警告,写明该仓库和错误,并移除 URL 中的凭据。
### 示例输出
@@ -529,6 +529,8 @@ skillshare install https://github.com/org/private-skills.git --track
平台專屬的變數優先於 `SKILLSHARE_GIT_TOKEN`。
token 會透過限定於該主機的 credential helper 傳給 git,因此不會出現在 `ps` 輸出等行程參數中。token 套用於某個主機期間,git 不會向你自己的 credential helper 或鑰匙圈查詢該主機,也不會在其中儲存任何內容。
官方 token 文件:
- GitHub:[Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
- GitLab:[Token overview](https://docs.gitlab.com/security/tokens/)
@@ -224,7 +224,7 @@ skillshare update --all
1. 所有 tracked 儲存庫(git pull)
2. 所有帶有來源 metadata 的 skills(upstream 有變更時重新安裝)
`update --all` 與 `update --group` 會依儲存庫將遠端 skill 分組,每個儲存庫只 clone 一次。資料夾在 upstream 沒有變更的 skill 維持不動,並計為 up to date。資料夾中含有 symlink 的 skill 例外:資料夾不變時檔案也可能改變,因此只要 upstream commit 有變動就會重新安裝。在專案模式(`-p`)下依名稱指定多個 skill 時也相同。使用 `--force` 可重新安裝所有 skill。只更新一個 skill,或在全域模式下依名稱指定時,一律重新安裝。
`update --all` 與 `update --group` 會依儲存庫將遠端 skill 分組,每個儲存庫只 clone 一次。資料夾在 upstream 沒有變更的 skill 維持不動,並計為 up to date。資料夾中含有 symlink 的 skill 例外:資料夾不變時檔案也可能改變,因此只要 upstream commit 有變動就會重新安裝。在專案模式(`-p`)下依名稱指定多個 skill 時也相同。使用 `--force` 可重新安裝所有 skill。只更新一個 skill,或在全域模式下依名稱指定時,一律重新安裝。無法取得某個儲存庫時,其 skill 計為 skipped,`update` 會顯示一則警告,寫明該儲存庫與錯誤,並移除 URL 中的憑證。
### 輸出範例