> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git Branching & Workflow

> Git branching strategy and workflow best practices

<Warning>
  **Follow this workflow for all repositories** to maintain clean history, minimize conflicts, and ensure production stability.
</Warning>

This document explains **how we branch, commit, and merge** so that:

* History stays clean
* Merge conflicts are rare (and small when they happen)
* Production is always stable
* Work-in-progress is easy to manage

***

## Goals

<CardGroup cols={2}>
  <Card title="Stable Main" icon="check-circle">
    `main` is always deployable and production-ready
  </Card>

  <Card title="Short-lived Branches" icon="clock">
    Every change goes through a short-lived branch
  </Card>

  <Card title="Clear Communication" icon="message">
    Branch names and commits tell you what changed and why
  </Card>

  <Card title="Minimal Conflicts" icon="shield">
    Conflicts minimized through small branches and frequent syncs
  </Card>
</CardGroup>

***

## Branch Types

We keep it simple and modern:

* **`main`** – production-ready, stable code
* **`dev`** (optional, for larger teams) – integration branch, where feature branches are merged before going to `main`
* **`feature/*`, `fix/*`, `chore/*`** – topic branches for actual work

### Solo or Small Team

<Info>
  Just use `main` + `feature/*` branches. Merge `feature/*` → `main` via pull requests (even if it's just you).
</Info>

**Branches:**

* `main`
* `feature/*` branches

### Larger Collaborator Team

<Info>
  Use a three-tier approach: `feature/*` → `dev` → (when stable) → `main`
</Info>

**Branches:**

* `main` (production)
* `dev` (integration)
* `feature/*` (work branches)

***

## Branch Naming Rules

Use **clear, structured names** that match your commit prefixes:

<Accordion title="Feature Branches">
  ```
  feature/<short-topic>
  ```

  **Examples:**

  * `feature/rn-sdk-upload`
  * `feature/flutter-auth-support`
  * `feature/user-profile-endpoint`
</Accordion>

<Accordion title="Fix Branches">
  ```
  fix/<short-topic>
  ```

  **Examples:**

  * `fix/login-null-crash`
  * `fix/api-timeout-error`
  * `fix/sdk-type-definitions`
</Accordion>

<Accordion title="Chore Branches">
  ```
  chore/<short-topic>
  ```

  **Examples:**

  * `chore/update-deps`
  * `chore/regenerate-sdk`
  * `chore/cleanup-old-files`
</Accordion>

<Accordion title="Refactor Branches">
  ```
  refactor/<short-topic>
  ```

  **Examples:**

  * `refactor/api-client-structure`
  * `refactor/auth-flow-logic`
  * `refactor/database-queries`
</Accordion>

<Accordion title="Hotfix Branches">
  ```
  hotfix/<short-topic>
  ```

  **Examples:**

  * `hotfix/handle-500-error-in-prod`
  * `hotfix/critical-security-patch`
  * `hotfix/payment-gateway-issue`
</Accordion>

<Tip>
  Branch names should match the **commit prefix** and clearly describe the purpose.
</Tip>

***

## Complete Workflow

### Step 1: Create a New Feature Branch

<Steps>
  <Step title="Update main branch">
    ```bash theme={null}
    git checkout main
    git pull origin main
    ```
  </Step>

  <Step title="Create feature branch">
    ```bash theme={null}
    git checkout -b feature/my-new-feature
    ```
  </Step>

  <Step title="Work and commit">
    ```bash theme={null}
    # Make your changes
    git add .
    git commit -m "feat(sdk): add loginWithOtp method"
    ```
  </Step>

  <Step title="Sync with main regularly">
    ```bash theme={null}
    git fetch origin
    git rebase origin/main
    # or: git merge origin/main
    ```
  </Step>

  <Step title="Push branch">
    ```bash theme={null}
    git push -u origin feature/my-new-feature
    ```
  </Step>

  <Step title="Open pull request">
    Open a PR: `feature/my-new-feature` → `main`
  </Step>

  <Step title="Merge and clean up">
    After PR approval, merge using **squash** (recommended) or **rebase & merge**
  </Step>
</Steps>

***

## Merge Strategy

### Squash & Merge (Recommended)

<Check>
  All commits in `feature/*` are squashed into **one commit** on `main`.
</Check>

**Benefits:**

* `main` history stays clean (one commit per feature)
* Small, readable Git log
* Easier to revert a feature if needed

<CodeGroup>
  ```bash Example Result theme={null}
  feat(sdk): add loginWithOtp support
  ```
</CodeGroup>

### Rebase & Merge (Alternative)

<Info>
  Keeps individual commits from the feature branch, but rewrites history to be linear. Good if you have **very clean** small commits.
</Info>

***

## When to Branch

<AccordionGroup>
  <Accordion title="✅ Create a branch when...">
    * You're working on anything that will take more than \~30–60 minutes
    * You're adding a feature, fixing a bug, or doing a refactor
    * You're experimenting, but might want to keep or scrap the work later
  </Accordion>

  <Accordion title="❌ Don't commit directly to main unless...">
    * It's an ultra-trivial change (e.g., fixing a typo in README)
    * And even then—it's often better to still use a branch + PR for consistency
  </Accordion>
</AccordionGroup>

***

## Minimizing Merge Conflicts

<Warning>
  You can't avoid conflicts forever, but you can **dramatically reduce them** with these practices.
</Warning>

### 1. Keep Branches Short-lived

<Tip>
  Aim to merge branches within **1–2 days**, not 1–2 weeks. The longer a branch lives, the more the rest of the codebase moves.
</Tip>

### 2. Sync with Main Regularly

On your feature branch, do this **often**:

<CodeGroup>
  ```bash Rebase (recommended) theme={null}
  git fetch origin
  git rebase origin/main
  ```

  ```bash Merge (alternative) theme={null}
  git fetch origin
  git merge origin/main
  ```
</CodeGroup>

<Info>Rebasing keeps history linear and clean</Info>

### 3. Avoid "Big Bang" Changes

<CardGroup cols={2}>
  <Card title="❌ Don't Do This" icon="xmark">
    Combine formatting + huge refactor + new features in one branch
  </Card>

  <Card title="✅ Do This Instead" icon="check">
    Run formatter in separate `chore/formatting` branch and merge it first
  </Card>
</CardGroup>

### 4. Own Specific Areas

<Info>
  If two people keep editing the **same files**, conflicts are inevitable. Coordinate ownership:

  * SDK core client → one owner at a time
  * Auth flows → one owner at a time
  * Huge config files → modify carefully and incrementally
</Info>

***

## Command Cheat Sheet

<AccordionGroup>
  <Accordion title="Start New Work">
    ```bash theme={null}
    git checkout main
    git pull origin main
    git checkout -b feature/my-feature
    ```
  </Accordion>

  <Accordion title="Add & Commit">
    ```bash theme={null}
    git add .
    git commit -m "feat(api): add /users/search endpoint"
    ```
  </Accordion>

  <Accordion title="Sync with Main">
    ```bash theme={null}
    git fetch origin
    git rebase origin/main
    # or: git merge origin/main
    ```
  </Accordion>

  <Accordion title="Push and Open PR">
    ```bash theme={null}
    git push -u origin feature/my-feature
    # then open PR in GitHub/GitLab
    ```
  </Accordion>

  <Accordion title="After PR Merge">
    ```bash theme={null}
    git checkout main
    git pull origin main
    git branch -d feature/my-feature      # delete local
    git push origin --delete feature/my-feature  # delete remote
    ```
  </Accordion>
</AccordionGroup>

***

## Handling Merge Conflicts

When conflicts occur during `git rebase origin/main` or merge:

<Steps>
  <Step title="Git marks conflicts">
    Files will have conflict markers: `<<<<<<<`, `=======`, `>>>>>>>`
  </Step>

  <Step title="Open and resolve">
    Open those files, manually decide what to keep
  </Step>

  <Step title="Stage resolved files">
    ```bash theme={null}
    git add <file1> <file2>
    ```
  </Step>

  <Step title="Continue the operation">
    ```bash theme={null}
    git rebase --continue   # if rebasing
    # or: git commit         # if merging
    ```
  </Step>
</Steps>

<Tip>
  If a conflict is huge, investigate *why*: big refactor? formatting change? simultaneous edits? In future, break PRs into smaller units and merge formatting/structural changes separately.
</Tip>

***

## Example: SDK Change Workflow

<Note>
  **Scenario:** You add a new endpoint to your API and then regenerate the React Native SDK.
</Note>

### Backend Repository

<CodeGroup>
  ```bash Step 1: Create branch theme={null}
  git checkout -b feature/add-search-endpoint
  ```

  ```bash Step 2: Make changes theme={null}
  # edit openapi.json & backend code
  git add .
  git commit -m "feat(api): add /v1/users/search endpoint"
  ```

  ```bash Step 3: Push and PR theme={null}
  git push -u origin feature/add-search-endpoint
  # open PR, review, squash & merge to main
  ```
</CodeGroup>

### SDK Repository

<CodeGroup>
  ```bash Step 1: Update and branch theme={null}
  git checkout main
  git pull origin main
  git checkout -b feature/sdk-search-endpoint
  ```

  ```bash Step 2: Regenerate SDK theme={null}
  npm run generate   # or your generator script
  git add .
  git commit -m "feat(sdk): add searchUsers client support"
  ```

  ```bash Step 3: Push and release theme={null}
  git push -u origin feature/sdk-search-endpoint
  # open PR, squash & merge to main
  # Then: semantic-release or manual version bump
  ```
</CodeGroup>

***

## Do's and Don'ts

<CardGroup cols={2}>
  <Card title="✅ Do" icon="circle-check" color="#10b981">
    * Use short-lived feature branches
    * Use clear, structured branch names
    * Use Conventional Commits
    * Sync with `main` frequently
    * Use squash merges for clean history
  </Card>

  <Card title="❌ Don't" icon="circle-xmark" color="#ef4444">
    * Work on `main` for real changes
    * Keep branches alive for weeks
    * Combine unrelated changes in one PR
    * Ignore merge conflicts until the end
    * Skip code reviews (even solo)
  </Card>
</CardGroup>

***

## TL;DR Workflow

<Steps>
  <Step title="Start from main">
    ```bash theme={null}
    git checkout main && git pull
    ```
  </Step>

  <Step title="Create branch">
    ```bash theme={null}
    git checkout -b feature/specific-task
    ```
  </Step>

  <Step title="Commit with convention">
    Use [Conventional Commits](/contributing/commit-guide)
  </Step>

  <Step title="Sync regularly">
    ```bash theme={null}
    git rebase origin/main
    ```
  </Step>

  <Step title="Open PR">
    Review → squash & merge into `main`
  </Step>

  <Step title="Delete branch">
    Clean up after merge
  </Step>
</Steps>

<Check>
  Follow this workflow and your repositories will stay **clean, predictable, and conflict-light**.
</Check>