General Assembly logo

Version Control

Session Time: 120 minutes

Table of Contents

  1. Git Fundamentals: Initialization and Management
  2. Versioning Strategies for Collaboration
  3. AI-Assisted Documentation and Commits
  4. Lab: Collaborative Version Control
  5. Wrap-Up and Reflection

Learning Objectives

Upon completion of this session, participants will be able to:

  • Initialize and manage repositories using Git commands.
  • Develop clear versioning strategies for collaboration.
  • Employ AI to draft professional commit messages and documentation.

Session Breakdown

Segment Topic Duration (minutes)
Concept I Git Fundamentals & Repository Management 50
Concept II Collaboration Strategies & AI Documentation 20
Practical Lab Lab: Collaborative Version Control 50
Total 120 minutes

1. Git Fundamentals: Initialization and Management

Learning objective: Initialize and manage repositories using Git commands.

What is version control ?

Version control is essentially a "save point" system for your project files. It allows you to track changes over time, revert to previous versions if something breaks, and collaborate with others without overwriting each other's work.

Git is the most popular tool for doing this. Here are the core concepts and a basic workflow to get you started.

The Problem with "Final_v2_Real.zip"

Before Version Control Systems (VCS), developers managed changes by saving copies of folders (Project_v1, Project_v2). This was error-prone and made combining work from two people nearly impossible.

Git solves this by tracking "snapshots" of your code over time. It allows you to travel back to previous versions and merge work from different developers.

The Three States of Git

To manage a repository effectively, you must understand the three zones a file can reside in:

  1. Working Directory: The files you are currently editing on your computer.
  2. Staging Area: A preparatory zone where you list files to be included in the next snapshot.
  3. Repository (Local): The database where Git permanently stores the snapshots (commits).

Git Flow

The Basic Git Workflow

Here is the loop you will repeat constantly when using Git:

Step 1: Initialize Turn a regular folder into a Git repository.

git init

Step 2: Check Status See which files have been changed and what is currently staged.

git status

Step 3: Add (Stage) Move changes from your Working Directory to the Staging Area. You are telling Git, "I want to include this file in the next snapshot."

git add filename.txt
# OR to add all changed files:
git add .

Step 4: Commit Take the snapshot. This moves the changes from the Staging Area to the Local Repository. Always include a clear message explaining what you changed.

git commit -m "Fixed the navigation bar bug"

3. Branching and Merging

This is Git's superpower. A branch allows you to create a parallel version of your project. You can work on a new feature in a separate branch without affecting the main "stable" version of your code.

  • Main (or Master): The default branch, usually containing the production-ready code.
  • Feature Branch: A temporary branch where you work on a specific task.

Visualizing the Workflow

graph LR
    A[Working Directory] -- "git add" --> B[Staging Area]
    B -- "git commit" --> C[Local Repository]
    C -- "git push" --> D[Remote Repository like GitHub]
    
    style A fill:#ff9,stroke:#333
    style B fill:#9f9,stroke:#333
    style C fill:#99f,stroke:#333
    style D fill:#ccc,stroke:#333

Common Branch Commands:

  • git branch feature-login: Create a new branch called "feature-login".
  • git checkout feature-login: Switch to that branch to start working.
  • git merge feature-login: When you are done, switch back to main and run this to combine your feature into the main code.

4. Remote Repositories (GitHub/GitLab)

So far, everything has happened on your computer. To back up your code or collaborate, you use a Remote (like GitHub).

  • Push: Uploads your local commits to the remote server.
    git push origin main
  • Pull: Downloads new changes from the remote server to your computer (useful if a teammate added code).
    git pull origin main

Summary of Terms

  • Repository (Repo): The project folder tracked by Git.
  • Commit: A saved snapshot of the project at a specific point in time.
  • Clone: Downloading an existing repository from the internet to your machine.
  • Conflict: When Git can't automatically merge branches because two people changed the exact same line of code in different ways.

Core Commands

To initialize and manage a project, we use the command line (Terminal/Git Bash).

Command Description Analogy
git init Starts tracking the current folder. Buying a blank photo album.
git status Shows which files have changed. Checking which photos are on the table.
git add <file> Moves a file to the Staging Area. Putting a photo in the plastic sleeve (but not sealing it).
git commit -m "msg" Saves the Staging Area to the Repository. Sealing the page and writing a caption.
git log Shows the history of changes. Flipping through the pages of the album.

2. Versioning Strategies for Collaboration

Learning objective: Develop clear versioning strategies for collaboration.

When working in teams, simply saving changes isn't enough. You need a strategy to ensure your changes don't overwrite your teammate's work.

Branching

A branch allows you to diverge from the main line of development and continue to work without messing up the main code.

  • Main Branch (usually main or master): This is the "production-ready" code. It should always be working.
  • Feature Branch: A temporary branch created to build a specific feature (e.g., feature/login-page).

Semantic Versioning (SemVer)

Professional software often uses a numbering system called SemVer (Format: MAJOR.MINOR.PATCH) to communicate the impact of changes.

  • MAJOR (1.0.0): Incompatible API changes (Breaking changes).
  • MINOR (1.1.0): Added functionality in a backward-compatible manner.
  • PATCH (1.1.1): Backward-compatible bug fixes.
