From e6a059a3d0c699e00c05cfa81ab3bfd0598a89a2 Mon Sep 17 00:00:00 2001
From: merlleu <r.langdorph@gmail.com>
Date: Wed, 13 Sep 2023 06:14:10 +0200
Subject: [PATCH] add sparse url in cargo package guide (#26937)

Hello,

The current package guide for cargo gives you only the git index, with
the HTTP Index stabilized being used as default for crates.io and being
better for most use-cases.

However, it's not documented that gitea supports the sparse spec, and it
does not require the _crates-index git repo for the sparse api.

I personally think we should push users to use the sparse instead of the
git repository. (Even let users disable crates-index repos if they only
want to use sparse)
---
 docs/content/usage/packages/cargo.en-us.md | 13 ++++++++++---
 docs/content/usage/packages/cargo.zh-cn.md |  3 ++-
 templates/package/content/cargo.tmpl       |  3 ++-
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/docs/content/usage/packages/cargo.en-us.md b/docs/content/usage/packages/cargo.en-us.md
index d5c2fab6fd..356e7ff0b9 100644
--- a/docs/content/usage/packages/cargo.en-us.md
+++ b/docs/content/usage/packages/cargo.en-us.md
@@ -50,10 +50,11 @@ Add the following text to the configuration file located in the current users ho
 default = "gitea"
 
 [registries.gitea]
-index = "https://gitea.example.com/{owner}/_cargo-index.git"
+index = "sparse+https://gitea.example.com/api/packages/{owner}/cargo/" # Sparse index
+# index = "https://gitea.example.com/{owner}/_cargo-index.git" # Git
 
-[net]
-git-fetch-with-cli = true
+# [net]
+# git-fetch-with-cli = true
 ```
 
 | Parameter | Description |
@@ -72,6 +73,12 @@ token = "Bearer {token}"
 | --------- | ----------- |
 | `token`   | Your [personal access token](development/api-usage.md#authentication) |
 
+## Git vs Sparse
+
+Currently, cargo supports two ways for fetching crates in a registry: Git index & sparse index.
+Sparse index is the newest method and offers better performance when updating crates compared to git.
+Since Rust 1.68, sparse is the default method for crates.io.
+
 ## Publish a package
 
 Publish a package by running the following command in your project:
diff --git a/docs/content/usage/packages/cargo.zh-cn.md b/docs/content/usage/packages/cargo.zh-cn.md
index 126dfd370a..285fe9c8b3 100644
--- a/docs/content/usage/packages/cargo.zh-cn.md
+++ b/docs/content/usage/packages/cargo.zh-cn.md
@@ -50,7 +50,8 @@ Cargo 将可用软件包的信息存储在一个存储在 git 仓库中的软件
 default = "gitea"
 
 [registries.gitea]
-index = "https://gitea.example.com/{owner}/_cargo-index.git"
+index = "sparse+https://gitea.example.com/api/packages/{owner}/cargo/" # Sparse index
+# index = "https://gitea.example.com/{owner}/_cargo-index.git" # Git
 
 [net]
 git-fetch-with-cli = true
diff --git a/templates/package/content/cargo.tmpl b/templates/package/content/cargo.tmpl
index b7a34632e4..67e003c9d1 100644
--- a/templates/package/content/cargo.tmpl
+++ b/templates/package/content/cargo.tmpl
@@ -8,7 +8,8 @@
 default = "gitea"
 
 [registries.gitea]
-index = "<gitea-origin-url data-url="{{AppSubUrl}}/{{.PackageDescriptor.Owner.Name}}/_cargo-index.git"></gitea-origin-url>"
+index = "<gitea-origin-url data-url="sparse+{{AppSubUrl}}/api/packages/{{.PackageDescriptor.Owner.Name}}/cargo/"></gitea-origin-url>" # Sparse index
+# index = "<gitea-origin-url data-url="{{AppSubUrl}}/{{.PackageDescriptor.Owner.Name}}/_cargo-index.git"></gitea-origin-url>" # Git
 
 [net]
 git-fetch-with-cli = true</code></pre></div>