feat: document shallow clone and add unshallow fetch option

docs/ko/reference/Remote/Methods/fetch.md

@@ -89,10 +89,7 @@ class Remote {
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">
-              가져올 커밋의 깊이를 설정해요.  
-              0 이하의 값이면 모든 커밋을 가져와요(제한 없음).
-            </p>
+            <p class="param-description">fetch 깊이로, 각 원격 브랜치의 최신 커밋부터 가져올 커밋 수를 설정해요. 0보다 크면 얕은 리포지토리가 만들어져요(<code>Repository.isShallow()</code> 참고).  0 이하의 값이면 모든 커밋을 가져와요(사실상 깊이 제한을 선언하지 않은 것과 같아요). 이미 얕은 리포지토리를 전체 리포지토리로 바꾸지는 않으므로, 그럴 때는 <code>unshallow</code>를 사용해요.  로컬 전송은 얕은 fetch를 지원하지 않아서 로컬 경로나 <code>file://</code> URL에서는 <code>depth</code>가 실패해요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -148,6 +145,11 @@ class Remote {
               - <code>Off</code> : 정리를 강제 비활성화
             </p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description"><code>git fetch --unshallow</code>처럼 얕은 리포지토리에 없는 히스토리를 가져와요. 원격 리포지토리도 얕은 리포지토리라면 원격에 있는 만큼만 가져와요.  <code>true</code>이면 <code>depth</code>는 무시돼요.</p>
+          </li>
         </ul>
       </li>
       <li class="param-li">

docs/ko/reference/Repository/cloneRepository.md

@@ -120,7 +120,7 @@ function cloneRepository(
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">클론할 커밋 깊이를 설정해요. 0 이하의 값이면 전체 이력을 클론해요.</p>
+            <p class="param-description">fetch 깊이로, 각 원격 브랜치의 최신 커밋부터 가져올 커밋 수를 설정해요. 0보다 크면 얕은 리포지토리가 만들어져요(<code>Repository.isShallow()</code> 참고).  0 이하의 값이면 모든 커밋을 가져와요(사실상 깊이 제한을 선언하지 않은 것과 같아요). 이미 얕은 리포지토리를 전체 리포지토리로 바꾸지는 않으므로, 그럴 때는 <code>unshallow</code>를 사용해요.  로컬 전송은 얕은 fetch를 지원하지 않아서 로컬 경로나 <code>file://</code> URL에서는 <code>depth</code>가 실패해요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -187,6 +187,11 @@ function cloneRepository(
               - <code>Off</code> : 삭제하지 않음
             </p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description"><code>git fetch --unshallow</code>처럼 얕은 리포지토리에 없는 히스토리를 가져와요. 원격 리포지토리도 얕은 리포지토리라면 원격에 있는 만큼만 가져와요.  <code>true</code>이면 <code>depth</code>는 무시돼요.</p>
+          </li>
         </ul>
       </li>
       <li class="param-li">
@@ -256,3 +261,18 @@ const repo = await cloneRepository('git@github.com:toss/es-git', '.', {
   },
 });
 ```
+
+최신 커밋만 가져오는 얕은 클론을 해요.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone', {
+  fetch: { depth: 1 },
+});
+console.log(repo.isShallow()); // true
+
+// 나머지 히스토리는 나중에 가져와요.
+await repo.getRemote('origin').fetch([], { fetch: { unshallow: true } });
+console.log(repo.isShallow()); // false
+```

docs/ko/reference/Submodule/Methods/clone.md

@@ -178,7 +178,7 @@ class Submodule {
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">fetch 깊이 설정. 0 이하 값은 모든 항목을 가져오라는 의미로 해석돼요(사실상 깊이 제한을 선언하지 않은 것과 같아요).</p>
+            <p class="param-description">fetch 깊이로, 각 원격 브랜치의 최신 커밋부터 가져올 커밋 수를 설정해요. 0보다 크면 얕은 리포지토리가 만들어져요(<code>Repository.isShallow()</code> 참고).  0 이하의 값이면 모든 커밋을 가져와요(사실상 깊이 제한을 선언하지 않은 것과 같아요). 이미 얕은 리포지토리를 전체 리포지토리로 바꾸지는 않으므로, 그럴 때는 <code>unshallow</code>를 사용해요.  로컬 전송은 얕은 fetch를 지원하지 않아서 로컬 경로나 <code>file://</code> URL에서는 <code>depth</code>가 실패해요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -215,6 +215,11 @@ class Submodule {
             <p class="param-description">fetch 이후 prune 수행 여부 설정</p>
             <p class="param-description">- <code>Unspecified</code> : 구성의 설정을 사용<br>- <code>On</code> : prune을 강제로 켬<br>- <code>Off</code> : prune을 강제로 끔</p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description"><code>git fetch --unshallow</code>처럼 얕은 리포지토리에 없는 히스토리를 가져와요. 원격 리포지토리도 얕은 리포지토리라면 원격에 있는 만큼만 가져와요.  <code>true</code>이면 <code>depth</code>는 무시돼요.</p>
+          </li>
         </ul>
       </li>
     </ul>

docs/ko/reference/Submodule/Methods/update.md

@@ -184,7 +184,7 @@ class Submodule {
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">fetch 깊이 설정. 0 이하의 값은 모든 것을 가져오라는 의미로 해석돼요(사실상 깊이 제한을 선언하지 않는 것과 동일해요).</p>
+            <p class="param-description">fetch 깊이로, 각 원격 브랜치의 최신 커밋부터 가져올 커밋 수를 설정해요. 0보다 크면 얕은 리포지토리가 만들어져요(<code>Repository.isShallow()</code> 참고).  0 이하의 값이면 모든 커밋을 가져와요(사실상 깊이 제한을 선언하지 않은 것과 같아요). 이미 얕은 리포지토리를 전체 리포지토리로 바꾸지는 않으므로, 그럴 때는 <code>unshallow</code>를 사용해요.  로컬 전송은 얕은 fetch를 지원하지 않아서 로컬 경로나 <code>file://</code> URL에서는 <code>depth</code>가 실패해요.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -221,6 +221,11 @@ class Submodule {
             <p class="param-description">fetch 후 prune을 수행할지 여부 설정</p>
             <p class="param-description">- <code>Unspecified</code> : 구성의 설정을 사용.<br>- <code>On</code> : prune을 강제로 켬.<br>- <code>Off</code> : prune을 강제로 끔</p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description"><code>git fetch --unshallow</code>처럼 얕은 리포지토리에 없는 히스토리를 가져와요. 원격 리포지토리도 얕은 리포지토리라면 원격에 있는 만큼만 가져와요.  <code>true</code>이면 <code>depth</code>는 무시돼요.</p>
+          </li>
         </ul>
       </li>
     </ul>

docs/ko/usage/repository.md

@@ -83,3 +83,33 @@ const repo = await cloneRepository('https://github.com/<owner>/<repo>', '.', {
   },
 });
 ```
+
+### 얕은 클론하기
+
+히스토리의 최근 일부만 클론하려면 `fetch` 옵션에 `depth`를 설정하세요. `depth`가 `1`이면 각 브랜치의 최신 커밋만
+가져와요. 리포지토리가 얕은 리포지토리인지는 [`isShallow()`](../reference/Repository/Methods/isShallow.md)로 확인할 수 있어요.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone', {
+  fetch: { depth: 1 },
+});
+console.log(repo.isShallow()); // true
+```
+
+::: warning
+얕은 클론은 `https://`, `git://`, SSH 같은 네트워크 프로토콜에서만 동작해요. libgit2의 로컬 전송은 얕은 fetch를
+지원하지 않기 때문에, 로컬 경로나 `file://` URL에서 `depth`를 설정해 클론하면 실패해요.
+:::
+
+나머지 히스토리를 나중에 가져오려면 `unshallow: true`로 리모트에서 fetch하세요. `git fetch --unshallow`와 같아요.
+
+```ts
+const remote = repo.getRemote('origin');
+await remote.fetch([], { fetch: { unshallow: true } });
+console.log(repo.isShallow()); // false
+```
+
+더 큰 `depth`로 fetch하면 히스토리를 그만큼 더 가져와요. `depth: 0`으로 fetch하거나 `depth`를 지정하지 않으면 얕은
+리포지토리가 전체 리포지토리로 바뀌지 않아요.

docs/reference/Remote/Methods/fetch.md

@@ -88,7 +88,7 @@ class Remote {
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">Set fetch depth, a value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth).</p>
+            <p class="param-description">Set fetch depth, the number of commits to fetch from the tip of each remote branch. A depth greater than 0 creates a shallow repository (see <code>Repository.isShallow()</code>).  A value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth). This does not unshallow an existing shallow repository; use <code>unshallow</code> for that.  Shallow fetches are not supported by the local transport, so <code>depth</code> fails for local paths and <code>file://</code> URLs.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -125,6 +125,11 @@ class Remote {
             <p class="param-description">Set whether to perform a prune after the fetch.</p>
             <p class="param-description">- <code>Unspecified</code> : Use the setting from the configuration.<br>- <code>On</code> : Force pruning on.<br>- <code>Off</code> : Force pruning off</p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description">Fetch the history missing from a shallow repository, like <code>git fetch --unshallow</code>. If the remote repository is itself shallow, fetch as much history as it has.  When <code>true</code>, <code>depth</code> is ignored.</p>
+          </li>
         </ul>
       </li>
       <li class="param-li">

docs/reference/Repository/cloneRepository.md

@@ -103,7 +103,7 @@ function cloneRepository(
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">Set fetch depth, a value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth).</p>
+            <p class="param-description">Set fetch depth, the number of commits to fetch from the tip of each remote branch. A depth greater than 0 creates a shallow repository (see <code>Repository.isShallow()</code>).  A value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth). This does not unshallow an existing shallow repository; use <code>unshallow</code> for that.  Shallow fetches are not supported by the local transport, so <code>depth</code> fails for local paths and <code>file://</code> URLs.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -140,6 +140,11 @@ function cloneRepository(
             <p class="param-description">Set whether to perform a prune after the fetch.</p>
             <p class="param-description">- <code>Unspecified</code> : Use the setting from the configuration.<br>- <code>On</code> : Force pruning on.<br>- <code>Off</code> : Force pruning off</p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description">Fetch the history missing from a shallow repository, like <code>git fetch --unshallow</code>. If the remote repository is itself shallow, fetch as much history as it has.  When <code>true</code>, <code>depth</code> is ignored.</p>
+          </li>
         </ul>
       </li>
       <li class="param-li">
@@ -203,4 +208,19 @@ const repo = await cloneRepository('git@github.com:toss/es-git', '.', {
     },
   },
 });