gitGraph
    commit id: "v1.0.0"
    branch feature/navbar
    checkout feature/navbar
    commit id: "Add Logo"
    commit id: "Style Links"
    checkout main
    merge feature/navbar tag: "v1.1.0"
    commit id: "Bug Fix" tag: "v1.1.1"

3. Employing AI for Documentation and Commits

Learning objective: Employ AI to draft professional commit messages and documentation.

One of the hardest parts of version control is maintaining clear documentation. Developers often write lazy commit messages like "fixed stuff," which is unhelpful for the team. AI can serve as a documentation assistant.

Here is an explanation of what a "Code Diff" looks like, followed by the Mermaid code to visualize the context in which a diff occurs.

The Code Diff Example

A git diff doesn't show the whole file; it only shows the lines that changed.

  • Red lines (-) are what existed before (and were removed).
  • Green lines (+) are what exist now (and were added).

Scenario: We are changing a website's title from "Welcome" to "Hello World".

Terminal Output:

diff --git a/index.html b/index.html
index 83c4.e92 100644
--- a/index.html
+++ b/index.html
@@ -5,7 +5,7 @@
 <body>
-    <h1>Welcome</h1>
+    <h1>Hello World</h1>
     <p>This is a paragraph.</p>
 </body>

The Change Diagram

The diagram below visualizes the two states (commits) that are being compared to generate the diff above.

gitGraph
   commit id: "Initial-Commit" tag: "v1.0.0"
   commit id: "Change-Title" tag: "v1.0.1"
   
   %% The 'diff' is the comparison between these two points

Key Takeaway

  • The Diagram shows when the change happened (the timeline).
  • The Diff shows what specifically changed inside the files between those two dots on the timeline.

Generating Commit Messages

You can paste your code changes (a "diff") into an AI tool to generate a standardized commit message.

Prompt Strategy:

"I have made the following changes to my HTML file: changed the heading of my page and added a paragraph. Please generate a concise git commit message following the 'Conventional Commits' standard (e.g., feat:, fix:, style:)."

AI Output Example:

fix(html): update heading scheme

Automating Changelogs

A Changelog is a file (usually CHANGELOG.md) that lists every notable change made to a project.

Workflow with AI:

  1. Provide the AI with a list of your recent tasks or raw code edits.
  2. Prompt: "Based on these tasks, write a Markdown entry for my Changelog under version 1.2.0. Group changes by 'Added', 'Changed', and 'Fixed'."

4. Lab: Collaborative Version Control

Learning objective: Simulate a professional development workflow by managing local project versions manually. Students will create multiple versions of an HTML/CSS project using clearly labeled folders, record changes in a changelog document, and use AI to generate concise commit-style summaries and documentation entries for each iteration.

Overview

Before using Git commands to automate the process, you will manually manage versions of a project to understand the underlying logic of snapshots and history. You will use AI to act as your "Commit Logger."

Part 1: Version 1.0 (The Foundation)

  1. Create a master folder named web-project-history.
  2. Inside it, create a folder named v1.0-initial.
  3. Create an index.html file inside v1.0-initial with a basic webpage structure (Header, Main, Footer).
  4. Documentation: Create a file in the master folder named manual-log.txt. Write a one-line summary of what v1.0 contains.

Part 2: Version 1.1 (The Feature Update)

  1. Copy the entire v1.0-initial folder and paste it. Rename the copy to v1.1-styling.
  2. Open the files in v1.1-styling.
  3. Add a style.css file and link it. Add a background color and font styles.
  4. AI Integration:
    • Open your AI assistant.
    • Describe your changes: "I added a CSS file, linked it to HTML, and added a blue background."
    • Prompt: "Turn this description into a professional Git commit message."
    • Action: Copy the AI-generated message into your manual-log.txt under "Version 1.1".

Part 3: Version 1.2 (The Bug Fix)

  1. Copy the v1.1-styling folder and paste it. Rename the copy to v1.2-bugfix.
  2. Simulate a bug fix: Change the footer text from "Copyright 2023" to "Copyright 2024".
  3. AI Integration:
    • Prompt: "I updated the copyright year in the footer. Generate a 'fix' type commit message."
    • Action: Log this in manual-log.txt.

Part 4: The Final Changelog

  1. You now have three folders representing three points in time.
  2. Copy the contents of your manual-log.txt.
  3. Prompt the AI: "Convert these three manual log entries into a professional CHANGELOG.md format using Semantic Versioning standards."
  4. Save the result as a new file CHANGELOG.md in your master folder.

Deliverable Structure

Your folder should look like this:

web-project-history/
├── v1.0-initial/
│   └── index.html
├── v1.1-styling/
│   ├── index.html
│   └── style.css
├── v1.2-bugfix/
│   ├── index.html
│   └── style.css
├── manual-log.txt
└── CHANGELOG.md

5. Wrap-Up and Reflection

Discussion Questions:

  1. In the lab, how much disk space would we waste if we had 100 versions of a project using the "Copy Folder" method? (This highlights why Git is efficient—it only saves changes, not duplicates).
  2. How did the AI change the tone of your commit messages? Were they clearer than what you would have written?
  3. Why is it important to separate a "Bug Fix" (Patch) from a "Feature Update" (Minor) in version numbering?

Resources