git-fundamentals - SKILL.md Agent Skill

name: git-fundamentals description: Essential Git version control knowledge including repositories, commits, branches, remotes, and common workflows. Use when helping with basic Git operations, teaching Git concepts, or as foundation for advanced Git tools. Activate for questions about Git basics, standard workflows, or version control fundamentals. version: 1.0.0

Git Fundamentals Skill

When to Use This Skill

Use this skill when:

User asks about basic Git operations or concepts
Need to explain Git fundamentals
User is learning version control
Troubleshooting common Git issues
Providing foundation before using advanced tools (like GitButler)

Do NOT use for:

Advanced Git operations (rebase, cherry-pick, subtrees)
Git hosting platforms (GitHub, GitLab, Bitbucket)
Git GUIs or alternative tools (use specific skills for those)

Core Concepts

Repository

A Git repository is a directory that tracks changes to files over time.

Key points:

Contains .git/ directory with version history
Can be local (on your machine) or remote (on a server)
Initialized with git init or cloned with git clone

Commits

Snapshots of your project at specific points in time.

Characteristics:

Identified by unique SHA hash (e.g., abc123)
Contains author, timestamp, message, and changes
Forms a history chain (each commit points to parent)
Immutable once created

Branches

Independent lines of development in a repository.

Key points:

Default branch: usually main or master
Branches are lightweight (just pointers to commits)
Allow parallel development
Can be merged or deleted

Working Directory, Staging Area, Repository

Working Directory  →  Staging Area  →  Repository
  (modified files)     (git add)       (git commit)

Working Directory: Your actual files
Staging Area (Index): Prepared changes for next commit
Repository: Committed history

Remote

A version of your repository hosted elsewhere (e.g., GitHub, GitLab).

Common operations:

git clone: Copy remote repository locally
git push: Send commits to remote
git pull: Fetch and merge remote changes
git fetch: Get remote changes without merging

Common Workflows

1. Starting a New Project

# Initialize new repository
git init

# Or clone existing repository
git clone https://github.com/username/repo.git
cd repo

2. Daily Development Workflow

# 1. Check status
git status

# 2. Make changes (edit files in your editor)

# 3. Stage changes
git add file1.txt file2.txt
# Or stage all changes
git add .

# 4. Commit changes
git commit -m "Add feature X"

# 5. Push to remote
git push origin main

3. Viewing History

# View commit history
git log

# Compact history
git log --oneline

# Graphical history
git log --graph --all --decorate

# Show specific commit
git show abc123

4. Branch Management

# List branches
git branch

# Create new branch
git branch feature-name

# Switch to branch
git checkout feature-name
# Or with newer syntax
git switch feature-name

# Create and switch in one command
git checkout -b feature-name
# Or
git switch -c feature-name

# Delete branch
git branch -d feature-name

5. Merging Changes

# Switch to target branch
git checkout main

# Merge feature branch
git merge feature-branch

# If conflicts occur:
# 1. Edit files to resolve conflicts
# 2. Stage resolved files
git add resolved-file.txt
# 3. Complete merge
git commit

6. Working with Remotes

# View remotes
git remote -v

# Add remote
git remote add origin https://github.com/username/repo.git

# Fetch changes
git fetch origin

# Pull changes (fetch + merge)
git pull origin main

# Push changes
git push origin main

# Push new branch
git push -u origin feature-branch

7. Undoing Changes

# Discard changes in working directory
git restore file.txt
# Or (older syntax)
git checkout -- file.txt

# Unstage file (keep changes)
git restore --staged file.txt
# Or (older syntax)
git reset HEAD file.txt

# Amend last commit (not pushed yet)
git commit --amend

# Revert commit (create new commit that undoes)
git revert abc123

Commit Message Best Practices

Format

<type>: <subject>

<body>

<footer>

Subject Line

Use imperative mood: "Add feature" not "Added feature"
Keep under 50 characters
Don't end with period
Capitalize first letter

Good examples:

Add user authentication
Fix memory leak in parser
Update dependencies to latest versions

Bad examples:

fixed bug (not imperative, not descriptive)
Added a new feature that allows users to authenticate using OAuth (too long)
stuff (not descriptive)

Body (optional)

Wrap at 72 characters
Explain what and why, not how
Separate from subject with blank line

Types

feat: New feature
fix: Bug fix
docs: Documentation only
style: Formatting, missing semi-colons, etc.
refactor: Code restructuring
test: Adding tests
chore: Maintenance tasks

Common Scenarios

Scenario 1: Starting a Feature

# 1. Ensure you're on main and up to date
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature-user-auth

# 3. Make changes and commit
# ... edit files ...
git add .
git commit -m "Add user login form"

# 4. Continue development
# ... more edits ...
git commit -m "Add authentication logic"

# 5. Push feature branch
git push -u origin feature-user-auth