+```
+
+Shallow clone repository with only the latest commit.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone', {
+  fetch: { depth: 1 },
+});
+console.log(repo.isShallow()); // true
+
+// Fetch the rest of the history later.
+await repo.getRemote('origin').fetch([], { fetch: { unshallow: true } });
+console.log(repo.isShallow()); // false
 ```

docs/reference/Submodule/Methods/clone.md

@@ -178,7 +178,7 @@ class Submodule {
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">Set fetch depth, a value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth).</p>
+            <p class="param-description">Set fetch depth, the number of commits to fetch from the tip of each remote branch. A depth greater than 0 creates a shallow repository (see <code>Repository.isShallow()</code>).  A value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth). This does not unshallow an existing shallow repository; use <code>unshallow</code> for that.  Shallow fetches are not supported by the local transport, so <code>depth</code> fails for local paths and <code>file://</code> URLs.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -215,12 +215,17 @@ class Submodule {
             <p class="param-description">Set whether to perform a prune after the fetch.</p>
             <p class="param-description">- <code>Unspecified</code> : Use the setting from the configuration.<br>- <code>On</code> : Force pruning on.<br>- <code>Off</code> : Force pruning off</p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description">Fetch the history missing from a shallow repository, like <code>git fetch --unshallow</code>. If the remote repository is itself shallow, fetch as much history as it has.  When <code>true</code>, <code>depth</code> is ignored.</p>
