How to use Version Control

Learning outcomes:

• Explain what version control is and why it is important for both personal and professional projects
• Demonstrate a basic GitHub workflow including creating a repository, making commits, and managing branches
• Compare a personal GitHub workflow with an industry workflow and describe the key differences

Key Takeaways:

• Version control is not just a backup system; it's a record of how your work evolved and why decisions were made
• Write commit messages as if a teammate needs to understand what changed without reading the diff
• Always branch before making a significant change; never commit directly to main on a shared project
• A pull request starts a conversation about merging, not a demand; it's how teams give each other feedback on code
• Your GitHub profile is a professional portfolio; treat your commit history as something a future employer might read

Would you like to download my PowerPoint to follow along?

• What Is Version Control?
  • Version control is a system for tracking changes to files over time.
  • Think of it as a detailed history of a project.
  • Avoids issues such as: paper.docx paper_final.docx paper_final_v2.docx paper_FINAL_FINAL.docx
  • Github is a commonly used version control option
    • There are a lot of free options they offer
    • Pro Git, a free comprehensive book on Git and version control
• Why Use Version Control?
  • Benefits include:
    • Change history
    • Backup and recovery
    • Collaboration
    • Accountability
    • Experimentation without risk
  • With version control:
    • Every change is recorded
    • Previous versions can be restored
    • Teams can work simultaneously
    • Contributions are documented
  • Without version control:
    • Changes can be lost
    • Multiple copies become confusing
    • Collaboration becomes difficult
    • Mistakes are difficult to undo
• Key Terms and Common Vocabulary
  • Repository (Repo) — A project managed by version control.
  • Commit — A saved checkpoint in project history.
  • Branch — A separate workspace used for developing changes without affecting the main project.
  • Merge — Combining completed work back into the primary project.
  • Pull Request (PR) — A request to review and merge changes.
  • Fork — Make a copy of the project/code/repo/app.
  • Atlassian Git Tutorials: in-depth explanations of each of these concepts
• Example: Basic Workflow
  • The fundamental workflow is: Create → Edit → Commit → Push → Review
• Steps
  • Step 1: Create a Repository
    • Only needed at the start of the project
    • GitHub's official getting started documentation
    • When creating a public repository, consider choosing a license; choosealicense.com explains the options
  • Step 2: Make Changes
  • Step 3: Commit Changes
  • Step 4: Push Changes
  • Step 5: Review Progress
  • Go back to Step 2
  • Want guided practice? GitHub Skills offers interactive exercises for each step
• Common Mistakes
  • Waiting Too Long to Commit
    • Daily is better than weekly
  • Vague Commit Messages
    • Examples of what to avoid: "Changes!" "Did things!" "Updates!"
  • Committing Broken Work Without Explanation
    • Document changes and what needs to be done next
    • Even brief explanations such as "Commit before trying X" is better than nothing
  • Working Directly on Main in group projects
    • Working on main in personal projects is ok to avoid losing branches of work
  • Ignoring README Documentation
  • How to Write a Git Commit Message: concrete rules for writing useful commit messages
• Example 1: Individual Student Project
  • Scenario: A student is creating a personal website for a web development course
  • Repository created
    • Commit: Initial project setup
  • Follow general steps:
    • Step 1: Make Changes
    • Step 2: Commit Changes
    • Step 3: Push Changes
• Example 2: Industry Team Workflow
  • Scenario: A software development team is building a customer management application
  • Five developers are contributing simultaneously
  • Shared Repository — each developer has their own branch
    • Step 1: Create the branch before work is started
    • Step 2: Do the work and make commits (with good messages!)
    • Step 3: Push the branch (uploads changes to version control)
    • Step 4: Pull Request (requests review from other developers)
    • Step 5: Once approved, merge into main/master
• Example 3: Open Source Contribution Workflow
  • Scenario: A student wants to contribute to an open-source project
  • Unlike workplace projects, contributors usually do not have direct write access to the original repository
  • Open Source Guides: How to Contribute to Open Source
  • Step 1: Fork the Repository
  • Step 2: Create a Branch
  • Step 3: Make Changes
  • Step 4: Commit Changes (with good commit messages)
  • Step 5: Push commit to your fork
  • Step 6: Submit Pull Request (requests feedback on changes)
  • Step 7: Respond to Feedback if needed
  • Step 8: The maintainer of the project does the merge

Suggested Activities and Discussion Topics:

