# microgit-cli 中文文档

规范地址：https://npmcn.com/package/microgit-cli/

版本：0\.1\.1
npm 元数据更新时间：2026-11-04T03:51:40.818Z
中文译文更新时间：2026-11-04T04:41:06.210Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/microgit-cli
原文对照：https://npmcn.com/package/microgit-cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：160 kB，42 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-11-04T03:50:04.371Z
- 最新版本发布：2026-11-04T03:51:40.664Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于自托管git服务器的命令行客户端（microgit）

## 安装

```sh
npm install microgit-cli
```

也可以使用：`pnpm add microgit-cli`、`yarn add microgit-cli`、`bun add microgit-cli`

## README

# microgit-cli

`microgit` - - - - - - **你自己的git服务器-克隆，推送，主机**。

的小型命令行客户端 [microgit](https://npmcn.com/package/microgit-cli/npm@microgit) 服务器。它保留了API 会话在本地配置文件中创建和删除存储库，并包装 通常 `git` 推/拉命令与帐户凭据一起工作。

它是一个单独的TypeScript项目 **无运行时依赖项** (节点的 内置的 `fetch`， `readline` 和 `git` 是足够的)。

## 安装

```bash
npm install -g microgit-cli
```

如果没有全局安装，直接运行构建的入口点：

```bash
node src/index.js --help
```

## 交互式shell

运行 `microgit` 没有参数(或。 `microgit shell`)打开外壳；

```
  ● ━━━ ●
    ┣━━━ ●   microgit-cli • gitserver  v0.1.0
    ┗━━━ ●   your own git server — clone, push, host

  # server   http://{HOST_NAME}:{PORT}
  # account  alice · 7d left

  ✓ ready · type help to list the commands
  # one-shot microgit --help

alice@microgit:~/repos$ new app
```

启动shell首先清除屏幕和滚动，因此横幅是 这一页上唯一的东西。提示符显示已登录的帐户和 当前文件夹。命令与一次性CLI和shell是相同的单词 补充道:

| 按键/命令 | 它是做什么的 |
| --- | --- |
| `↑` / `↓` | 历史，保存在 `~/.microgit/history` |
| `Tab` | 完整的命令名称， `config` 行动和 `--options` |
| `Ctrl+C` | 清线；在空行中，它离开shell |
| `Ctrl+D` | 离开外壳 |
| `help` | 命令列表 |
| `clear` | 清除屏幕并重新绘制横幅 |
| `exit` / `quit` | 离开外壳 |

错误永远不会关闭shell。要求某事的命令(`login`， `commit`， `delete`， `new`)在同一提示符中问道。

## 快速启动

```bash
# 1. Point the CLI at the server and sign in. Use the host and port the
#    server actually listens on, or its domain behind a reverse proxy.
microgit login --url http://{HOST_NAME}:{PORT}

# 2. Create a repository and a local checkout with a first commit,
#    then push it.
microgit new app --init

# 3. Work as usual; commit also pushes.
cd app
echo "hello" > hello.txt
microgit commit -m "Add hello.txt"

# 4. Check the session or list repositories.
microgit whoami
microgit list
```

再次登录将重用一个有效的存储会话，因此用户名和密码是 只问过一次。添加 `--force` 以另一个帐户登录。

## 命令

| 命令 | 它是做什么的 |
| --- | --- |
| `microgit login` | 登录，存储API令牌和可选的git密码 |
| `microgit register` | 创建一个帐户（当服务器允许注册时）并登录 |
| `microgit logout` | 撤销服务器会话，删除本地令牌和密码 |
| `microgit whoami` | 显示登录帐户，服务器和到期 |
| `microgit new <name>` | 创建存储库；要求公共/私人，加上 `--private`， `--public`， `--clone`， `--init` |
| `microgit list` | 存储库列表; `--owner`， `--name`， `--public`， `--private` |
| `microgit delete <name|owner/name>` | 删除存储库；在做之前先问一下 |
| `microgit clone <name|owner/name> [dir]` | 使用来自服务器的克隆URL进行克隆 |
| `microgit init [dir]` | 仅限本地：项目文件夹， `git init` 和一个空的 `README.md` |
| `microgit status` | `git status --short --branch` |
| `microgit commit -m "message"` | `git add -A`承诺，然后推动 |
| `microgit push [git args]` | 使用存储凭据推送 |
| `microgit pull [git args]` | 使用存储凭据进行拉取 |
| `microgit config` | 显示配置文件、服务器和会话 |

每个命令都接受 `-h` / `--help`． 打印API数据的命令也接受 `--json` 有意义的地方(`whoami`， `list`， `new`， `delete`， `clone`， `login`， `register`， `logout`， `config`）.

### 创建存储库

没有 `--private` 或 `--public` 命令行要求可见性，然后按Enter 创建一个公共存储库：

```bash
microgit new app                  # asks: public or private
microgit new secret --private
microgit new app --public
microgit new app --clone          # create it and clone the empty repository
microgit new app --init           # create it, README, first commit and push
microgit new app --init --dir ./projects/app
```

发送到服务器的请求为 `{"name":"app","private":false}` (或 `true`）.

`new` 打印服务器的克隆URL。现有存储库不是错误： API返回 `created: false` 命令行说它已经存在了。

### 启动本地存储库

`microgit init` 是本地的-它不与服务器通信：

```bash
microgit init app        # creates ./app, .git on main, empty README.md
microgit init            # initialise the current folder
microgit init --dir ./projects/app
```

它拒绝在现有的存储库中运行，并重用保存的帐户 的名字 `user.name` / `user.email` 当git没有配置时。

### 删除存储库

```bash
microgit delete app                 # asks for confirmation
microgit delete app --yes           # non-interactive
microgit delete bob/app --yes       # administrators can delete for another owner
```

### 清单库

```bash
microgit list
microgit list --owner alice
microgit list --private --limit 20
microgit list --public --page 2 --json
```

## 身份验证和git凭证

返回的会话令牌 `login`． 命令行将其发送为 `Authorization: Bearer <token>` 并将其存储在配置文件中。Git使用HTTP 基本的 **帐户用户名和密码**，而不是API令牌。

因为这个原因 `login` 默认情况下仅存储令牌。添加 `--save-password` 还要存储密码，这就使得 `push`， `pull`， `clone` 私有存储库和 `new --init` 没有另一个提示的工作：

```bash
microgit login --save-password
```

密码以明文形式存储在配置文件中。文件创建完成 与模式 `600` 在Unix上;在Windows上，用户配置文件权限适用。如果你 不想存起来，就离开 `--save-password` 开了又放 `git` 问一下什么时候 需要凭证，还是设置 `MICROGIT_PASSWORD` 对于一个命令：

```bash
MICROGIT_PASSWORD='alicepass1' microgit push
```

当用户名未更改时，再次登录将保留已保存的密码；通过 `--forget-password` 移除它。

CLI将凭据作为参数传递给git `http.extraHeader`，所以它们是 **不** 写进 `.git/config` 并且不是克隆URL的一部分。

当服务器发布当天的消息时，随后打印该消息 `login`， `register` 和 `whoami`。

## 配置文件

默认位置: `~/.microgit/config.json`． 使用 `MICROGIT_CONFIG` 指向… 不同的文件，例如每个服务器一个：

```bash
MICROGIT_CONFIG=~/.microgit/work.json microgit login --url https://git.example.com
```

壳把它的历史放在旁边，在 `~/.microgit/history`。

用：

```bash
microgit config
microgit config set url https://git.example.com
microgit config set username alice
microgit config unset password
microgit config clear
```

环境变量覆盖一个命令的文件：

| 变量 | 意义 |
| --- | --- |
| `MICROGIT_URL` | 服务器URL |
| `MICROGIT_TOKEN` | API令牌，而不是存储的令牌 |
| `MICROGIT_USERNAME` | 帐户名，也用于git |
| `MICROGIT_PASSWORD` | Git密码，也用于Git |
| `MICROGIT_CONFIG` | 配置文件路径 |
| `NO_COLOR` | 禁用的颜色 |

## 重命名命令行

包名、命令名、横幅、标语、标签、版本、环境前缀 和配置文件夹都住在 [`src/settings.ts`](https://npmcn.com/package/microgit-cli/src/settings.ts)。改变他们 这里和更新 `name` / `bin` 在 `package.json` 来匹配。

## 域

服务器的 `domain` / `publicUrl` 设置更改它返回的克隆URL。 `microgit clone` 和 `microgit new --init` 使用该URL，因此必须解析该名称 从运行CLI的机器中获取。如果公共域只能从 在外部，使用内部URL登录；存储库仍然可以工作，但是 `domain` 构建克隆URL时，在服务器上配置的服务器获胜。

## 退出代码

-   `0` 成功
-   `1` 预期失败（输入错误，服务器错误，git失败）

错误只打印一次，不进行堆栈跟踪。 `--json` 输出仍然是 服务器的JSON(或for `whoami`/`config`（一个具有相同字段的小对象）。

## 故障排除

-   **`You are not signed in`** ——运行 `microgit login`;令牌将在 服务器的 `sessionDays`。
-   **`login` 一直用旧账号登录** -存储的会话是静止的 有效的;通过 `--force` 或运行 `microgit logout` 第一。
-   **`Authentication failed` 在推** - - - - - - `login --save-password`，或设置 `MICROGIT_PASSWORD`;用户名/密码是您的帐户，而不是API令牌。
-   **`No 'origin' remote`** ——使用 `microgit clone <owner/name>` 或者添加一个遥控器 与git。
-   **`Directory is not empty`** - - - - - - `--clone`/`--init` 拒绝覆盖文件； 选择另一个 `--dir`。
-   **`Already a git repository`** - - - - - - `microgit init` 跳过已经存在的文件夹 有 `.git`。
-   **服务器无法访问** ——通过 `--url` 或一组 `MICROGIT_URL`;检查服务器的 `host`， `port` 还有反向代理。

## 常见问题

### microgit-cli 是什么？

用于自托管git服务器的命令行客户端（microgit）

### 如何安装 microgit-cli？

在项目目录运行 npm install microgit-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 microgit，可以用 npx microgit 直接运行。

### microgit-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/microgit-cli 是否存在。

### microgit-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### microgit-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### microgit-cli 可以商用吗？

microgit-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### microgit-cli 还在维护吗？

最新版本 0\.1\.1 发布于 2026/11/04（今天）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。