# gitdash

**Repository Path**: grow-project/gitdash

## Basic Information

- **Project Name**: gitdash
- **Description**: gitdash 是一个本地 Git 仓库状态查看 CLI
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feature/config-mvp
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitdash

gitdash 是一个本地 Git 仓库状态查看 CLI。当前版本聚焦 MVP：通过配置文件或命令行路径解析仓库，并输出分支、工作区脏文件数、ahead/behind 等状态信息。

详细使用和配置参考见 [docs/usage.md](docs/usage.md)。

## 目录

- [当前实现范围](#当前实现范围)
- [安装](#安装)
- [快速开始](#快速开始)
- [命令说明](#命令说明)
- [配置文件](#配置文件)
- [配置项参考](#配置项参考)
- [退出码](#退出码)
- [FAQ](#faq)
- [开发命令](#开发命令)
- [许可证](#许可证)

## 当前实现范围

已实现命令：

- `gitdash init`
- `gitdash status [path...]`
- `gitdash repo list`
- `gitdash config check`

当前 MVP 限制：

- 不支持 `repo add`、`repo remove` 等仓库管理命令。
- `status` 不会默认执行 `git fetch`，ahead/behind 基于本地已有 upstream 信息计算；upstream 不可用时显示 `ERR`。
- 暂不提供 TUI、桌面版或常驻后台服务。
- `app.default_workers` 和 `app.fetch_timeout_seconds` 已可写入配置，但当前代码暂未实际使用。
- `repositories[].enabled` 和 `scan_paths[].enabled` 只有显式设置为 `true` 时才启用。

## 安装

前置要求：

- Go 1.22 或更高版本
- Git 已安装并可在 `PATH` 中调用

从源码编译：

```bash
git clone <repo-url>
cd gitdash
go build -o gitdash ./cmd/gitdash
```

也可以直接安装到 Go bin 目录：

```bash
go install ./cmd/gitdash
```

验证：

```bash
gitdash --help
```

## 快速开始

生成默认配置：

```bash
gitdash init
```

默认会写入：

```text
~/.config/gitdash/config.yaml
```

如果目标文件已存在，`init` 会失败并拒绝覆盖。可以用 `--config` 指定其他路径：

```bash
gitdash init --config ./gitdash.yaml
```

查看配置中的仓库状态：

```bash
gitdash status
```

直接查看指定路径，不需要配置文件：

```bash
gitdash status ~/projects/app ~/projects/lib
```

按分组过滤：

```bash
gitdash status --group work
```

全局参数由当前 CLI 手写解析，支持放在命令前后：

```bash
gitdash --config ./gitdash.yaml status --group work
gitdash status --group work --config ./gitdash.yaml
```

## 命令说明

### `gitdash init`

创建默认配置文件。

```bash
gitdash init
gitdash init --config ./gitdash.yaml
```

行为说明：

- 不带 `--config` 时写入 `~/.config/gitdash/config.yaml`。
- 带 `--config` 时写入指定路径，相对路径会按当前工作目录解析。
- 目标文件已存在时返回错误，不覆盖旧文件。

### `gitdash status [path...]`

输出仓库状态，列为：

```text
NAME  GROUP  BRANCH  DIRTY  AHEAD  BEHIND  PATH
```

用法：

```bash
gitdash status
gitdash status --group work
gitdash status --config ./gitdash.yaml
gitdash status ~/projects/app ~/projects/lib
```

行为说明：

- 传入 `path...` 时进入路径模式，不读取配置文件。
- 不传路径时读取配置文件，解析启用的显式仓库和扫描路径。
- `DIRTY` 是 `git status --porcelain` 的非空行数。
- `AHEAD` 和 `BEHIND` 来自 `HEAD...@{upstream}`；没有 upstream 或计算失败时显示 `ERR`，并在 stderr 输出 WARN。
- `BRANCH` 或 `DIRTY` 读取失败时不会填默认值，命令会输出该仓库的 WARN；当前分支为空但可识别时显示 `detached`。
- `--group` 只对配置模式解析出的仓库生效；路径模式下仓库没有配置分组。

### `gitdash repo list`

列出配置解析后的仓库列表。

```bash
gitdash repo list
gitdash repo list --group work
gitdash repo list --config ./gitdash.yaml
```

输出列为：

```text
NAME  GROUP  PATH
```

注意：`repo list` 会加载配置并解析仓库列表，解析过程中会调用 Git root 校验仓库路径，并不是完全不触碰 Git。

### `gitdash config check`

检查配置中启用的仓库和扫描路径。

```bash
gitdash config check
gitdash config check --config ./gitdash.yaml
```

输出示例：

```text
Config: /Users/me/.config/gitdash/config.yaml
OK    repo       app      /Users/me/projects/app      ok
WARN  repo       missing  /Users/me/projects/missing  path not found
OK    scan_path  default  /Users/me/workspace         ok
```

出现 `WARN` 时命令返回非零退出码。

## 配置文件

未显式指定 `--config` 时，按以下顺序查找第一个存在的配置文件：

1. `./gitdash.yaml`
2. `~/.config/gitdash/config.yaml`
3. `~/.gitdash.yaml`

最小配置示例：

```yaml
scan_paths:
  - path: ~/projects
    group: default
    depth: 3
    enabled: true
```

完整示例：

```yaml
app:
  default_workers: 6
  git_timeout_seconds: 5
  fetch_timeout_seconds: 60

repositories:
  - name: app
    path: ~/projects/app
    group: work
    enabled: true
    tags:
      - backend
  - name: docs
    path: ~/projects/docs
    group: work
    enabled: true

scan_paths:
  - path: ~/workspace
    group: personal
    depth: 3
    enabled: true
    excludes:
      - node_modules
      - vendor
      - target
      - dist
      - build
      - .cache
```

## 配置项参考

### `app`

| 配置项 | 类型 | 默认值 | 当前行为 |
| --- | --- | --- | --- |
| `default_workers` | int | `6` | 暂为配置字段，当前未用于并发控制 |
| `git_timeout_seconds` | int | `5` | `status` 配置模式下的 Git 命令超时时间 |
| `fetch_timeout_seconds` | int | `60` | 暂为配置字段，当前不会自动 fetch |

### `repositories[]`

| 配置项 | 类型 | 默认值 | 当前行为 |
| --- | --- | --- | --- |
| `name` | string | 路径目录名 | 显示名称 |
| `path` | string | 无 | 仓库路径，支持 `~` 展开 |
| `group` | string | 空字符串 | 分组名，可被 `--group` 过滤 |
| `enabled` | bool | `false` | 只有显式 `true` 才启用 |
| `tags` | []string | 空列表 | 会被解析保存，当前 CLI 输出暂未展示 |

### `scan_paths[]`

| 配置项 | 类型 | 默认值 | 当前行为 |
| --- | --- | --- | --- |
| `path` | string | 无 | 扫描根目录，支持 `~` 展开 |
| `group` | string | 空字符串 | 扫描发现仓库的分组 |
| `depth` | int | `3` | 递归扫描深度 |
| `enabled` | bool | `false` | 只有显式 `true` 才启用 |
| `excludes` | []string | 空列表 | 按目录名排除扫描 |

## 全局参数

| 参数 | 说明 |
| --- | --- |
| `--config <path>` / `--config=<path>` | 指定配置文件路径 |
| `--group <name>` / `--group=<name>` | 按分组过滤仓库 |
| `-h` / `--help` | 显示帮助 |

全局参数会先被提取，所以可以出现在命令前或命令后。

## 退出码

| 退出码 | 含义 |
| --- | --- |
| `0` | 成功 |
| `1` | 运行失败，或执行完成但存在 WARN |
| `2` | 参数错误、缺少命令或未知命令 |

说明：

- `config check` 只要出现 `WARN` 就返回 `1`。
- `status` 或 `repo list` 解析仓库时出现警告，也会返回 `1`。
- 配置文件读取失败、配置解析失败、`init` 创建失败也返回 `1`。

## FAQ

### 提示找不到配置文件怎么办？

可以先生成默认配置：

```bash
gitdash init
```

也可以指定配置文件：

```bash
gitdash status --config ./gitdash.yaml
```

如果只是临时查看几个仓库，可以直接传路径，路径模式不需要配置文件：

```bash
gitdash status ~/projects/app
```

### 为什么配置了仓库却没有显示？

请确认对应条目显式设置了 `enabled: true`。当前实现不会把省略 `enabled` 的条目视为启用。

### 为什么 ahead/behind 显示 `ERR`？

`gitdash status` 当前不会自动执行 `git fetch`，也不会把 upstream 缺失或读取失败伪装成 `0`。请先确认当前分支设置了 upstream，并在需要时手动 fetch 或用其他脚本定期更新远程引用。

### `repo list` 会执行 Git 命令吗？

会。它需要解析并校验仓库根目录，因此会调用 Git root 相关命令。

### 是否支持添加仓库命令？

暂不支持。当前需要手动编辑 YAML 配置文件。

## 开发命令

```bash
# 运行全部测试
go test ./...

# 运行指定包测试
go test ./internal/cli
go test ./internal/config
go test ./internal/repos
go test ./internal/git

# 编译 CLI
go build -o gitdash ./cmd/gitdash
```

主要代码位置：

| 路径 | 说明 |
| --- | --- |
| `cmd/gitdash/main.go` | CLI 入口 |
| `internal/cli/cli.go` | 参数解析、命令路由、输出 |
| `internal/config/config.go` | YAML 加载、默认值、配置路径解析 |
| `internal/repos/repos.go` | 仓库解析、扫描、去重、配置检查 |
| `internal/git/git.go` | Git root 和状态读取 |

## 许可证

当前仓库暂未声明许可证。