# Git Workflow

## Branch Strategy

### Main Branches

```
main (production)
  └── develop (staging)
```

- **main**: Production-ready code
- **develop**: Integration branch for features

### Supporting Branches

```
develop
  ├── feature/user-authentication
  ├── feature/billing-system
  ├── bugfix/payment-timeout
  └── hotfix/security-patch
```

## Branch Naming Convention

### Feature Branches
```
feature/short-description
feature/user-auth
feature/payment-gateway
```

### Bugfix Branches
```
bugfix/issue-description
bugfix/payment-timeout
bugfix/email-sending
```

### Hotfix Branches
```
hotfix/critical-issue
hotfix/security-vuln
hotfix/data-loss
```

## Commit Message Format

### Structure

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Type

- `feat`: ویژگی جدید
- `fix`: رفع باگ
- `docs`: تغییرات مستندات
- `style`: فرمت‌بندی، فاصله‌گذاری
- `refactor`: بازنویسی کد
- `perf`: بهبود performance
- `test`: اضافه/اصلاح تست
- `chore`: کارهای نگهداری
- `build`: تغییرات build system
- `ci`: تغییرات CI/CD

### Scope

بخشی از کد که تغییر کرده:
- `auth`
- `billing`
- `api`
- `database`
- `ui`

### Examples

```bash
feat(auth): add two-factor authentication

- Implement TOTP-based 2FA
- Add QR code generation
- Add backup codes

Closes #123
```

```bash
fix(payment): resolve timeout issue with zarinpal

The payment gateway was timing out due to long response time.
Added retry logic with exponential backoff.

Fixes #456
```

```bash
docs(api): update authentication endpoints

Added examples for JWT token usage and refresh flow.
```

## Workflow Steps

### 1. شروع کار روی Feature جدید

```bash
# بروزرسانی develop
git checkout develop
git pull origin develop

# ایجاد branch جدید
git checkout -b feature/my-feature

# شروع کدنویسی...
```

### 2. Commit های منظم

```bash
# بررسی تغییرات
git status
git diff

# Stage کردن
git add src/specific/file.py
# یا
git add .

# Commit
git commit -m "feat(scope): description"

# Push (اولین بار)
git push -u origin feature/my-feature

# Push های بعدی
git push
```

### 3. نگهداری Branch به‌روز

```bash
# بروزرسانی از develop
git checkout develop
git pull origin develop

git checkout feature/my-feature
git merge develop

# حل conflict ها (در صورت وجود)
# ... edit files ...
git add .
git commit -m "merge: resolve conflicts with develop"
```

### 4. ایجاد Pull Request

1. Push کردن همه commits
2. رفتن به GitHub/GitLab
3. Create Pull Request
4. انتخاب base: `develop`, compare: `feature/my-feature`
5. عنوان و توضیحات
6. Request reviewers
7. Link کردن issues

### 5. Code Review Process

**برای نویسنده**:
- پاسخ به comments
- انجام تغییرات درخواستی
- Push کردن updates
- Request re-review

**برای Reviewer**:
- بررسی کد با دقت
- Check کردن tests
- بررسی code quality
- Approve یا Request Changes

### 6. Merge

پس از approval:
```bash
# Squash and Merge (توصیه می‌شود)
# یا
# Merge Commit
# یا
# Rebase and Merge
```

### 7. پاک کردن Branch

```bash
# Local
git branch -d feature/my-feature

# Remote (معمولا automatic)
git push origin --delete feature/my-feature
```

## Best Practices

### Commit های کوچک و مشخص

```bash
# ✅ GOOD: Small, focused commits
git commit -m "feat(auth): add email validation"
git commit -m "test(auth): add tests for email validation"
git commit -m "docs(auth): document email validation"

# ❌ BAD: Large, vague commit
git commit -m "add stuff"
```

### Commit منظم

```bash
# Commit هر چند ساعت یکبار
# نه خیلی کم (هر خط کد)
# نه خیلی زیاد (روزی یک commit)
```

### Push روزانه

```bash
# حداقل یکبار در روز push کنید
# از دست رفتن کد جلوگیری می‌کند
```

### استفاده از .gitignore

```bash
# اضافه نکردن فایل‌های غیرضروری
# - __pycache__
# - .env
# - venv/
# - *.pyc
```

## Git Commands Reference

### Basic

```bash
# Status
git status

# Log
git log
git log --oneline
git log --graph

# Diff
git diff
git diff --staged
```

### Branching

```bash
# لیست branches
git branch
git branch -a  # با remote

# ایجاد branch
git branch feature/new-feature
git checkout -b feature/new-feature  # ایجاد + checkout

# تغییر branch
git checkout develop

# حذف branch
git branch -d feature/old-feature
git branch -D feature/force-delete  # Force
```

### Stashing

```bash
# ذخیره تغییرات موقت
git stash

# با پیام
git stash save "work in progress"

# لیست stash ها
git stash list

# برگرداندن stash
git stash apply
git stash pop  # apply + delete

# حذف stash
git stash drop
git stash clear  # همه
```

### Undoing Changes

```bash
# Unstage file
git reset HEAD file.py

# Discard changes
git checkout -- file.py

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Revert commit (safe)
git revert <commit-hash>
```

### Rebasing

```bash
# Rebase on develop
git checkout feature/my-feature
git rebase develop

# Interactive rebase
git rebase -i HEAD~3  # آخرین 3 commits

# Abort rebase
git rebase --abort

# Continue after resolving conflicts
git rebase --continue
```

### Tags

```bash
# ایجاد tag
git tag v1.0.0

# با پیام
git tag -a v1.0.0 -m "Release version 1.0.0"

# Push tags
git push origin v1.0.0
git push origin --tags  # همه tags

# حذف tag
git tag -d v1.0.0
git push origin --delete v1.0.0
```

## Merge Conflicts

### حل Conflict

```bash
# 1. مشاهده conflicts
git status

# 2. باز کردن فایل و حل conflict
# <<<<<<< HEAD
# کد شما
# =======
# کد دیگران
# >>>>>>> branch-name

# 3. Stage کردن
git add resolved-file.py

# 4. Commit
git commit -m "merge: resolve conflicts"
```

### ابزارهای کمکی

```bash
# استفاده از merge tool
git mergetool

# استفاده از --ours یا --theirs
git checkout --ours file.py
git checkout --theirs file.py
```

## Tips & Tricks

### Aliases

```bash
# در ~/.gitconfig
[alias]
    co = checkout
    br = branch
    ci = commit
    st = status
    lg = log --oneline --graph --decorate
```

### Commit Templates

```bash
# در ~/.gitmessage
<type>(<scope>): <subject>

<body>

<footer>
```

```bash
git config --global commit.template ~/.gitmessage
```

### Auto-completion

```bash
# Bash
source /usr/share/bash-completion/completions/git

# Zsh
autoload -Uz compinit && compinit
```

---

**مهم**: این workflow الزامی است و در code review بررسی می‌شود.

