Skip to content

git.md

Latest commit

 

History

History
296 lines (188 loc) · 9.04 KB

git.md

File metadata and controls

296 lines (188 loc) · 9.04 KB

Git

Table of contents

What is Git

Git is a distributed version control system that tracks changes in your files and lets multiple people collaborate on the same codebase. It records a history of every change, so you can revert mistakes, compare versions, and work on features in parallel using branches.

Docs:

Repository

A repository (or "repo") is a storage location for files that are version-controlled using Git.

Example: GitHub repository

Remote

A remote (remote repository) is a version of your repository hosted on a remote host, e.g. GitHub.

Remotes let you push and pull changes between your local repository and the remote host.

You can inspect remotes in VS Code.

Docs:

See also upstream and origin.

<remote> placeholder

A remote name (without < and >).

Common remote names:

  • origin — your fork on GitHub.
  • upstream — the original repository that was forked.

Root directory of the repository

Commit

A commit is a snapshot of your project at a specific point in time. Each commit records what changed since the previous commit, who made the change, and a commit message describing why. Commits form a history that you can browse, revert, or branch from.

Commit hash

A hash of a commit in Git.

Example: 4aeacb54f898125560c545e5e0477762094027a7

Docs:

<git-commit-hash>

A commit hash (without < and >).

Commit message

A commit message is a short description attached to each commit. It explains what was changed and why. Good commit messages make the project history readable and help teammates understand changes without reading the code.

Guidelines:

  • Keep the first line short (under 72 characters).
  • Use the imperative mood ("add feature", not "added feature").
  • Focus on why the change was made, not just what changed.
  • (Optional) follow the Conventional Commits specification.

Conventional Commits

Rules for creating human- and machine-readable commit history.

Docs:

Common commit message prefixes in Conventional Commits

  • feat: for new functionality.
  • fix: for bug fixes.
  • docs: for documentation changes.
  • refactor: for code changes without behavior changes.

Branch

A branch is an independent line of development. It lets you work on a feature or fix in isolation without affecting the main branch. Under the hood, a branch is a movable pointer to a commit — as you add new commits, the pointer advances.

Branches are central to the GitHub flow: you create a branch, commit changes to it, open a pull request, and merge it back into main when ready.

Docs:

main branch

main is typically the default branch of a repository.

It represents the stable, up-to-date state of the project.

<branch> placeholder

A Git branch name (without < and >).

Examples:

  • main
  • dev
  • upstream/dev

Revision

Typically a commit hash or the branch name.

Docs:

How Git works - text

  • Read this tutorial to learn about Git, Github, and other Git workflows.

Quick mental model:

  • Working tree: your local files.
  • Staging area: selected changes for the next commit (git add).
  • Commit: a save point of your progress since the previous save point (git commit).
  • Commit history: a timeline of these save points.

Simple view:

working tree changes -> git add -> git commit
                         (stage)     (save progress)

Useful commands:

git status
git add <file-path>
git commit -m "docs: update wiki"
git log --oneline --decorate --graph -n 15

See <file-path>.

When confused, start with git status and read it carefully before running the next command.

How Git works - videos

Merge conflict

A merge conflict occurs when two branches modify the same lines in a file and Git cannot automatically decide which version to keep. Conflicts happen during git merge or git pull.

Git marks conflicting sections with conflict markers:

<<<<<<< HEAD
Your changes on the current branch.
=======
Changes from the other branch.
>>>>>>> other-branch

To resolve a conflict: choose which version to keep (or combine them), then remove all conflict markers, and commit the result.

See Resolve a merge conflict.

Practice Git

.gitignore

The .gitignore file allows you to specify which files shouldn't be added to the repo.

Examples:

Common ignored files:

  • Secrets (.env files, keys, tokens).
  • Build artifacts (dist/, build/).
  • Local caches and temporary files.

GitHub flow

Typical sequence:

  1. Create an issue.
  2. Create a branch from main.
  3. Commit changes to the branch.
  4. Push branch.
  5. Open a PR.
  6. Get review.
  7. Merge the branch to main.

Check your Git config

  1. To find out which name and email are used in commits,

    run in the VS Code Terminal:

    git config --global --list

    The output should look like this (but with your values):

    user.name=Inno SE Toolkit
user.email=inno-se-toolkit@gmail.com

Configure Git

Note

See docs about user.name and user.email.

Complete the following steps:

  1. Check your Git config.
  2. Configure user.name.
  3. Configure user.email.

Configure user.name

  1. To set the name that will be used in commits,

    run in the VS Code Terminal:

    git config --global user.name '<your-name>'

    Example: git config --global user.name 'Inno SE Toolkit'

Configure user.email

  1. To set the email that will be used in commits,

    run in the VS Code Terminal:

    git config --global user.email '<your-email>'

    Example: git config --global user.email 'inno-se-toolkit@gmail.com'