git-basics

name	git-basics
description	Git fundamentals - init, add, commit, status, log, and core concepts
sasmp_version	1.3.0
bonded_agent	git-mentor
bond_type	PRIMARY_BOND
category	learning
version	2.0.0
triggers	["git basics","git init","git commands"]

Git Basics Skill

Production-Grade Learning Skill | Version 2.0.0

Essential Git operations for version control mastery.

Skill Contract

Input Schema

input:
  type: object
  properties:
    command_focus:
      type: string
      enum: [init, add, commit, status, log, diff, config, all]
      default: all
    detail_level:
      type: string
      enum: [quick, standard, deep]
      default: standard
    include_examples:
      type: boolean
      default: true
  validation:
    sanitize_strings: true

Output Schema

output:
  type: object
  required: [content, success]
  properties:
    content:
      type: string
      format: markdown
    success:
      type: boolean
    commands_covered:
      type: array
      items:
        type: object
        properties:
          name: string
          syntax: string
          examples: array
          common_flags: array
    diagrams:
      type: array
      items:
        type: string

Error Handling

Retry Logic

retry_config:
  max_attempts: 2
  backoff_ms: [1000, 2000]
  retryable:
    - timeout
    - network_error

Parameter Validation

validation_rules:
  command_focus:
    type: enum
    fallback: all
  detail_level:
    type: enum
    fallback: standard

---

Core Commands Reference

Repository Initialization

# Create new repository
git init

# What it creates:
.git/
├── HEAD              # Current branch pointer
├── config            # Repository config
├── hooks/            # Git hooks
├── objects/          # Git object store
└── refs/             # Branch/tag references

File Tracking

# Check repository status
git status

# Short status format
git status -s
# M  modified
# A  added
# ?? untracked
# D  deleted

# Add files to staging
git add file.txt           # Single file
git add .                  # All files
git add *.js               # Pattern
git add -p                 # Interactive (patch mode)

Committing Changes

# Commit with message
git commit -m "Add feature"

# Commit with detailed message (opens editor)
git commit

# Amend last commit
git commit --amend

# Skip staging (tracked files only)
git commit -am "Quick fix"

Viewing History

# Full log
git log

# One line per commit
git log --oneline

# With graph visualization
git log --oneline --graph --all

# Last N commits
git log -5

# File history
git log --follow -- file.txt

# Search commits
git log --grep="bug"
git log --author="Name"
git log --since="2 weeks ago"

Viewing Changes

# Working directory changes
git diff

# Staged changes
git diff --staged

# Between commits
git diff abc123 def456

# Specific file
git diff HEAD~3 -- file.txt

# Statistics only
git diff --stat

Command Quick Reference

Command	Purpose	Common Flags	Example
git init	Create repo	-	git init
git clone	Copy repo	--depth, --branch	git clone URL
git status	Check state	-s, -b	git status -s
git add	Stage files	-p, -A	git add .
git commit	Save changes	-m, --amend	git commit -m "msg"
git log	View history	--oneline, --graph	git log --oneline
git diff	See changes	--staged, --stat	git diff --staged
git show	Show commit	-	git show abc123

Understanding Git Objects

┌─────────────────────────────────────────────────────────┐
│                    GIT OBJECTS                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   BLOB     ─ File content (compressed)                  │
│   TREE     ─ Directory listing (blob + tree refs)       │
│   COMMIT   ─ Snapshot + metadata + parent link          │
│   TAG      ─ Named pointer to commit                    │
│                                                         │
│   commit ─┬─► tree ─┬─► blob (file1.txt)               │
│           │         ├─► blob (file2.txt)               │
│           │         └─► tree (subdir/) ─► blob         │
│           │                                             │
│           └─► parent commit                             │
│                                                         │
└─────────────────────────────────────────────────────────┘

Configuration

Essential Setup

# Identity (required)
git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

# Editor
git config --global core.editor "code --wait"

# Default branch
git config --global init.defaultBranch main

# View all settings
git config --list
git config --global --list

Useful Aliases

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph"

File States

┌─────────────────────────────────────────────────────────┐
│                    FILE LIFECYCLE                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   Untracked ──────────────────────────────────────►     │
│       │                                                 │
│       │ git add                                         │
│       ▼                                                 │
│   Staged ─────────────────────────────────────────►     │
│       │                                                 │
│       │ git commit                                      │
│       ▼                                                 │
│   Committed/Unmodified ───────────────────────────►     │
│       │                                                 │
│       │ edit file                                       │
│       ▼                                                 │
│   Modified ──────► git add ──► Staged ──► Committed     │
│                                                         │
└─────────────────────────────────────────────────────────┘

.gitignore Patterns

# Ignore specific file
secret.txt

# Ignore by extension
*.log
*.tmp

# Ignore directory
node_modules/
.cache/

# Negation (don't ignore)
!important.log

# Pattern matching
**/build/       # Any directory named build
doc/**/*.pdf    # PDFs in doc subdirectories

---

Troubleshooting Guide

Debug Checklist

□ 1. Inside repo? → git rev-parse --git-dir
□ 2. Clean state? → git status
□ 3. On right branch? → git branch
□ 4. Files tracked? → git ls-files

Common Issues

Error	Cause	Solution
"nothing to commit"	No changes staged	Check git status, use git add
"untracked files"	New files not added	git add
"Changes not staged"	Modified but not added	git add
"detached HEAD"	Checked out commit	git checkout main

Log Patterns

# Normal add output
# (no output = success)

# Normal commit output
[main abc1234] Your message
 2 files changed, 10 insertions(+), 3 deletions(-)

---

Unit Test Template

#!/bin/bash
# test_git_basics.sh

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

test_add_stages_file() {
  tmpdir=$(mktemp -d)
  cd "$tmpdir"
  git init
  echo "test" > file.txt
  git add file.txt
  staged=$(git diff --cached --name-only)
  assertEquals "file.txt" "$staged"
  rm -rf "$tmpdir"
}

test_commit_creates_history() {
  tmpdir=$(mktemp -d)
  cd "$tmpdir"
  git init
  git config user.email "[e-mail]"
  git config user.name "Test"
  echo "test" > file.txt
  git add file.txt
  git commit -m "test"
  count=$(git log --oneline | wc -l)
  assertEquals 1 "$count"
  rm -rf "$tmpdir"
}

---

Observability

logging:
  level: INFO
  events:
    - command_executed
    - file_staged
    - commit_created
    - error_occurred

metrics:
  - commands_per_session
  - staging_patterns
  - commit_frequency
  - error_types

---

Best Practices

1. Commit Often: Small, focused commits
2. Write Clear Messages: What and why
3. Review Before Commit: git diff --staged
4. Use .gitignore: Keep repo clean
5. Don't Commit Secrets: Never!

---

"Git basics are the foundation of all version control."