• Activity: Go through This AI generated study guide, what do you think? Did it capture the week materials well? How did you do on the self quiz? Do you know all the vocab used?
• Activity: Go through this AI-generated key terms list for this module. How many of the terms did you already know? Were there any definitions you would update or expand based on the lecture notes? Did the AI miss any important terms? This should take about 10–15 minutes.
• Activity: Create a free GitHub account if you don't already have one. Before signing up, take a look at GitHub's VPAT accessibility conformance report and note whether it meets the accessibility standards you would expect from a tool used in a professional environment. Then create a new public repository for a personal project or a class assignment. Make at least three commits with clear, descriptive commit messages; avoid messages like "update" or "fix" and instead describe what actually changed and why. When you are done, share the link to your repository and reflect on the following: Did writing commit messages make you think more carefully about your changes? Was anything harder than expected? This should take about 30–45 minutes.
• Activity: Working in pairs, one person creates a repository and adds the other as a collaborator. Each person makes changes to the same file on separate branches, then opens a pull request for their changes. Attempt to merge both pull requests and handle any merge conflicts that come up. Discuss afterward: What caused the conflict? How did you resolve it? What would have helped prevent it in the first place? This should take about 45–60 minutes.
• Discussion: Version control is standard practice in the tech industry, but the workflow and expectations can vary significantly between teams. Some use strict branch protection rules and code reviews, others are more informal. What do you think the minimum version control habits should be for any technical project, even a solo one? At what point does a project become too small to bother?
• Discussion: Commit messages, pull request descriptions, and branch names are all a form of documentation and communication with your future self and your teammates. Think about what makes a commit message useful versus useless. What information should it always include? Have you ever tried to trace back through a project and had no idea what past you was thinking? What would have helped?
• Activity: Read through these five sets of example commit messages, all describing the exact same set of code changes but written at different quality levels: Terrible, Poor, OK, Good, and Excellent. For each level, identify specifically what information is missing or present and why it matters. Then answer the following: Where would you draw your personal minimum standard, and why? Would that standard change depending on whether it was a solo project, a class assignment, or a professional team setting? Do you think the given labels are accurate for quality on the messages? This should take about 20–30 minutes.
• Activity: Choose an AI tool of your choice such as ChatGPT, Gemini, or Claude. Ask it to explain what a merge conflict is in Git and walk you through how to resolve one. Do some research not using an AI, Is the explanation accurate? Is it clear enough that someone brand new to version control could follow it? Did it leave anything out or get anything wrong? Would you recommend this explanation to a classmate who was confused about merge conflicts? This should take about 5–10 minutes.
• Activity: Find an active open source project on GitHub in a domain you find interesting. Spend 15–20 minutes exploring it: Look at the commit history and evaluate whether the commit messages are descriptive or vague. Look at open and closed pull requests to see what was proposed and how feedback was given. Look at any open issues to understand what the community is currently working on. Write a short summary of what you found: What does this project's version control history tell you about how the team works and communicates? This should take about 20–30 minutes.
• Activity: Practice a complete fork-and-pull-request workflow. Find a public repository that accepts contributions; many have issues labeled "good first issue" on GitHub. Fork the repository, create a branch, make a small change such as fixing a typo, improving documentation, or adding a missing step to a README, and open a pull request. If submitting a real PR feels high-stakes, do this with a classmate's repository instead. Reflect: What was harder than expected? What did the process teach you about how open source collaboration works? This should take about 30–45 minutes.
• Activity: Write commit messages for a set of hypothetical changes. Imagine you are working on a personal portfolio website and have made the following changes: added a new projects section to the homepage, fixed a broken navigation link, updated the color scheme in CSS, and added setup instructions to the README. Write a commit message for each change: first a vague version, then rewrite it as a strong, descriptive one. Compare your pairs: What information does the better version include that the vague one does not? How long did it take to write the improved versions? This should take about 20–30 minutes.
• Activity: Set up a version-controlled project of your own from scratch. This does not have to be code; it could be your resume, a writing project, or notes for a class. Create a new repository on GitHub, make at least five commits over the course of a week with descriptive messages, and push them to the remote. At the end of the week, review your commit history: Does it tell the story of what you worked on? Would someone reading it understand what changed and why? What would you do differently on your next version-controlled project? This should take about 15–20 minutes to set up; allow one week to complete.

Related modules you might find useful:

• How to Collaborate as a Team
• How to do Documentation
• How to Get a Tech Job

Would you like to see some more How tos? See more How tos