Git Version Control Basics

Git Version Control Basics

Git is the most popular distributed version control system. In IoT development, it is used to manage firmware code, hardware design files, and project documentation. This section systematically introduces Git’s core concepts and basic operations, helping readers quickly get started with version control.

Git Core Concepts

Git’s three working areas:

Working Directory → Staging Area → Local Repository
     git add           git commit

• Working Directory: the files you are currently editing
• Staging Area: a collection of changes ready to be committed
• Local Repository: where Git stores all historical versions

Git Basic Workflow

Init & Clone

# Initialize a new local repository
git init

# Clone an existing remote repository
git clone https://github.com/your-org/iot-project.git

Daily Development Trilogy: Add → Commit → Push

# 1. Check current status
git status

# 2. Stage changes
git add main.c                    # Add a single file
git add src/                       # Add an entire directory
git add -p                         # Interactive staging (recommended)

# 3. Commit to local repository
git commit -m "feat: add MQTT reconnection mechanism"

# 4. Push to remote repository
git push origin main

Commit Message Convention: Use Conventional Commits format

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Testing
• chore: Build/tooling changes

Viewing History & Diffs

# View commit history
git log
git log --oneline                  # Compact mode
git log --graph                    # Graphical branch view

# View unstaged changes
git diff

# View staged changes
git diff --cached

Pulling Remote Updates

# Pull latest remote code and merge
git pull origin main

# Fetch without merging (review first)
git fetch origin
git log origin/main..HEAD          # See what's ahead locally
git merge origin/main              # Merge after review

Branch Management

Branches allow teams to develop in parallel.

Basic Branch Operations

# List all branches (* marks current)
git branch

# Create a new branch
git branch feature/temperature-sensor

# Switch branches
git checkout feature/temperature-sensor

# Create and switch (one step)
git checkout -b feature/humidity-sensor

# Delete branch (after merge)
git branch -d feature/temperature-sensor

Common Branch Strategy

Simplified Git Flow:

main ────────●────────────●────────
              \          /
feature/xyz    ●──●──●──●
                  \
fix/abc           ●──●

• main: Stable release-ready branch
• feature/*: Feature branches, merged via PR
• fix/*: Bug fix branches

Merging & Conflict Resolution

# Merge feature into current branch
git merge feature/temperature-sensor

# Rebase (linear history, suitable for personal branches)
git checkout feature/temperature-sensor
git rebase main

When two branches modify the same file region, Git reports a conflict:

# Conflict markers example
<<<<<<< HEAD
Serial.println("Temperature: 25.5°C");
=======
Serial.println("Temperature: 26.3°C");
>>>>>>> feature/calibration

# Resolve: edit file, keep correct version, remove markers
Serial.println("Temperature: 26.3°C");  # Use calibrated value

# Mark as resolved and commit
git add sensor.cpp
git commit -m "fix: resolve temperature calibration conflict"

Remote Repository Collaboration

Adding a Remote

git remote add origin https://github.com/your-org/iot-project.git
git remote -v

Pull Request Workflow

# Push local branch to remote
git push origin feature/temperature-sensor

# On GitHub/GitLab, create a PR including:
# - Summary of changes
# - Related Issue number
# - Testing methodology
# - Scope of impact

.gitignore Configuration

For IoT projects, exclude these files:

# Build artifacts
build/
cmake-build-*/
*.o
*.elf
*.bin
*.hex

# IDE config
.vscode/
.idea/
*.swp
*.swo

# Environment (do not commit secrets)
.env
*.env.local

# System files
.DS_Store
Thumbs.db

# Python cache
__pycache__/
*.pyc

Commit the .gitignore:

git add .gitignore
git commit -m "chore: add .gitignore"

Undoing Changes

# Discard working directory changes (use with caution)
git checkout -- main.c

# Unstage a file
git reset HEAD main.c

# Amend last commit message
git commit --amend -m "new message"

# Hard reset to a commit (discard history)
git reset --hard <commit-hash>

# Soft reset (keep changes in working directory)
git reset --soft <commit-hash>

Quick Command Reference

Command	Purpose	Common Flags
git init	Initialize a repo	—
git clone <url>	Clone a remote repo	--recursive
git status	Check workspace status	-s (short)
git add <file>	Stage changes	. (all), -p (interactive)
git commit	Commit staged changes	-m (message), --amend
git push	Push to remote	origin main, --force (risky)
git pull	Pull and merge	--rebase
git branch	Manage branches	-d (delete), -a (all)
git checkout	Switch branch/file	-b (create + switch)
git merge <b>	Merge a branch	—
git log	View history	--oneline, --graph
git diff	View differences	--cached (staged diff)

---

Next: After mastering Git basics, the next section covers how to initialize a project repository on GitHub and configure the team collaboration environment.

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →