npm package: @roeus/gitsync
Description: CLI to check git sync status of repos in current directory
Latest version: 1.0.1

# gitsync

[![npm version](https://img.shields.io/npm/v/@roeus/gitsync)](https://www.npmjs.com/package/@roeus/gitsync)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)

CLI tool that scans directories for git repos and reports their sync status.

## Demo

<!-- TODO: Add terminal GIF/screenshot showing gitsync output -->

## Why gitsync?

Working across multiple git repositories? It's easy to forget uncommitted changes, unpushed commits, or branches without upstreams.

gitsync gives you a quick overview of all repos in a directory so nothing falls through the cracks.

## Features

- Detect uncommitted changes
- Track ahead/behind status vs remote
- Find branches without upstream tracking
- Multiple output formats: JSON, table, minimal
- Recursive directory scanning
- Config file support (cosmiconfig)

## Install

```bash
npm install -g @roeus/gitsync
```

Or build locally:

```bash
git clone https://github.com/syz51/gitsync.git
cd gitsync
pnpm install
pnpm run build
pnpm link --global
```

## Usage

```bash
gitsync [options] [paths...]
```

### Options

| Flag                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `-a, --all`           | Show all repos (not just outstanding)              |
| `-f, --format <type>` | Output: `json`, `table`, `minimal` (default: json) |
| `-q, --quiet`         | Suppress output                                    |
| `-r, --recursive`     | Scan recursively                                   |
| `-d, --depth <n>`     | Max depth (default: 1)                             |
| `--include-hidden`    | Include hidden directories                         |
| `--filter <types>`    | Filter: `changes,ahead,behind,untracked`           |
| `--dir <path>`        | Config file search directory                       |

### Examples

```bash
# scan current dir, show only repos with issues
gitsync

# show all repos as table
gitsync -a -f table

# recursive scan, filter to repos with uncommitted changes
gitsync -r --filter changes

# scan specific directories
gitsync ~/projects ~/work

# combine filters
gitsync --filter changes,ahead
```

## Config File

Supports `.gitsyncrc`, `.gitsyncrc.json`, `.gitsyncrc.yaml`, `gitsync.config.js`, or `package.json` field.

Example `.gitsyncrc.json`:

```json
{
  "format": "table",
  "recursive": true,
  "depth": 2
}
```

CLI args override config file values.

## Output

By default shows repos with issues:

- uncommitted changes
- ahead/behind remote
- no upstream
- untracked branches

### JSON (default)

```json
[{"name": "repo", "uncommittedChanges": 3, "ahead": 1, ...}]
```

### Table

```text
REPO     BRANCH  CHANGES  AHEAD  BEHIND  UNTRACKED
my-repo  main    3        1      0       feature-x
```

### Minimal

```text
my-repo (main): 3 changes, 1 ahead, [feature-x]
```

## Requirements

- Node.js >= 24
- git

## Development

```bash
git clone https://github.com/syz51/gitsync.git
cd gitsync
pnpm install
pnpm run build

# test locally
pnpm link --global
gitsync
```

## Contributing

1. Fork the repo
2. Create a feature branch
3. Make changes
4. Submit a PR

## License

MIT