Version Control with Git

This skill equips an AI agent to perform the full spectrum of Git-based version control tasks, from initializing a repository and crafting atomic commits to orchestrating branching strategies, resolving merge conflicts, and configuring automation with hooks. It covers both everyday workflows and advanced operations needed for professional team collaboration.

Workflow

1. Assess Repository State: Run

   git status

   ,

   git log --oneline -10

   , and

   git branch -a

   to understand the current branch, uncommitted changes, recent history, and available remotes. This context determines which operations are safe to perform.

2. Stage and Commit Changes: Group related changes into atomic commits. Write commit messages that start with a concise summary line (50 characters or fewer), followed by a blank line and an explanatory body when the change is non-trivial. Follow the project's commit convention (Conventional Commits, Angular style, etc.) if one exists.

3. Branch Management: Create feature, bugfix, or release branches from the appropriate base. Use a consistent naming convention such as

   feat/short-description

   ,

   fix/issue-123

   , or

   release/1.2.0

   . Delete stale branches after merging to keep the branch list clean.

4. Synchronize with Remote: Fetch and pull regularly to stay up to date. Push feature branches with the

   -u

   flag on first push. Before merging, rebase or merge the base branch into the feature branch to resolve conflicts early in an isolated context.

5. Resolve Conflicts: When conflicts arise, inspect the conflicting files, understand both sides of the change, choose the correct resolution (or combine both), mark the file as resolved with

   git add

   , and complete the merge or rebase. Always run tests after resolution to confirm correctness.

6. Automate with Hooks and CI: Set up Git hooks (pre-commit for linting/formatting, commit-msg for message validation, pre-push for test runs) and ensure

   .gitignore

   covers build artifacts, environment files, and OS metadata. Integrate with CI pipelines to enforce quality gates on every push.

Supported Technologies

• Git (CLI, libgit2)
• Platforms: GitHub, GitLab, Bitbucket, Azure DevOps
• CLI tools:

  gh

  (GitHub CLI),

  glab

  (GitLab CLI)
• Hook frameworks: Husky, pre-commit, Lefthook
• Branching models: GitFlow, GitHub Flow, trunk-based development

Usage

Ask the agent to perform any Git operation by describing what you need in plain language. Examples:

• "Create a feature branch for the new auth module and commit my staged changes."
• "Resolve the merge conflicts in

  src/config.ts

  and complete the merge."
• "Set up a

  .gitignore

  for a Python project with a virtual environment."
• "Rebase my branch onto main and force-push the cleaned-up history."

The agent will verify the repository state before every destructive operation and confirm with you before running commands like

reset --hard

,

push --force

, or

rebase

that rewrite history.

Examples

Example 1 — Resolving a Merge Conflict

Scenario: You are on branch

feat/user-profile

and want to merge

main

, but there is a conflict in

src/utils/format.ts

.

# Attempt the merge
git merge main
# Output: CONFLICT (content): Merge conflict in src/utils/format.ts

# Inspect the conflict markers
git diff --name-only --diff-filter=U
# src/utils/format.ts

The conflicting file contains:

function formatDate(date: Date): string {
<<<<<<< HEAD
  return date.toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" });
=======
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(date);
>>>>>>> main
}

Resolution: The

main

version uses the modern

Intl.DateTimeFormat

API, which is preferred. Accept that version, remove the conflict markers, and complete the merge:

function formatDate(date: Date): string {
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(date);
}

# Mark resolved and commit
git add src/utils/format.ts
git commit -m "merge main into feat/user-profile, adopt Intl.DateTimeFormat"

Example 2 — Setting Up a Branching Strategy (GitHub Flow)

Scenario: A small team wants a lightweight branching model for continuous deployment.

# Ensure main is the default and protected branch
gh repo edit --default-branch main

# Create a feature branch from main
git checkout main && git pull
git checkout -b feat/dark-mode

# ... develop and commit ...
git add .
git commit -m "feat: add dark-mode toggle to settings page

Reads user preference from localStorage and applies the
'dark' class to <html>. Falls back to OS preference via
prefers-color-scheme media query."

# Push and open a pull request
git push -u origin feat/dark-mode
gh pr create \
  --title "feat: add dark-mode toggle" \
  --body "## Summary
- Adds a toggle in Settings that persists to localStorage
- Respects OS-level dark mode preference as default

## Test plan
- [ ] Toggle switches theme immediately
- [ ] Preference persists across page reloads
- [ ] Falls back to OS preference for new users"

# After review and CI pass, merge via GitHub
gh pr merge --squash --delete-branch

Key points:

main

is always deployable, every change goes through a PR with review and CI, and branches are deleted after merge to avoid clutter.

Best Practices

• Write atomic commits. Each commit should represent one logical change that compiles and passes tests on its own. This makes

  bisect

  ,

  revert

  , and

  cherry-pick

  reliable.
• Never commit secrets. Add

  .env

  , credentials files, and private keys to

  .gitignore

  before the first commit. Use tools like

  git-secrets

  or

  trufflehog

  to scan for accidental leaks.
• Rebase feature branches, merge to main. Rebasing keeps feature branch history linear and easy to review; merging into main preserves the merge commit as a clear integration point.
• Use

  --force-with-lease

  instead of

  --force

  . It prevents overwriting teammates' work by failing if the remote has commits you haven't fetched.
• Tag releases. Use annotated tags (

  git tag -a v1.2.0 -m "Release 1.2.0"

  ) for every production release so you can always trace deployed code back to a specific commit.
• Keep

  .gitignore

  comprehensive. Start from a template (github/gitignore) for your language/framework and add project-specific entries for build output, editor config, and local environment files.

Edge Cases

• Detached HEAD state: If the user has checked out a tag or specific commit, warn them before committing. Suggest creating a branch first to avoid orphaned commits.
• Large binary files: Git is not designed for large binaries. Recommend Git LFS for assets like images, models, or videos, and add the relevant LFS tracking rules.
• Shallow clones: Operations like

  blame

  ,

  log

  , and

  bisect

  may fail on shallow clones (

  --depth 1

  ). Run

  git fetch --unshallow

  before performing history-dependent operations.
• Submodules and monorepos: When the project uses submodules, ensure

  git submodule update --init --recursive

  is part of the setup instructions. For monorepos, respect per-package change boundaries during commits.
• Diverged branches after force-push: If a teammate force-pushed a shared branch, advise

  git fetch

  followed by

  git reset --hard origin/<branch>

  only after confirming no local work will be lost. Coordinate with the team first.