Version Control with Git: The Basics

Anyone who has saved files named "report-final", "report-final-v2" and "report-really-final" has met the problem that version control solves. Copies pile up, nobody remembers what changed between them, and two people editing at once can overwrite each other's work. A version control system keeps a careful history of changes to a set of files, so you can look back, compare and undo.

Git is a very common tool of this kind in software work, and developers and people who manage configuration files often use it. This entry teaches four core ideas, repository, commit, branch and merge, and walks through a few safe commands on a practice folder. It assumes you can open a terminal; if not, read command line basics first. Git is useful for text such as code, scripts and notes, which is why it matters to the work described in what a software developer does.

What Git does and does not do

Git is a distributed version control system. Distributed means that each person's copy holds the full history, not just the latest files. According to the Git project's book, Git records a snapshot of the whole project at each commit, rather than a list of small differences per file. If a file has not changed, Git simply points to the earlier identical copy. Most operations use only local files, so you can browse history and commit while offline.

Git does not replace a backup. If your only copy is on your own computer and the disk fails, the history goes with it. It also is not the same as GitHub or similar websites. Those services host Git repositories online so teams can share them. You can use Git alone, with no website at all.

The four ideas

Repository

A repository (often called a repo) is a project folder that Git tracks. Git stores its history in a hidden folder named .git inside it. Leave that folder alone; Git manages it.

Commit

A commit is a saved snapshot plus a message. Git has three states for a file: modified (changed but not saved), staged (marked to go in the next commit) and committed (stored safely in the history). The staging step lets you choose exactly what goes into each snapshot, so one commit can hold one idea.

Branch

A branch is a movable label for a line of commits. The main line is called main or master, depending on your settings. Git itself still defaults to master unless you change it, while many hosting sites use main. A new branch lets you try a change without touching the main line.

Merge

A merge combines the work of one branch into another. If the main line has not moved since you branched, Git can simply move its label forward, which is called a fast-forward. If both lines changed, Git combines them into a new commit.

Try it: your first repository

Use a practice folder with no important files. The git config lines save your name and email in your global Git settings, once per computer, and you replace the example values with your own. The other commands only affect the practice folder.

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

mkdir git-practice
cd git-practice
git init -b main

git init -b main turns the folder into a repository whose first branch is named main. The -b option needs Git 2.28 or newer. On an older version, run plain git init and use the branch name that git status shows wherever main appears below. Now create a file named notes.txt with any text editor and put one line in it, such as "Packing list". Then check the state:

git status

Git reports that notes.txt is untracked, meaning Git sees it but is not recording it. Stage it and make the first commit:

git add notes.txt
git commit -m "Add first packing list"

Edit notes.txt to add a second line, then look at what changed:

git diff
git add notes.txt
git commit -m "Add second item to packing list"
git log

git diff shows the lines you changed since the last staging. git log lists your commits, newest first, each with its message. One thing to remember: Git stages a file as it was at the moment you ran git add. If you edit it again afterward, run git add again.

Writing a good commit message

A message should say what the commit does in a short line, such as "Fix typo in heading". Avoid "stuff" or "update". Future you will read the log to find out what happened and when.

Branch and merge in practice

Branching lets you test an idea without risk to the main line. Continue in the same practice folder.

git switch -c add-travel-section

This creates a branch named add-travel-section and moves you onto it. Add a new line to notes.txt, such as "Passport", then save and commit:

git add notes.txt
git commit -m "Add travel items"

Go back to the main line and bring the work in:

git switch main
git merge add-travel-section
git branch -d add-travel-section

If your default branch has another name, such as master, use that name in the git switch line. Check the name with git status. The git switch command needs Git 2.23 or newer; on older versions, git checkout does the same job. The last command deletes the branch label. It refuses to delete a branch with unmerged work, which makes it a safe command. The commits stay in the history, because they are now reachable from the main line.

What a merge conflict is

A conflict happens when two branches changed the same part of the same file. Git cannot choose, so it pauses and marks the file with lines that look like this:

<<<<<<< HEAD
Passport and tickets
=======
Passport
>>>>>>> add-travel-section

The part above the ======= line is the current branch, and the part below is the branch being merged. A conflict is not a failure. You open the file, edit it into the version you want, delete the three marker lines, then run git add on the file and git commit to finish the merge. Run git status at any time to see what Git is waiting for.

Working habits that prevent trouble

• Commit small and often. Each commit should hold one idea, so history is easy to read.
• Check before you commit. git status and git diff show exactly what is about to be saved.
• Never commit secrets. Passwords, access keys and private files in a repository can be hard to remove from history. Keep them out.
• Use a .gitignore file. It lists file patterns Git should not track, such as logs or build output. It only affects files not yet tracked.
• Work in branches for experiments. The main line stays clean while you try things.

Common mistakes

• Running commands in the wrong folder. Git acts on the repository you are inside. Check with git status first.
• Thinking Git is a backup. Local history is lost with the disk. Copy repositories to another place as well.
• Committing everything with one vague message. Large commits with unclear messages make problems hard to trace.
• Forgetting to stage after a second edit. Only what was staged is committed. Use git status to see changes left out.
• Panicking at a conflict. It is a normal pause. Read the markers, choose the right text, and finish the merge.
• Running a command copied from the internet without reading it. Some Git commands discard work for good. Learn what a command does before using it on something important.

FAQ

Is Git the same as GitHub?

No. Git is the tool that tracks history on your computer. GitHub and similar services host repositories online so people can share and review them.

Do I need Git if I work alone?

It is still useful, because you can look back, compare versions and try ideas on a branch. Many beginners start with personal projects.

What is the difference between a commit and a save?

Saving writes the file to disk. A commit records a snapshot in the history with a message, so you can return to it later.

Can I undo a commit?

Yes, but the right method depends on the situation, and some methods remove work. Read the official documentation before trying, and practice in a folder that holds nothing important.

Where should I go next?

Practice in a small project, then read the Git project's free Pro Git book. Pair this with the Careers and Skills entries on learning plans.