Git Introduction Skill

Production-Grade Learning Skill | Version 2.0.0

Your first steps into the world of version control.

Skill Contract

Input Schema

input:
  type: object
  properties:
    topic:
      type: string
      enum: [what-is-git, why-use-git, installation, first-setup, first-repo]
      default: what-is-git
    os:
      type: string
      enum: [macos, windows, linux, unknown]
      default: unknown
    experience_level:
      type: string
      enum: [complete-beginner, some-coding, used-other-vcs]
      default: complete-beginner
  validation:
    custom: true
    rules:
      - if_unknown_os: detect_from_environment

Output Schema

output:
  type: object
  required: [explanation, success]
  properties:
    explanation:
      type: string
      format: markdown
    success:
      type: boolean
    visual_aid:
      type: string
      description: ASCII diagram if applicable
    next_steps:
      type: array
      items:
        type: string
    commands_to_try:
      type: array
      items:
        type: object
        properties:
          command: string
          description: string
          safe: boolean

Error Handling

Validation Rules

parameter_validation:
  topic:
    required: false
    sanitize: lowercase_trim
    fallback: what-is-git
  os:
    required: false
    auto_detect: true
    detection_command: uname -s || ver

Retry Logic

retry_config:
  max_attempts: 2
  backoff_ms: [1000, 2000]
  retryable_scenarios:
    - command_timeout
    - os_detection_failed

Fallback Strategy

fallback:
  - scenario: installation_failed
    action: provide_manual_instructions
  - scenario: command_not_found
    action: check_path_and_suggest

---

What is Git?

    Without Git                    With Git
    ──────────                     ─────────

    report_v1.doc                  report.doc
    report_v2.doc                     │
    report_final.doc                  ├─ commit 1: "Initial draft"
    report_final_v2.doc               ├─ commit 2: "Added intro"
    report_REALLY_final.doc           ├─ commit 3: "Fixed typos"
    report_final_final.doc            └─ commit 4: "Final version"

    Chaos!                         Clean history!

Why Use Git?

Problem	Git Solution
"Which version is latest?"	Single file, full history
"I broke everything!"	Time travel to any point
"Who changed this?"	Blame/log shows author
"Can't work together"	Branches, merge, resolve
"Lost my work!"	Every commit is backup

Key Concepts

The Three Areas

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Working Directory    Staging Area      Repository         │
│   (Your Workspace)     (Ready Room)      (Safe Storage)     │
│                                                             │
│       📁 ──────────► 📦 ──────────────► 🏠               │
│              git add        git commit                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Commits = Save Points

commit 3 ← (HEAD - You are here)
    ↓
commit 2 ← You can go back
    ↓
commit 1 ← Or even further back!

Installation

macOS

# Option 1: Xcode Command Line Tools (recommended)
xcode-select --install

# Option 2: Homebrew
brew install git

Windows

# Option 1: Git for Windows (recommended)
# Download from https://git-scm.com/download/windows

# Option 2: winget
winget install --id Git.Git -e --source winget

Linux

# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

# Arch
sudo pacman -S git

Verify Installation

git --version
# Expected: git version 2.42.0 (or similar)

First-Time Setup

# Tell Git who you are (REQUIRED)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Optional but recommended
git config --global init.defaultBranch main
git config --global core.editor "code --wait"  # VS Code

# Verify your settings
git config --list

Your First Repository

# 1. Create a folder
mkdir my-first-project
cd my-first-project

# 2. Initialize Git (creates .git folder)
git init
# Output: Initialized empty Git repository in .../my-first-project/.git/

# 3. Create a file
echo "# My Project" > README.md

# 4. Check status
git status
# Output: Untracked files: README.md

# 5. Stage the file
git add README.md

# 6. Commit (save!)
git commit -m "Initial commit: Add README"

# 7. View history
git log --oneline

Quick Reference Card

┌────────────────────────────────────────────────────────────┐
│                    GIT CHEAT SHEET                         │
├────────────────────────────────────────────────────────────┤
│ START                                                      │
│   git init              Create new repo                    │
│   git clone <url>       Download existing repo             │
│                                                            │
│ DAILY WORK                                                 │
│   git status            What's going on?                   │
│   git add <file>        Stage file                         │
│   git add .             Stage all                          │
│   git commit -m "msg"   Save with message                  │
│                                                            │
│ HISTORY                                                    │
│   git log               View commits                       │
│   git log --oneline     Compact view                       │
│   git diff              See changes                        │
└────────────────────────────────────────────────────────────┘

---

Troubleshooting Guide

Debug Checklist

□ 1. Is Git installed? → git --version
□ 2. Correct version? → Should be 2.x or higher
□ 3. User configured? → git config user.name
□ 4. Editor set? → git config core.editor

Common Issues

Issue	Cause	Solution
"command not found: git"	Not installed or not in PATH	Reinstall or add to PATH
"Author identity unknown"	User not configured	Run git config commands
"not a git repository"	Missing .git folder	Run git init

Log Patterns

# Successful init
Initialized empty Git repository in /path/.git/

# Successful commit
[main abc1234] Your message
 1 file changed, 1 insertion(+)

---

Unit Test Template

#!/bin/bash
# test_git_intro.sh

test_git_installed() {
  git --version > /dev/null 2>&1
  assertEquals 0 $?
}

test_user_configured() {
  name=$(git config user.name)
  assertNotNull "$name"
}

test_init_creates_git_folder() {
  tmpdir=$(mktemp -d)
  cd "$tmpdir"
  git init
  assertTrue "[ -d .git ]"
  rm -rf "$tmpdir"
}

---

Observability

logging:
  level: INFO
  events:
    - skill_invoked
    - installation_checked
    - config_verified
    - first_commit_created

metrics:
  - installation_success_rate
  - time_to_first_commit
  - common_error_types

---

Next Steps

After mastering this skill, proceed to:

1. basic-workflow - Daily Git operations
2. git-basics - Deeper understanding
3. branching - Work in parallel

---

"Every expert was once a beginner. Welcome to Git!"