+          </li>
         </ul>
       </li>
     </ul>
   </li>
   <li class="param-li param-li-root">
-    <span class="param-name">signal</span><span class="param-type">null | AbortSignal</span>
+    <span class="param-name">signal</span><span class="param-type">AbortSignal | null</span>
     <br>
     <p class="param-description">Optional AbortSignal to cancel the operation.</p>
   </li>

docs/reference/Submodule/Methods/update.md

@@ -187,7 +187,7 @@ class Submodule {
           <li class="param-li">
             <span class="param-name">depth</span><span class="param-type">number</span>
             <br>
-            <p class="param-description">Set fetch depth, a value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth).</p>
+            <p class="param-description">Set fetch depth, the number of commits to fetch from the tip of each remote branch. A depth greater than 0 creates a shallow repository (see <code>Repository.isShallow()</code>).  A value less or equal to 0 is interpreted as pull everything (effectively the same as not declaring a limit depth). This does not unshallow an existing shallow repository; use <code>unshallow</code> for that.  Shallow fetches are not supported by the local transport, so <code>depth</code> fails for local paths and <code>file://</code> URLs.</p>
           </li>
           <li class="param-li">
             <span class="param-name">downloadTags</span><span class="param-type">AutotagOption</span>
@@ -224,12 +224,17 @@ class Submodule {
             <p class="param-description">Set whether to perform a prune after the fetch.</p>
             <p class="param-description">- <code>Unspecified</code> : Use the setting from the configuration.<br>- <code>On</code> : Force pruning on.<br>- <code>Off</code> : Force pruning off</p>
           </li>
+          <li class="param-li">
+            <span class="param-name">unshallow</span><span class="param-type">boolean</span>
+            <br>
+            <p class="param-description">Fetch the history missing from a shallow repository, like <code>git fetch --unshallow</code>. If the remote repository is itself shallow, fetch as much history as it has.  When <code>true</code>, <code>depth</code> is ignored.</p>
+          </li>
         </ul>
       </li>
     </ul>
   </li>
   <li class="param-li param-li-root">
-    <span class="param-name">signal</span><span class="param-type">null | AbortSignal</span>
+    <span class="param-name">signal</span><span class="param-type">AbortSignal | null</span>
     <br>
     <p class="param-description">Optional AbortSignal to cancel the operation.</p>
   </li>

docs/usage/repository.md

@@ -82,3 +82,35 @@ const repo = await cloneRepository('https://github.com/<owner>/<repo>', '.', {
   },
 });
 ```
+
+### Shallow Clone
+
+To clone only the latest part of the history, set `depth` in the `fetch` option. A depth of `1` fetches only the latest
+commit of each branch. Use [`isShallow()`](../reference/Repository/Methods/isShallow.md) to check whether a repository is
+shallow.
+
+```ts
+import { cloneRepository } from 'es-git';
+
+const repo = await cloneRepository('https://github.com/toss/es-git', '/path/to/clone', {
+  fetch: { depth: 1 },
+});
+console.log(repo.isShallow()); // true
+```
+
+::: warning
+Shallow clones need a network protocol such as `https://`, `git://` or SSH. Cloning from a local path or a `file://` URL
+with `depth` fails, because libgit2's local transport does not support shallow fetches.
+:::
+
+To fetch the rest of the history later, fetch from the remote with `unshallow: true`. This works like
+`git fetch --unshallow`.
+
+```ts
+const remote = repo.getRemote('origin');
+await remote.fetch([], { fetch: { unshallow: true } });
+console.log(repo.isShallow()); // false
+```
+
+Fetching with a larger `depth` deepens the history instead. Fetching with `depth: 0` or without `depth` does not unshallow
+a shallow repository.