Version Control & Collaboration

Build a trustworthy project history, collaborate without overwriting work, and move changes from an idea to a reviewed release.

3 technologies

A small story: You fix a bug, try a bold redesign, and realize the first version was better. With no saved history, you are guessing. With version control, you can compare both attempts, keep the useful parts, and explain how the project got here.

This guide follows one change from a developer’s laptop to a teammate’s review and, eventually, a release. You will learn the ideas behind Git, how GitHub and GitLab fit around it, and how to recover calmly when work gets tangled.

What version control actually does

Version control records changes to files over time. It helps answer practical questions: What changed? Who changed it? Why? Which version was working last week? Can two people work at once without silently replacing each other’s work?

Think of it as a project timeline with named checkpoints. A useful checkpoint is more than an emergency undo button: it gives the team context, makes review possible, and lets people experiment without losing a known-good version.

Three models you may hear about

Model Where history lives What it means in practice
Local version control On one computer Better than manually copying folders, but collaboration and device failure remain concerns.
Centralized version control A central server Users check out files from one shared source; the server is important to daily work.
Distributed version control In each repository clone Each clone has project history, so many operations work offline and teams exchange changes when ready.

Git is a distributed version-control system. It can track a project locally without an account, a hosting service, or an internet connection. GitHub and GitLab host Git repositories and add collaboration features; they are platforms around Git, not replacements for the Git tool itself.

The four places a change travels

The most useful beginner picture is a one-way workbench. A file starts in your Working Tree, you choose what belongs in the next checkpoint, and then you save that checkpoint in your local repository.

Working Tree  ->  Staging Area (Index)  ->  Local Repository  ->  Remote Repository
 edit files       choose this change        commit history        share with the team
Area Plain-language picture Helpful command
Working Tree The files you can currently see and edit. git status, git diff
Staging Area / Index A preview of exactly what the next commit will contain. git add, git diff --staged
Local Repository The saved history on your computer. git commit, git log
Remote Repository Another copy used to exchange history with teammates or a hosting platform. git fetch, git pull, git push

Staging is not busywork. It is the moment you review the contents of the next commit. If a change mixes a typo fix with an unrelated experiment, stage only the pieces that make one clear story.

Your first safe session

Install Git from its official source, open a terminal in a project folder, and check what Git sees:

git --version
git status

For a new folder, start a repository with git init. For a project that already exists on a host, use git clone <repository-url> instead; cloning downloads the project and its history.

Git records the author name and email in commits. Set an identity that you are comfortable publishing:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

--global applies these settings to your user account on this computer. A project can override them locally with git config user.name "Project Name" when needed. Never put passwords, access tokens, or private keys in these values or in the repository.

Make a commit that tells a story

Try a tiny change, inspect it, and commit only what you mean to save:

git status
git diff
git add README.md
git diff --staged
git commit -m "docs: explain local setup"
git log --oneline

Read this sequence as: inspect, review the unstaged difference, select a file, review the staged version, save a checkpoint, then look at the history. git add . is convenient, but it can stage generated files or secrets by accident; for learning, name the files you intend to include.

A good commit is small enough to understand and complete enough to make sense. Prefer a message such as Fix empty search state over updates. Start with an action, keep unrelated changes in separate commits, and add context in the commit body when the reason is not obvious.

Branches: experiment without losing the main path

A branch is a lightweight name pointing to a line of commits. It is not normally a full copy of the project. The default branch—often named main—is the shared path the team treats as stable.

Create a short-lived branch for one change:

git switch -c feature/search-empty-state

Make a few focused commits there. If the experiment fails, the stable branch is still intact. If it works, the branch can be reviewed and merged. Names like feature/, fix/, and docs/ are team conventions, not special Git syntax.

Under the hood, commits form a branching history. A commit points to its parent commit or commits; a branch name moves as new commits are added. HEAD tells Git which current commit or branch you are working from. These ideas explain why switching branches is fast and why a merge can have more than one parent.

Share history with a remote

A remote is a named connection to another repository. The name origin is a common default; it is only a nickname, not a special server.

