Git Branch Management Skill
This skill guides AI agents and human contributors on how to create, name, structure, and navigate Git branches in the **GitHub Backup Automation System** repository.
1. Core Branching Principles
**Mandatory Local Branch Creation**: Prior to modifying any code, configuration, or documentation files for ANY task, you MUST ALWAYS create and switch to a dedicated local branch (`git switch -c <github-username>/<parent-branch>/<feature>`). Never develop or commit directly on `main` or `dev`.**Branch-First Development**: All changes (features, fixes, refactoring, tests, docs) are developed directly on Git branches created from `main`.**Strict No-Worktree Rule**: AI agents and contributors must **NOT** create or use Git worktrees for standard development tasks. All work occurs in the primary repository clone via branch switching (`git switch -c`).**Structured Hierarchical Naming**: Branch names follow the standard format `<github-username>/<parent-branch>/<feature>`.**All Pull Requests Target `main`**: `main` is the sole production integration branch. Never open PRs against `dev` or temporary feature branches.**Agent Safety Boundaries**: * Agents may create or switch between local branches directly.
* **STRICT RULE**: Agents MUST NOT push branches to a remote repository automatically. Pushing and opening PRs is permitted ONLY upon explicit human request.
* **STRICT RULE**: Agents MUST NEVER force-push (`git push --force`) or delete remote branches.
2. Branch Naming Convention
All development branches MUST follow the standard structure:
<github-username>/<parent-branch>/<feature>
Components Breakdown
`<github-username>`: GitHub username of the author (e.g. `MishraShardendu22`).`<parent-branch>`: Target base branch name (typically `main`).`<feature>`: Concise, kebab-case description of the feature or fix (e.g. `database-auto-sync`, `precommit-workflow`, `branch-first-migration`).Rules
**Lowercase**: All characters lowercase.**Kebab-Case**: Hyphen-separated words for the feature portion.**Concise**: 2–4 descriptive words.**No Timestamps/Hashes**: Avoid timestamps or random suffixes unless required for uniqueness.
3. Canonical Branch Workflow Runbook
For Human Contributors
# 1. Update main branch
git checkout main
git pull origin main
# 2. Create and switch to new branch
git switch -c MishraShardendu22/main/my-feature
# 3. Develop, validate, and commit
make pre-commit
git add .
git commit -s -S -m "feat(worker): add new capability"
# 4. Push and open PR
git push -u origin MishraShardendu22/main/my-feature
gh pr create --base main --head MishraShardendu22/main/my-feature --title "feat(worker): add new capability" --body "..."
For AI Agents
Inspect repository and branch status (do NOT spawn worktrees): ```bash
git status
git branch -a
```
Switch to `main` and pull latest changes: ```bash
git switch main
git pull origin main
```
Create local branch: ```bash
git switch -c <github-username>/<parent-branch>/<feature>
```
Develop directly on that branch, run `make pre-commit`, and commit locally with `-s` and `-S`.When explicitly requested by the user, push to remote and open a PR targeting `main`.
4. Single Open PR Mandate & Preventing Merge Conflicts
To ensure continuous delivery without merge conflict deadlock:
**Mandatory Pre-Branch Check**: Always run `gh pr list --state open` before creating a new branch.**Consolidate into Existing Open PR**: If an open PR already exists targeting `main`, DO NOT create a new branch or open a secondary PR. Check out the existing PR's branch (`git checkout <open-branch>`), implement all requested changes there, and push to that same branch.**Open New PR Only on Clean State**: Create a new feature branch and open a new PR ONLY when zero open PRs exist.**Rebasing**: If `main` is updated while a PR is open, rebase your branch on `origin/main` (`git fetch origin && git rebase origin/main`), re-verify with `make pre-commit`, and push with `--force-with-lease`.
5. Merging & Local Branch Cleanup
Once a Pull Request is merged into `main` on GitHub and upon explicit human user instruction, perform safe branch cleanup and repository garbage collection: ```bash
make git-clean
```
Or manual sequence:
```bash
git switch main
git pull origin main
git fetch --prune origin
git branch | grep -v "^\* main$" | grep -v "^ main$" | xargs -r git branch -D
git reflog expire --expire=now --all
git gc --prune=now --aggressive
```
**Explicit Instruction Only**: AI agents must only execute branch cleanup when explicitly asked by the user after PR merge.See [`.agents/skills/git-post-merge-cleanup/SKILL.md`](../git-post-merge-cleanup/SKILL.md).