Scenario 2: Reviewing Changes Before Commit

# See what changed
git status

# See detailed changes
git diff

# See changes for specific file
git diff path/to/file.txt

# See staged changes
git diff --staged

Scenario 3: Fixing Mistakes

Made changes but want to start over:

# Discard all working directory changes
git restore .

Committed to wrong branch:

# On wrong branch
git log  # Note the commit SHA

# Switch to correct branch
git checkout correct-branch

# Cherry-pick the commit
git cherry-pick abc123

# Go back and remove from wrong branch
git checkout wrong-branch
git reset --hard HEAD~1

Scenario 4: Collaborating

# Update your main branch
git checkout main
git pull origin main

# Update your feature branch with main's changes
git checkout feature-branch
git merge main

# Resolve any conflicts, then push
git push origin feature-branch

Important Commands Reference

Information Commands

git status              # Check working directory status
git log                 # View commit history
git log --oneline       # Compact history
git diff                # View changes
git show <commit>       # Show specific commit
git branch              # List branches
git remote -v           # List remotes

Making Changes

git add <file>          # Stage file
git add .               # Stage all changes
git commit -m "msg"     # Commit staged changes
git commit -am "msg"    # Stage all tracked files and commit

Branching

git branch <name>       # Create branch
git checkout <name>     # Switch branch
git switch <name>       # Switch branch (newer)
git checkout -b <name>  # Create and switch
git branch -d <name>    # Delete branch
git merge <branch>      # Merge branch into current

Remote Operations

git clone <url>         # Clone repository
git fetch               # Fetch remote changes
git pull                # Fetch and merge
git push                # Push commits
git push -u origin <br> # Push new branch

Undoing

git restore <file>      # Discard working directory changes
git restore --staged    # Unstage file
git commit --amend      # Modify last commit
git revert <commit>     # Create commit that undoes changes

Configuration

Initial Setup

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default editor
git config --global core.editor "vim"

# Set default branch name
git config --global init.defaultBranch main

# View configuration
git config --list

Useful Aliases

# Create shortcuts
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'restore --staged'
git config --global alias.last 'log -1 HEAD'
git config --global alias.lg 'log --oneline --graph --all'

# Now you can use:
git co main    # instead of git checkout main
git st         # instead of git status

Git Ignore

Create .gitignore file to exclude files from version control:

# Dependencies
node_modules/
vendor/

# Environment files
.env
.env.local

# Build outputs
dist/
build/
*.pyc

# IDE files
.vscode/
.idea/
*.swp

# OS files
.DS_Store
Thumbs.db

Common Issues and Solutions

"Your branch is ahead of origin/main by X commits"

Solution: Push your commits

git push origin main

"Your branch is behind origin/main"

Solution: Pull remote changes

git pull origin main

"Merge conflict"

Solution:

Open conflicted files
Look for conflict markers: <<<<<<<, =======, >>>>>>>
Edit to resolve conflicts
Remove conflict markers
Stage resolved files: git add <file>
Complete merge: git commit

"Fatal: not a git repository"

Solution: You're not in a Git repository

# Either initialize one
git init

# Or clone existing repository
git clone <url>

"Permission denied (publickey)"

Solution: SSH keys not set up

# Check if you have SSH keys
ls ~/.ssh

# If not, generate them
ssh-keygen -t ed25519 -C "your.email@example.com"

# Add to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Add public key to GitHub/GitLab/etc
cat ~/.ssh/id_ed25519.pub

Best Practices

Commit often: Small, focused commits are better than large ones
Write good commit messages: Help future you understand changes
Use branches: Keep main stable, develop features in branches
Pull before push: Stay synced with remote
Review before commit: Use git diff and git status
Don't commit sensitive data: Use .gitignore for secrets
Keep commits atomic: One logical change per commit
Test before commit: Ensure code works
Use meaningful branch names: feature/user-auth not stuff
Clean up branches: Delete merged branches

Further Learning

Next Steps

Advanced branching strategies (Git Flow, GitHub Flow)
Interactive rebase for cleaning history
Git hooks for automation
Submodules and subtrees
Advanced tools like GitButler for managing complexity

Related Skills

gitbutler-cli: Advanced Git workflows with virtual branches
github-workflow: GitHub-specific features and workflows
git-hooks: Automating tasks with Git hooks

Quick Reference Card

# Start
git init / git clone <url>

# Daily workflow
git status
git add <files>
git commit -m "message"
git push

# Branching
git branch <name>
git checkout <name>
git merge <branch>

# Sync
git pull
git fetch

# Undo
git restore <file>
git restore --staged <file>
git commit --amend

# History
git log
git show <commit>
git diff

Tips

Use git status constantly - it's your friend
Commit early and often
Branch for every feature or fix
Keep commits focused on one thing
Write commits as if explaining to future teammates
Pull before starting new work
Don't panic - most things are recoverable