Version Control with Git and Team Workflows

Version control helps you track changes to your code over time, work safely in a team, and recover when something goes wrong. Git is the most widely used version control system, and most teams use it together with a hosting platform like GitHub, GitLab, or Bitbucket.

This topic focuses on practical Git usage in a team: repositories, branching, pull requests, code reviews, merge conflicts, and writing good commit messages.

---

1) Repositories: Local vs Remote

A repository (repo) is the place where Git stores the history of your project.

• Local repository: on your computer
• Remote repository: hosted online (e.g. GitHub) so the team can collaborate

Common commands:

# Create a new repo in the current folder
git init

# Link your local repo to a remote repo
git remote add origin https://github.com/your-org/your-repo.git

# Download a remote repo to your machine
git clone https://github.com/your-org/your-repo.git

Key idea: pull vs push

• Pull brings changes from the remote repo to your local machine.
• Push sends your local changes to the remote repo.

git pull
git push

---

2) The Basic Git Workflow (Day-to-day)

A typical workflow looks like this:

1. Get the latest code
2. Create a branch for your work
3. Make changes
4. Stage changes
5. Commit changes
6. Push branch
7. Open a pull request (PR)
8. Review, fix feedback, and merge

Key commands:

git status          # see what changed
git add .           # stage changes
git commit -m "..." # commit staged changes
git push -u origin my-branch

Useful habit: check what you are about to commit

git diff            # unstaged changes
git diff --staged   # staged changes

---

3) Branching: Working Without Breaking Main

A branch is an independent line of work. Branching allows multiple people to work at the same time without interfering with each other.

Most teams protect the main branch:

• main (or master) should always be deployable
• new work happens on feature branches

Create and switch to a new branch:

git checkout -b feature/login-form

List branches:

git branch

Switch branches:

git checkout main

Branch naming conventions (team-friendly)

Use consistent names so everyone understands what a branch is for:

• feature/... (new functionality): feature/product-search
• fix/... (bug fixes): fix/header-overlap
• chore/... (maintenance): chore/update-deps
• docs/... (documentation): docs/readme-setup

Keep branch names:

• short, meaningful, lower-case, hyphenated

---

4) Keeping Your Branch Up to Date

If your branch gets behind main, you can bring in changes before you open a PR. This reduces conflicts later.

Option A: Merge main into your branch (simple and common)

git checkout main
git pull
git checkout feature/login-form
git merge main

Option B: Rebase your branch on top of main (cleaner history, more advanced)

Rebase rewrites commit history. Teams often use it before pushing, or only on personal branches.

git checkout main
git pull
git checkout feature/login-form
git rebase main

Team rule of thumb:

• Merge is safer for beginners and shared branches
• Rebase can be great, but avoid rebasing commits that others already pulled

---

5) Pull Requests (PRs): How Teams Merge Code Safely

A pull request is a request to merge your branch into main. It creates a place for discussion, review, and automated checks (tests, linting, build).

A good PR should:

• focus on one feature/fix (small and reviewable)
• include a clear description
• link to the ticket/user story (if your team uses one)
• include screenshots for UI changes
• include test notes (how to test it)

Example PR description structure

• What: Implement login form validation
• Why: Prevent invalid submissions and improve UX
• How to test:
  1. Open /login
  2. Submit empty form → errors show
  3. Enter valid email and password → submit succeeds

Draft PRs

Use a Draft PR when work is not ready to merge but you want early feedback.

---

6) Code Reviews: What to Look For

Code reviews help you catch issues before they reach production and help the team learn consistent patterns.

When reviewing, focus on:

Correctness

• Does it solve the user story?
• Are edge cases handled?
• Are there obvious bugs?

Readability

• Clear naming (variables, functions, components)
• Code is easy to follow
• Comments only where needed (explain “why”, not “what”)

Maintainability

• Reusable functions/components
• Minimal duplication
• Fits project structure and conventions

Quality and safety

• Tests added/updated where appropriate
• No secrets committed (API keys, passwords)
• Input validation and safe API usage

Performance and accessibility

• Avoid unnecessary re-renders/heavy loops (front end)
• Images and assets handled responsibly
• Basic accessibility checks (labels, keyboard access)

Review etiquette (team culture)

• Be respectful and specific
• Prefer suggestions: “Consider…” / “What do you think about…”
• Explain reasoning, not just opinion
• Accept feedback professionally; it’s about the code, not the person

---

7) Resolving Merge Conflicts (Without Panic)

A merge conflict happens when Git cannot automatically combine changes, usually because two people edited the same lines in the same file.

You may see something like this in a file:

<<<<<<< HEAD
button { background: blue; }
=======
button { background: green; }
>>>>>>> feature/new-theme

This means:

• HEAD is your current branch’s version
• the other section is the incoming change

Steps to resolve a conflict

1. Read both sides and decide what the final code should be
2. Edit the file to the correct final version (remove the conflict markers)
3. Mark as resolved by staging the file:

   git add styles.css
   

4. Finish the merge:

   git commit
   

Helpful commands during conflicts

git status     # see which files are conflicted
git merge --abort   # stop the merge and return to previous state (if needed)

Tips to avoid conflicts

• Pull from main regularly
• Keep PRs small and short-lived
• Communicate when multiple people must edit the same area
• Use agreed patterns (e.g. consistent formatting via Prettier)

---

8) Writing Meaningful Commit Messages

A commit is a snapshot of staged changes with a message that explains what changed and why. Good commit messages make project history useful.

What makes a commit message “good”?

• describes the intent (not only the file changes)
• small scope (one logical change per commit)
• uses consistent style across the team

Recommended format

Short summary (imperative) + optional body.

Examples:

• Add responsive navigation menu
• Fix null check in user profile loader
• Update README setup instructions

If needed, add more detail:

Fix password reset token validation

- Reject expired tokens
- Add server-side logging for invalid attempts

Conventional Commits (common in many teams)

Some teams use a standard prefix:

• feat: add password strength indicator
• fix: handle empty search results
• docs: update API usage examples
• chore: bump dependencies
• test: add unit tests for cart totals

This can help automate:

• changelogs
• versioning
• release notes

Commit message anti-patterns (avoid)

• Update
• Fix stuff
• Changes
• WIP (unless your team explicitly allows it for temporary commits on local branches)

---

9) A Simple Team Workflow (Recommended for This Course)

A practical workflow you can use for group projects:

1. Protect main (no direct pushes)
2. Create a branch per task: feature/... or fix/...
3. Commit regularly with meaningful messages
4. Push your branch and open a PR
5. PR requires at least one review
6. CI checks (lint/tests/build) must pass before merge
7. Use Squash merge or Merge commit depending on your team preference

Squash merge is often easiest for learners because it turns many small commits into one clean commit on main.

---

10) Common Problems and Quick Fixes

“I committed to the wrong branch”

• Create a new branch from your current state, then reset the wrong branch (best done carefully).

A safe approach (if not pushed):

git checkout -b feature/correct-branch
# then switch back and reset the wrong branch if needed

“I need to undo a commit”

• If it is already shared, prefer revert (safe and traceable):

git revert <commit-hash>

• If it is local and not pushed, you can reset:

git reset --soft HEAD~1   # keeps changes staged
git reset --mixed HEAD~1  # keeps changes unstaged

“My push was rejected”

You likely need to pull first:

git pull
# resolve conflicts if needed, then:
git push

---

Key Takeaways

• Use branches to keep main stable and deployable.
• Use pull requests and code reviews to catch issues early and keep quality high.
• Resolve conflicts carefully by choosing the correct final code, then staging and committing.
• Write commit messages that explain the change clearly—your future self and teammates will thank you.