# git flutter CLI

[![Validate](https://github.com/Flutter-Global/fsc-git-flutter/actions/workflows/validate.yml/badge.svg)](https://github.com/Flutter-Global/fsc-git-flutter/actions/workflows/validate.yml)

Git workflow automation CLI for Flutter teams. Implements service and multiple-teams branching models with semantic versioning, OpenTelemetry tracing, and golden-file integration testing.

## Overview

Automates feature, hotfix, release, and support branch workflows according to configurable branching strategies. Commands enforce confirmation before write operations, prefer origin by default, and output structured recap/progress/result messages.

**User documentation**: https://innersource.flutter.com/git-flutter/
**Support**: [#inner-source](https://slack.com/app_redirect?channel=C0115SW13V5) or InnerSourceTeam@flutter.com

## Quick Start

```bash
make
./git-flutter --help
./git-flutter feature my-feature --team myteam
```

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for complete development setup, code standards, testing guidelines, and PR requirements.

## Project Structure

| Directory | Purpose |
|-----------|---------|
| `cli/` | Entry point with version injection and error handling |
| `cmd/` | Command implementations (feature, hotfix, release, push, sync, status, tag) |
| `git/` | Git CLI abstraction (checkout, branches, tags, config, merge, push) |
| `model/` | Domain model (branches with behind/ahead tracking, version resolution) |
| `config/` | Branching model providers (service, multiple-teams) |
| `branch/` | Branch reference types and enumerations |
| `style/` | Terminal UI (styled output, confirmation prompts) |
| `semver/` | Semantic versioning with alpha/beta/feat/released phases |
| `mock/` | Testing utilities for in-memory Git operations |
| `integration/` | Integration tests using compiled binary and golden files |

## Documentation

| Document | Description |
|----------|-------------|
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development setup, code standards, testing, PR requirements |
| [cmd/README.md](cmd/README.md) | Command behavior conventions and output patterns |
| [integration/README.md](integration/README.md) | Integration test framework and golden file workflow |

## Branching Models

**Service model** (`config.Service`): Single develop branch (typically `main`), feature/hotfix branches, optional support branches for maintenance releases. See https://innersource.flutter.com/sdlc/service/

**Multiple teams model** (`config.MultipleTeams`): Team-isolated develop branches (`team/develop`), team-scoped features/releases (`team/feature/*`, `team/release/*`), shared hotfix branches. See https://innersource.flutter.com/sdlc/multiple-teams/

## CI/CD

**Pull requests**: Lint (golangci-lint v1.64.5), test on Linux/macOS/Windows, SonarCloud analysis
**Releases**: Triggered on `v*` tags, builds multi-platform binaries with macOS code signing and notarization, publishes to GitHub releases, triggers org-site version update

## Testing Strategy

**Unit tests**: Use `mock/` package for in-memory Git operations, run with race detector
**Integration tests**: Compile binary with coverage instrumentation, execute via `GIT_FLUTTER_BINARY_PATH`, assert output against `testdata/*.golden` files
**Test patterns**: `*_mt_test.go` for multiple-teams model, `*_srv_test.go` for service model

## Command Conventions

All commands follow these patterns:
- No write operations without user confirmation (override with `--yes`)
- Prefer origin/remote operations (override with `--no-network`)
- Structured output: recap line, progress indicators, result with next steps
- Team specification via `--team` flag for multiple-teams model
- Source path override via `--source-path` for non-CWD repositories

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code standards, and PR requirements.
