# gqueue 参考
`gqueue` 用于查看任务列表，支持筛选、格式化输出，以及树/分组视图。
## 用法
```bash
gqueue [options]
gqueue completion <shell>
```
## 常用示例
```bash
gqueue # 当前用户的活跃任务（Queued、Hold、Running）
gqueue -a # 所有任务（包含已完成任务）
gqueue -s Running,Queued # 按状态筛选
gqueue -j 12,13,14 # 按任务 ID 筛选（逗号分隔）
gqueue -u alice # 按用户筛选（默认当前用户；用 'all' 表示所有用户）
gqueue -P ml-research # 按项目编码筛选
gqueue -T # 仅显示有活跃 tmux 会话的任务
gqueue -t # 依赖树视图
gqueue -g # 按状态分组
gqueue -w # 每 2 秒自动刷新
gqueue -w --interval 5 # 每 5 秒自动刷新
```
## 输出格式
默认格式：
```text
JOBID,NAME,ST,TIME,NODES,NODELIST(REASON)
```
自定义格式：
```bash
gqueue -f JOBID,NAME,PROJECT,ST,TIMELIMIT,MEMORY,NODELIST(REASON)
```
`-f/--format` 支持的字段：
- `JOBID`
- `NAME`
- `ST`
- `TIME`
- `TIMELIMIT`
- `MEMORY`
- `NODES`（请求的 GPU 数量）
- `NODELIST(REASON)`（运行中：GPU 索引；排队/暂停/已取消：原因）
- `USER`
- `PROJECT`
`gqueue -t` 示例输出：
```
JOBID NAME ST TIME NODES NODELIST(REASON)
1 prep CD 00:02:15 0 -
├─2 train R 00:10:03 1 0
└─3 eval PD - 0 (WaitingForDependency)
```
## 选项
- `-n, --limit <N>`：显示前/后 N 个任务（正数：前 N 个；负数：后 N 个；`0`：全部；默认：`0`）
- `-a, --all`：显示所有任务，包括已完成任务
- `-c, --completed`：仅显示已完成任务
- `--since <when>`：显示自 `1h`、`2d`、`3w`、`today`、`yesterday` 或时间戳以来的任务
- `-r, --sort <field>`：`id`、`state`、`time`、`name`、`gpus`、`priority`
- `-s, --states <list>`：状态列表（如 `Queued,Running`）
- `-u, --user <list>`：用户列表（默认当前用户；用 `all` 表示所有用户；别名：`--users`）
- `-j, --jobs <list>`：任务 ID 列表（如 `1,2,3`；别名：`--job`）
- `-N, --names <list>`：任务名列表
- `-P, --project <code>`：按项目编码筛选
- `-f, --format <fields>`：输出字段列表
- `-g, --group`：按状态分组
- `-t, --tree`：树视图（依赖 + redo 关系）
- `-T, --tmux`：仅显示有活跃 tmux 会话的任务
- `-w, --watch`：自动刷新任务列表（默认每 2 秒）
- `--interval <N>`：`--watch` 模式的刷新间隔（秒，默认：`2`）