# Gitflow

> Git Flow branching model - a philosophy for versioned releases, implemented with pure git commands (no tools required)

- **Type:** Skill
- **Install:** `agentstack add skill-hughedward-gitflow-skills-gitflow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hughedward](https://agentstack.voostack.com/s/hughedward)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hughedward](https://github.com/hughedward)
- **Source:** https://github.com/hughedward/gitflow-skills/tree/main/skills/gitflow
- **Website:** https://gitflow-skills.vercel.app/

## Install

```sh
agentstack add skill-hughedward-gitflow-skills-gitflow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Git Flow

> **Note on Branch Names**: Examples use default Git Flow naming (`main`, `develop`, `feature/*`, `release/*`, `hotfix/*`).
> If your `.gitflow` config uses custom names (e.g., `dev` instead of `develop`), substitute accordingly.

## Philosophy: Branching Model, NOT a Tool

Git Flow is a **branching strategy protocol** - a set of conventions for how to organize your branches. It is NOT dependent on any specific tool.

```
┌─────────────────────────────────────────────────────────┐
│  Git Flow 理念  →  用原生 git实现  ✓                      │
│  Git Flow 工具  →  可选，非必须  (optional)              │
└─────────────────────────────────────────────────────────┘
```

### Core Branch Structure

| Branch | Purpose | Lifetime |
|--------|---------|----------|
| `main`/`master` | Production-ready code | Indefinite |
| `develop` | Integration branch for features | Indefinite |
| `feature/*` | Develop new features | Short-term |
| `release/*` | Prepare production release | Short-term |
| `hotfix/*` | Fix critical production bugs | Short-term |

### Why Pure Git?

The git-flow-avh CLI tool is just a wrapper around native git commands. Understanding the underlying git commands gives you:
- **No dependencies** - works anywhere git is installed
- **Full control** - understand and customize each operation
- **Debugging** - know exactly what's happening
- **Portability** - not tied to a specific tool

## Quick Start

**For new repository setup:** See "Initialize Repository" below

**For daily workflow:** Use the workflow decision tree to determine which operation to perform

## Workflow Decision Tree

```
Need to work on Git Flow repository?
│
├─ New feature? → Feature Workflow
├─ Prepare release? → Release Workflow
├─ Fix production bug? → Hotfix Workflow
└─ New repository? → Initialize Repository
```

## Initialize Repository

Set up a new repository with Git Flow branches:

### Pure Git Method (Recommended)

```bash
# 1. Ensure you're on main/master
git checkout main

# 2. Create develop branch from main
git checkout -b develop

# 3. Push both branches to remote
git push -u origin main
git push -u origin develop
```

### Using Helper Script

```bash
bash scripts/setup_gitflow.sh
```

### Optional: git-flow-avh Tool

If you have git-flow-avh installed:

```bash
git flow init      # Interactive setup
git flow init -d   # Use defaults
```

**After initialization, you should be on the `develop` branch.**

## Feature Workflow

Use feature branches for developing new features for upcoming releases.

### Start a Feature

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bashgit checkout developgit checkout -b feature/``` | ```bashgit flow feature start ``` |

**Example (Pure Git):**
```bash
git checkout develop
git checkout -b feature/user-authentication
```

This creates `feature/user-authentication` from `develop`.

### Finish a Feature

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bashgit checkout developgit merge --no-ff feature/git branch -d feature/``` | ```bashgit flow feature finish ``` |

**Example (Pure Git):**
```bash
git checkout develop
git merge --no-ff feature/user-authentication
git branch -d feature/user-authentication
```

This:
- Merges `feature/user-authentication` to `develop` using `--no-ff`
- Deletes the feature branch
- Switches back to `develop`

**Note:** `--no-ff` (no fast-forward) preserves feature history in the graph.

### Publish a Feature (Team Collaboration)

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bashgit push -u origin feature/``` | ```bashgit flow feature publish ``` |

**Checkout remote feature:**
```bash
git fetch origin
git checkout feature/
```

**Pull latest changes:**
```bash
git pull origin feature/
```

## Release Workflow

Use release branches when preparing for a new production release. This allows bug fixes and version bumping.

### Start a Release

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bashgit checkout developgit checkout -b release/``` | ```bashgit flow release start ``` |

**Example (Pure Git):**
```bash
git checkout develop
git checkout -b release/1.2.0
```

This creates `release/1.2.0` from `develop`.

### Publish a Release

```bash
git push -u origin release/
```

### Finish a Release

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bash# Merge to main and taggit checkout maingit merge --no-ff release/git tag -a  -m "Release "# Merge back to developgit checkout developgit merge --no-ff release/# Cleanupgit branch -d release/``` | ```bashgit flow release finish ``` |

**Example (Pure Git):**
```bash
# Merge to main and tag
git checkout main
git merge --no-ff release/1.2.0
git tag -a 1.2.0 -m "Release version 1.2.0"

# Merge back to develop
git checkout develop
git merge --no-ff release/1.2.0

# Cleanup
git branch -d release/1.2.0
```

This:
- Merges `release/1.2.0` to `main` using `--no-ff`
- Tags the merge with version name
- Merges `release/1.2.0` back to `develop` using `--no-ff`
- Deletes the release branch
- Switches back to `develop`

**Push tags to remote:**
```bash
git push origin main
git push origin develop
git push origin   # Push the tag
```

## Hotfix Workflow

Use hotfix branches to fix critical production bugs immediately.

