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 fetchdownloads new objects and updates remote-tracking references. It does not silently rewrite your current files.git pullfetches and then integrates a remote branch, usually by merge or rebase depending on configuration and options.git pushsends your local commits to a remote branch. The first push often uses-uto 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.
- Read the file and understand both changes before editing.
- Look for conflict markers:
<<<<<<<,=======, and>>>>>>>. - Keep the correct lines, combine them, or rewrite the section as one coherent result.
- Remove all conflict markers, run the relevant tests, then stage the resolved file.
- Finish with
git commitfor a merge, orgit rebase --continueif 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; inspectgit stash listbefore 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 bisectto search history for the commit that introduced a regression. - Reflog: inspect recent local movements of
HEADand 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:
- Create a repository and add a short README.
- Commit that starting point with a message that explains it.
- Create a feature branch and make one visible change.
- Use
git diffandgit statusto inspect the work, then stage only the intended files. - Push the branch to GitHub or GitLab and open a PR/MR.
- Ask a classmate to leave one useful review comment; respond with a follow-up commit.
- Merge the change, add a version tag, and write release notes describing what changed.
- 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
- Git documentation — command reference and concepts.
- Pro Git book — a detailed, free guide to Git.
- GitHub flow — GitHub’s branch-and-review workflow.
- GitHub pull requests — creating and reviewing proposed changes.
- GitLab Flow — branch and release workflow guidance.
- GitLab CI/CD — pipelines, jobs, and automation.
- Conventional Commits — one optional commit-message convention.
- Semantic Versioning — the public version-numbering specification.
Explore the topic lessons
Git
BeginnerA distributed version control system that records project history and helps developers work in parallel.
GitHub
BeginnerA collaborative platform for hosting Git repositories, reviewing code, tracking work, and automating workflows.
GitLab
BeginnerA DevSecOps platform for Git repositories, code review, issue tracking, and integrated CI/CD workflows.