git remote -v
git fetch origin
git status
git push -u origin feature/search-empty-state
  • git fetch downloads new objects and updates remote-tracking references. It does not silently rewrite your current files.
  • git pull fetches and then integrates a remote branch, usually by merge or rebase depending on configuration and options.
  • git push sends your local commits to a remote branch. The first push often uses -u to remember which remote branch it tracks.

Before sharing, fetch and inspect what changed. If your team has a standard pull strategy, follow it consistently; mixing merge and rebase habits without understanding them can make history confusing.

Pull Requests and Merge Requests: the human review layer

On GitHub, a Pull Request (PR) proposes merging one branch into another. On GitLab, a Merge Request (MR) fills a similar role. The names differ; the central idea is the same: show a focused diff, explain the intent, run checks, discuss feedback, and decide whether to merge.

A healthy review is a conversation about the change, not the person. Keep a PR/MR focused, describe the problem it solves, link relevant work items, and mention risks or screenshots when they help. Reviewers should ask for clarification when intent is unclear and approve only when the change is ready for the project’s standards.

Stage What the contributor does What the team gains
Branch Isolates one piece of work. A reviewable unit instead of a moving target.
Commit and push Records the work and shares it. A traceable history and a visible diff.
PR/MR Explains the change and requests review. Context, discussion, and an explicit decision.
Checks Runs tests and other automation. Repeatable signals before integration.
Merge Integrates accepted work. A shared history the team can build on.

Merge conflicts without the panic

A merge conflict means Git cannot safely decide how two changes should fit together. It is not a failure and does not mean your work is gone. Git marks the affected file and pauses so a person can choose the intended result.

  1. Read the file and understand both changes before editing.
  2. Look for conflict markers: <<<<<<<, =======, and >>>>>>>.
  3. Keep the correct lines, combine them, or rewrite the section as one coherent result.
  4. Remove all conflict markers, run the relevant tests, then stage the resolved file.
  5. Finish with git commit for a merge, or git rebase --continue if you were resolving a rebase.

Do not solve a conflict by blindly choosing “ours” or “theirs.” Those labels depend on the operation in progress, and the discarded side may contain an important fix. If the correct choice is unclear, ask the author or reviewer.

Merge or rebase?

Both operations integrate work; they present history differently.

Operation What it does A sensible use
Merge Joins histories and can create a merge commit. Existing commits keep their identities. Integrating a reviewed team branch while preserving how work came together.
Rebase Replays commits on a new base, creating new commit identities. Tidying your own unpublished feature branch before review, if your team prefers it.

Avoid rebasing commits that teammates already based work on: changing published history forces others to repair their branches. Do not force-push to a shared or protected branch as a shortcut. Agree on a team policy and use the platform’s protected-branch and review settings.

Undo safely: choose the operation by the situation

Git has several ways to undo, and their names are easy to mix up. First run git status and ask whether the change is unstaged, staged, committed locally, or already shared.

Situation Typical tool What it changes
Discard an unstaged edit to one tracked file git restore path/to/file Replaces the working copy from the index. This discards that edit.
Unstage a file but keep its edits git restore --staged path/to/file Removes it from the next commit; the working file remains changed.
Undo a commit that was already shared git revert <commit> Adds a new commit that reverses the selected change.
Rename the last local commit message git commit --amend Replaces the most recent commit; avoid amending a commit others already use.
Move a local branch pointer git reset Rewrites which commit the branch points to; options decide what happens to staged and working files.

git reset --hard can permanently discard uncommitted work. Do not run it as a generic “fix Git” command. git reflog can often help find recently moved local references, but it is not a backup and does not guarantee recovery of every deleted file.

Keep the repository clean and safe

A .gitignore file lists generated or local files Git should not track. Common examples include build output, dependency folders, editor state, and .env files containing local configuration. Ignore rules do not remove a file that is already tracked; untrack it deliberately and check the resulting diff.

Never commit secrets. If a password, token, or private key reaches a remote, deleting it in a later commit is not enough—the secret may remain in history or copies. Revoke or rotate it first, notify the project owner, and follow the organization’s incident process.

