Core Concepts

Definitions with examples.

📦 Repository (Repo)

The "folder" that Git tracks. It contains the entire history of changes.

• Local repo: on your own machine
• Remote repo: on GitLab

Example: the Chronos project → 1 repo, with a local copy on your PC and a remote on GitLab.

📝 Commit

A snapshot of your changes, with a message explaining what you did. It's like a save point in a game.

Every commit has: a unique hash (e.g. a3f5c9d), an author, a timestamp, a message, and a pointer to its "parent" commit.

Commits are local until you push.

Example: you changed the config files → git add → git commit -m "2030-projectX-central-4h-1cycle". In SourceTree: staged files (bottom left) → write a message → Commit button.

:::warning Common misconception Commit ≠ Push. The commit stays on your machine until you send it. :::

🎯 Stage / Staging (Index)

The process of "marking" which changes go into the next commit.

Why does it exist? Because you might have changed 5 files but only want to commit 2 of them (e.g. to split your changes into logical commits).

• Unstaged = "I've seen it, I haven't added it yet"
• Staged = "ready to go into the commit"

In SourceTree: top list = unstaged, bottom list = staged. Click the checkbox or drag to stage.

Command: git add config.yaml (or git add . for everything)

⬆️ Push

You send your local commits to the remote (GitLab), so others can see them.

Example: you made 3 commits locally all morning. At the end you hit Push → they go up to GitLab, onto the branch you're working on.

warning

If someone else pushed before you to the same branch, your push will fail until you first do a pull/fetch + merge.

⬇️ Fetch

Downloads the information (new commits, branches) from the remote, without integrating it into your files.

It's like saying: "Show me what changed on GitLab, but don't touch anything of mine yet."

Useful for seeing what your colleagues did before deciding whether to merge.

In SourceTree: the Fetch button at the top. You'll see the remote branches update (grey lines in the graph) but your working directory stays the same.

⬇️➕ Pull

= Fetch + Merge (or Fetch + Rebase, depending on the setting) in one step.

It downloads the changes from the remote AND integrates them into your current branch.

Example: you start your day → first thing, Pull on main, to get whatever the others did overnight.

tip

See Pull: Merge vs Rebase for the difference.

🌿 Branch

An independent "path" of development. It lets you work on something new without affecting the main code (main/master).

• Local branch: exists only on your machine
• Remote branch: exists on GitLab (e.g. origin/feature-x)
• Tracking branch: a local branch that is "connected" to a remote branch, so push/pull knows where to go automatically

Example: you want to try a new scenario without breaking production. → git checkout -b feature/battery-degradation (creates + switches to the new branch)

In SourceTree: right-click the branch → New Branch, or the Branch button at the top.

Common naming conventions:

• feature/xyz — new feature
• fix/xyz or bugfix/xyz — bug fix
• hotfix/xyz — urgent production fix
• release/1.2.0 — release preparation

🔀 Merge

Joins the changes from one branch into another, creating a merge commit (if needed) that has 2 "parents".

Example: you finished feature/battery-degradation and it works → go to main → Merge feature/battery-degradation in.

The history clearly shows that there were 2 separate branches that came together (a fork in the graph).

• Upside: keeps a full, accurate history.
• Downside: the graph can get "messy" with lots of merges.

🔁 Rebase

Takes your commits from one branch and "rewrites" them on top of the latest version of another branch — as if you'd made them there from the start.

Example: you work on feature/battery-degradation for 3 days. Meanwhile main has moved on. You run git rebase main (while on the feature branch) → your 3 commits "move" as if you'd started today, on top of the latest main.

• Upside: clean, linear history (no merge commits).
• Downside: it rewrites history → never rebase a branch that others have already pulled (you'll create chaos for them).

:::tip Rule for beginners Merge when you're not sure. Rebase only on personal, local branches before you share them. :::

⚔️ Merge Conflict

Happens when Git can't decide on its own how to combine two changes on the same line of a file.

Example: you changed a line in config.yaml to "X", your colleague changed it to "Y", and the two branches are trying to come together.

Git shows you something like:

<<<<<<< HEAD
cycles_per_day: 1.5   # your change
=======
cycles_per_day: 2.0   # colleague's change
>>>>>>> feature/battery-degradation

You have to pick (or combine) manually, delete the <<<<<<< / ======= / >>>>>>> markers, then git add + commit to resolve the conflict.

In SourceTree: conflicted files show up with a red icon. Right-click → Resolve Conflicts → Launch External Merge Tool (or do it by hand in an editor).

🔗 Remote

A "name-pointer" to a remote repository location (e.g. on GitLab).

• The default remote name is almost always origin
• You can have multiple remotes (e.g. origin for GitLab, upstream for some other fork)

In SourceTree: left menu → REMOTES → you'll see origin and the GitLab address.

📌 HEAD

Points to where you currently are — which commit/branch is "active".

If you're on branch main, HEAD points to the latest commit on main.

"Detached HEAD" = you're on a specific commit, not on a branch (careful, if you commit there those commits can get "lost").

🏷️ Tag

A "label" on a specific commit, usually for versions/releases.

Example: v1.0.0, v1.1.0 for releases.

In SourceTree: right-click a commit → Tag.

📦 Stash

Temporarily "sets aside" changes you haven't committed, without losing them, so you can switch branches cleanly.

Example: you're working on something in feature/battery-degradation, and suddenly you need to go to main for an urgent hotfix, but you're not ready to commit. → Stash (saves the changes "on the side") → switch branch → then Stash Pop to get them back.

In SourceTree: the Stash button at the top. Stashes show up in the left menu under STASHES.

↩️ Reset vs Revert vs Checkout

The most confusing trio:

Command	What it does	Safe?
Checkout	Move to another branch/commit (changes what you see)	✅ Yes, nothing is lost
Revert	Creates a new commit that undoes a previous one	✅ Safe, keeps history
Reset	"Moves" the branch back to an older commit, erasing the history after it (soft/mixed/hard)	⚠️ Dangerous if already pushed

Revert example: you committed something wrong and already pushed it. You want to undo it without breaking other people's history → Revert (safe, public).

Reset example: you committed something locally, have NOT pushed it yet, and just want to erase it as if it never happened → Reset (local, safe only if you haven't shared it).

:::danger Golden rule Reset only for things you have NOT pushed. If you've already sent it, use Revert. :::

🔄 Merge Request (MR)

GitLab's equivalent of a "Pull Request".

It's not a Git command — it's a GitLab feature. It's a request: "I want to merge my branch into main — can someone review it first?"

Flow: Push feature/battery-degradation to GitLab → open a Merge Request in the GitLab UI (feature/battery-degradation → main) → a colleague reviews/comments → Approve → Merge (from within GitLab, not SourceTree).

note

SourceTree does not manage MRs directly — that happens in GitLab's web UI.