### Start a Hotfix

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bashgit checkout maingit checkout -b hotfix/``` | ```bashgit flow hotfix start ``` |

**Example (Pure Git):**
```bash
git checkout main
git checkout -b hotfix/1.2.1
```

This creates `hotfix/1.2.1` from `main/master`.

### Finish a Hotfix

| Pure Git | git-flow Tool (Optional) |
|----------|--------------------------|
| ```bash# Merge to main and taggit checkout maingit merge --no-ff hotfix/git tag -a  -m "Hotfix "# Merge back to developgit checkout developgit merge --no-ff hotfix/# Cleanupgit branch -d hotfix/``` | ```bashgit flow hotfix finish ``` |

**Example (Pure Git):**
```bash
# Merge to main and tag
git checkout main
git merge --no-ff hotfix/1.2.1
git tag -a 1.2.1 -m "Hotfix: Fix critical login bug"

# Merge back to develop
git checkout develop
git merge --no-ff hotfix/1.2.1

# Cleanup
git branch -d hotfix/1.2.1
```

This:
- Merges `hotfix/1.2.1` to `main/master` using `--no-ff`
- Tags the merge with version name
- Merges `hotfix/1.2.1` back to `develop` using `--no-ff`
- Deletes the hotfix branch
- Switches back to `develop`

**Exception:** If a release branch exists, merge the hotfix into that release branch instead of develop.

## Helper Scripts

This skill includes helper scripts for common Git Flow operations:

**All scripts use pure git commands - no git-flow-avh dependency required.**

- `scripts/gitflow_helper.sh` - Interactive menu for all Git Flow operations
- `scripts/setup_gitflow.sh` - Initialize Git Flow repository (pure git)
- `scripts/gitflow_status.sh` - Show current Git Flow status (pure git)

**Usage:**

```bash
# Run interactive helper
bash scripts/gitflow_helper.sh

# Check Git Flow status
bash scripts/gitflow_status.sh

# Setup new Git Flow repository
bash scripts/setup_gitflow.sh
```

## Branch Summary

| Branch Type | Branch From | Merge To | Naming Convention | Lifetime |
|-------------|-------------|----------|-------------------|----------|
| **main/master** | - | - | `main` or `master` | Indefinite |
| **develop** | - | - | `develop` | Indefinite |
| **feature** | `develop` | `develop` | `feature/*` | Short-term |
| **release** | `develop` | `develop`, `main` | `release/*` | Short-term |
| **hotfix** | `main` | `develop`, `main` | `hotfix/*` | Short-term |

## Best Practices

1. **Always use `--no-ff`** when merging - preserves feature history and enables easy reversion
2. **Keep feature branches focused** - one feature per branch
3. **Write descriptive commit messages** - explain what and why, not just how
4. **Tag releases** - use semantic versioning (e.g., `1.2.0`)
5. **Pull before starting** - ensure `develop` is up-to-date before starting features
6. **Understand the git commands** - the git-flow tool is optional; knowledge of pure git commands is universal

## Quick Reference: Pure Git Commands

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         Git Flow: Pure Git Cheat Sheet                  │
├─────────────────────────────────────────────────────────────────────────┤
│ FEATURE START:   git checkout develop && git checkout -b feature/ │
│ FEATURE FINISH:  git checkout develop && git merge --no-ff feature/                        │
├─────────────────────────────────────────────────────────────────────────┤
│ RELEASE START:   git checkout develop && git checkout -b release/  │
│ RELEASE FINISH:  git checkout main && git merge --no-ff release/   │
│                  && git tag -a  -m "Release "                 │
│                  && git checkout develop && git merge --no-ff release/                         │
├─────────────────────────────────────────────────────────────────────────┤
│ HOTFIX START:    git checkout main && git checkout -b hotfix/      │
│ HOTFIX FINISH:   git checkout main && git merge --no-ff hotfix/    │
│                  && git tag -a  -m "Hotfix "                  │
│                  && git checkout develop && git merge --no-ff hotfix/                          │
└─────────────────────────────────────────────────────────────────────────┘
```

## Common Issues

**Issue:** "Not a gitflow repository" (when using git-flow tool)
- **Solution:** Run `git flow init` first, or just create the branches manually with pure git

**Issue:** Merge conflicts during finish
- **Solution:** Resolve conflicts, then `git add` the files, `git commit` to complete the merge

**Issue:** Feature branch name contains invalid characters
- **Solution:** Use alphanumeric and hyphens only (e.g., `user-auth` not `user_auth`)

**Issue:** develop branch doesn't exist
- **Solution:** Create it from main: `git checkout main && git checkout -b develop`

## When NOT to Use Git Flow

Git Flow is NOT ideal for:
- **Continuous delivery** teams - consider GitHub Flow or trunk-based development instead
- **Single developer** projects - overhead may not be justified
- **Web services** with frequent deployments - simpler workflows work better

Git Flow IS ideal for:
- Versioned software releases
- Projects with scheduled release cycles
- Teams supporting multiple production versions
- Mobile apps with app store review processes

## References

See [references/workflow.md](references/workflow.md) for detailed workflow diagrams and advanced patterns.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hughedward](https://github.com/hughedward)
- **Source:** [hughedward/gitflow-skills](https://github.com/hughedward/gitflow-skills)
- **License:** MIT
- **Homepage:** https://gitflow-skills.vercel.app/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hughedward-gitflow-skills-gitflow
- Seller: https://agentstack.voostack.com/s/hughedward
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.