Prefer text configuration over large binaries when practical. For large assets, Git Large File Storage (Git LFS) may be appropriate, but confirm that the hosting service and collaborators support it. Git is excellent at text history; it is not automatically a media archive or a backup strategy.

Read and explore project history

git log --oneline --graph --decorate --all
git show <commit>
git diff main...feature/search-empty-state
git blame path/to/file

git log shows the story, git show inspects one commit, and the three-dot diff compares a branch with its merge base. git blame shows which commit last changed each line; it is a tracing aid, not a way to assign blame to a person.

Useful tools for when the story gets complicated:

  • Stash: temporarily set aside tracked working changes with git stash; inspect git stash list before applying an old entry.
  • Cherry-pick: apply a chosen commit onto another branch. It creates a new commit, so the same change can exist twice in history.
  • Bisect: use git bisect to search history for the commit that introduced a regression.
  • Reflog: inspect recent local movements of HEAD and branch references.
  • Tags: mark a named point, often a release; unlike a branch, a release tag is intended to stay put.
  • Submodules: connect one repository to a specific commit in another repository. They add setup and update steps, so document them clearly.

Releases and version numbers

A tag gives an important commit a stable name, such as v1.4.0. A hosting platform can use that tag to create a release with notes and downloadable artifacts. Tags record a point in history; a release process still needs tests, review, and a rollback plan.

Many projects use Semantic Versioning: MAJOR.MINOR.PATCH. In its common form, a major change signals an incompatible public API change, a minor change adds compatible functionality, and a patch fixes compatible bugs. Teams should state their own compatibility promises; the number alone does not guarantee quality.

GitHub or GitLab?

Both platforms host Git repositories and support issues, code review, permissions, and automation. They are products with overlapping features, not different version-control systems.

Consideration GitHub GitLab
Review terminology Pull Requests Merge Requests
Automation commonly associated with it GitHub Actions GitLab CI/CD
Hosting choices GitHub-hosted and supported enterprise options GitLab-hosted and self-managed options
A good selection process Check integrations, governance, and the team’s existing workflow. Check integrations, governance, hosting needs, and what the team can operate.

Neither is automatically the best choice for every project. Choose based on security requirements, integrations, hosting, support, cost, and the team’s ability to maintain the workflow.

From a commit to CI/CD

Continuous Integration (CI) runs repeatable checks when changes are shared: tests, linting, builds, and sometimes security checks. Continuous Delivery/Deployment (CD) extends that path toward packaging and releasing software. GitHub Actions and GitLab CI/CD can run these workflows, but automation is only as trustworthy as its permissions and configuration.

Keep deployment credentials out of source files. Give automation the smallest permissions it needs, protect release branches and environments, review pipeline changes, and make it clear which checks must pass before a release. A green check is evidence—not proof—that software is safe or correct.

A practical student project

Build a tiny notes app, personal website, or class project in a repository you own:

  1. Create a repository and add a short README.
  2. Commit that starting point with a message that explains it.
  3. Create a feature branch and make one visible change.
  4. Use git diff and git status to inspect the work, then stage only the intended files.
  5. Push the branch to GitHub or GitLab and open a PR/MR.
  6. Ask a classmate to leave one useful review comment; respond with a follow-up commit.
  7. Merge the change, add a version tag, and write release notes describing what changed.
  8. Try a harmless conflict on a throwaway branch and resolve it without deleting either side’s work.

The win is not the number of commands. It is being able to explain what changed, why it changed, and how the team can safely continue.

A compact glossary

Term Meaning
Repository / repo A project directory together with its Git history and configuration.
Commit A saved point in project history, identified by a hash.
Branch A movable name for a line of commits.
HEAD Git’s reference to the current checkout.
Working Tree The files currently checked out for you to edit.
Index / staging area The proposed contents of the next commit.
Remote A named connection to another repository.
Fetch Download remote history without integrating it into the current branch.
Merge Join histories.
Rebase Replay commits on a different base, changing their identities.
Conflict A change Git needs a human to reconcile.
Pull Request / Merge Request A hosted proposal to review and integrate changes.
Tag A stable name attached to an important commit.
CI/CD Automated build, test, and delivery steps connected to changes.

Official references

Explore the topic lessons