Metadata-Version: 2.4
Name: blink-repo
Version: 2.0.0
Summary: A lightweight TUI to scan, search, and manage local git repositories
License-Expression: MIT
Project-URL: Homepage, https://github.com/russell/blink
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: prompt-toolkit<4.0,>=3.0
Requires-Dist: click<9.0,>=8.0

# Blink

**你的终端里，住着一个仓库管家。**

Blink 是一个轻量级的终端工具集，帮助开发者高效管理本地 Git 仓库。双栏交互界面，打开即用，无需离开终端。

---

## 它能做什么？

### 仓库管理器 (TUI)

在一个漂亮的终端界面中，浏览、搜索和管理你所有的 Git 仓库：

- **自动发现** — 扫描指定目录，自动识别所有 Git 仓库，结果持久化到本地数据库
- **实时状态** — 并行获取分支名、脏文件数、ahead/behind 等信息，一目了然
- **全文搜索** — 按名称、路径、远程 URL、标签、描述实时过滤
- **一键操作** — Enter 退出并跳转项目目录，打开 IDE、终端、Finder、浏览器跳转远程仓库
- **快捷拉取** — 无需手动输入 git 命令，一键拉取最新代码
- **个性化标记** — 为仓库设置置顶、别名、标签和描述，快速识别

```
┌───────────────────────┬──────────────────────────────────────────┐
│ ── Repos ──────────   │ ── Detail ────────────────────────────── │
│   ▸ ★ name [tag]     │     Name      repo-name                  │
│     /path/to/repo    │     Path      /path/to/repo              │
│                      │     Repo      https://github.com/...      │
│                      │     Status    main ●                     │
│                      │ ───────────────────────────────────────── │
│                      │   ▸ Terminal  Open in Terminal   [Shift+1]│
│                      │     IDE       Open with IDE      [Shift+2]│
│                      │     Finder    Open in Finder      [Shift+3]│
│                      │ ───────────────────────────────────────── │
│                      │     Git       Open in Browser     [Shift+4]│
│                      │     Pull      Pull Changes         [Shift+5]│
└───────────────────────┴──────────────────────────────────────────┘
```

### 项目列表 (CLI)

不想打开交互界面？一行命令拿到全部本地项目：

- **全量输出** — `blink list` 列出所有本地 Git 仓库的路径
- **先扫后列** — 每次返回结果前都重新扫描本地 Git 仓库，结果始终是最新的
- **按目录筛选** — 指定一个项目目录，只列出它下面的仓库
- **表格视图** — `blink list -l` 显示名称、标签和描述

---

## 为什么用 Blink？

|  |  |
|---|---|
| **零配置启动** | `pip install` 后直接运行，首次自动扫描，无需任何设置 |
| **不离开终端** | 全部操作在终端内完成，无需切换窗口 |
| **键盘优先** | 所有操作都有快捷键，`Shift+数字` 一键触发 |
| **持久化缓存** | 仓库信息存储在本地 SQLite，二次启动瞬间加载 |
| **轻量依赖** | 核心仅依赖 prompt-toolkit、click |

---

## 快速开始

### 安装

```bash
pip install blink-repo
```

### 启动

```bash
blink              # 启动仓库管理器
```

首次启动会扫描主目录下的 Git 仓库，完成后自动打开 TUI 界面。后续启动直接使用缓存，同时自动清理失效条目。

### 常用命令

```bash
blink                          # 启动 TUI
blink -R                       # 强制重新扫描
blink list                     # 重新扫描并列出全部本地仓库
blink list ~/work              # 只列出 ~/work 下的仓库
blink list -l                  # 表格输出名称/标签/描述
```

---

## 快捷键

所有快捷键在列表和详情面板中均可使用：

| 按键 | 功能 |
|------|------|
| `↑` / `↓` | 导航 |
| `Enter` | 退出并 cd 到项目目录（列表）/ 执行操作（详情） |
| `/` | 搜索（任何焦点下） |
| `→` | 切换到详情面板（窄模式下切换至详情全屏） |
| `Esc` / `←` | 切换回列表（窄模式下切换至列表全屏） |
| `Shift+1` | 打开终端 |
| `Shift+2` | 用 IDE 打开 |
| `Shift+3` | 在 Finder 中打开 |
| `Shift+4` | 浏览器打开远程仓库 |
| `Shift+5` | 拉取最新代码 |
| `Shift+R` | 重新扫描 |
| `Shift+S` | 打开配置面板 |
| `Ctrl+C` ×2 | 退出 |

### 搜索

按 `/` 展开搜索框，实时过滤仓库。搜索范围：名称、别名、描述、路径、远程 URL、标签。Enter 隐藏搜索框保留结果，Esc 清空恢复全部。

---

## 配置

首次运行在 `~/.blink/config.json` 创建默认配置：

```json
{
  "scan_paths": ["~"],
  "exclude_dirs": [".Trash", ".cache", ".npm", ".docker", "Library", "node_modules"],
  "editor": null,
  "auto_sync_days": 0,
  "nerd_fonts": false
}
```

| 字段 | 说明 |
|------|------|
| `scan_paths` | 扫描 Git 仓库的根目录列表 |
| `exclude_dirs` | 扫描时跳过的目录名 |
| `editor` | 首选 IDE 名称（如 `VSCode`、`Cursor`），首次使用时自动选择 |
| `auto_sync_days` | 自动重新扫描间隔天数（0 禁用） |
| `nerd_fonts` | 启用 Nerd Font 图标 |

可在 TUI 中按 `Shift+S` 打开配置面板直接修改 `editor`。

所有数据存储在 `~/.blink/` 目录下。

---

## 开发

Blink 使用 Python 3.9+ 和 [uv](https://docs.astral.sh/uv/) 构建。开发环境搭建、测试、调试等详细信息请参阅 [开发指南](docs/development.md)。

快速上手：

```bash
git clone <repo-url> blink && cd blink
uv sync                    # 安装依赖
uv run blink               # 启动 TUI
uv run pytest              # 运行测试
```

---

## 许可证

MIT
