A Gentle Intro to Git

Some friends in a Discord server I am in mentioned feeling intimidated by Git, so I decided to put together this blog post to serve as a quick intro to Git for folks who aren't coming from a programming background!

Version Control Systems

Git is a Version Control System (VCS). Its main purpose is to let you keep track of different versions of files and manage a history of changes over time like save points so you can revert to older versions if something goes wrong, or neatly organize multiple versions of your files without interfering with eachother. This is especially important if you're not the only one updating and editing files! Git allows for multiple people to change the same files and keeps track of who made which changes and when, and helps resolve conflicting edits.

While Git is the most popular version control system today, it isn't the only one! Some other popular version control systems include mercurial and jujutsu.

Git Concepts

Before diving into concrete examples, let's go through some standard terminology up front.

Repositories

Repositories are the container of changes that you want git to keep track of. This is usually the folder with all of your content or code and contains your entire project. All of the contents, assets, and code for this blog lives in a git repository!

Commits

A commit is a snapshot in time of your entire project. It encapsulates the state of all of your project's files at that time, information of who created the snapshot, and a unique identifier for that snapshot.

Branches

Branches let you store an alternate version of your project and make independent edits without interfering with the main version. Think of these like an alternate universe or different path in a story so you can experiment with new changes.

This lets you avoid the 'myblog_version1.txt`, 'myblog_version2.txt', 'myblog_newcolors.txt', 'myblog_final_final.txt' problem by letting you experiment on the same file instead of needing new files for each version, and this applies to multiple files or your whole project at once!

Branches have their own set of commits, independent from the main branch of your project, but will also share any commits in common that were created before the branch was created.

Actually using Git

Ok, now that we've gotten the terminology out of the way we can walk through some common git commands and examples of how to use them!

(As a quick side-note, I am recording my terminal on a Linux laptop so you might see some commands like cd, echo, or bat sprinkled throughout the demos. You don't have to worry about these commands, they'll be used for the purposes of setting up the demos and displaying pertinent information. Any commands that are important, I'll call out explicitly! :) )

Installing Git

Git is a cross-platform command line tool that supports every major operating system. Instructions for installing Git can be found here.

Creating a Git Repository

Git repositories can be created (initialized) from a folder that already has some files in it, or git can be used to create a new empty folder. This is done through the git init command.

Let's say I have an existing folder called git-demo that has a few files in it that might have a layout like:

git-demo
├── hello.txt
└── README.md

I can create the git repository like so:

git init git-demo

Checking repository status

In order to see the current state of your branch, you can use the git status command. This will tell you what branch you're on, which files have been modified, which files are new that git isn't watching yet, and some information about the current commit.

For this fresh repository, there won't be any commit information, and all of the files in the repository are new to git (untracked)!

Creating a new commit

Staging files

Before we actually create the commit, you need to add files to the staging area. This is how you mark files as ready to commit before actually committing. This is useful if you're working on changes across multiple files, but you only want to actually take a snapshot of a few of them instead of all of them at once. To do that, you can run the git add commmand followed by one or more files that you'd like to stage:

git add file1.txt file2.txt file3.txt

You can also stage every file in the current folder by running git add .

Committing the staged files

Now that your files are staged, you can create the actual commit by using the git commit command. In practice, it is also good to associate a descriptive message alongside the commit so you know what the snapshot was for or what state your project was in when the commit was created. This can be done with the -m option followed by a message:

git commit -m "added the final paragraph to chapter 22"

Let's see it all in action:

Creating a Branch

With a commit in place, let's make a branch to track some changes we want to keep independent from the main branch created when the repository was initialized. That can be done with the git branch command, followed by a name we'd like to give the branch.

git branch new-feature

Typing just git branch on its own without a branch name will list out all of the branches we have created so far, and it will add a * next to the branch that is currently in use (sometimes you'll hear this referred to as 'the branch we are currently on').

git branch new-feature created the new-feature branch, but we are still using the main branch we were on before! To actually switch to that new branch, we'll need to use the checkout command:

git checkout new-feature

This will swap us over to the new feature branch, and we can use the same command to go back to the main branch. You can create a new branch and swap to it all in one go by running git checkout -b new-feature

Here's branch creation in action:

Notice how when I switch back to the main branch, the edits to hello.txt are gone! That is the power of branches, any changes you make to files that git is tracking is isolated just to the branch you are on, so you are free to experiment and mess things up, all with the safety of knowing you can swap back to a branch that has a working copy of your stuff.

Note that for something simple like a blog or personal website, creating branches is optional and not necessary! You can commit all of your changes to your main branch to keep your workflow simple if you like. It might just be a bit trickier to undo a chance you don't like if you've already committed it to that branch, which is why creating a new branch for larger or riskier changes can be helpful!

Merging branches

So what do you do when you're done with writing some new content or experimenting with something new on your site and you'd like for the changes to actually show up on your main branch? That is where the git merge command comes in!

To properly merge some changes in from one branch to another, you'll want to checkout the branch you want to merge the changes into, and then run git merge followed by the name of the branch whose changes are getting merged in:

After executing the git merge command, the edits I made in the new-feature branch are now visible in hello.txt even when I am in the main branch!

Checking the Git logs

If you'd like to see the history of the various commits on the branch you're on, along with their associated messages and IDs, you can use the git log command:

Git vs GitHub

You might have interacted wtih GitHub in the past to download some software and you may be wondering what the difference or relationship is between Git and GitHub. GitHub is a cloud hosting service that can host remote git repositories. Think of it like Google Drive or Dropbox for Git.

While the git command line tool runs entirely locally, you can sync changes to and from a remote repository very easily! This is super useful for teams of people since everything gets synced to a single source-of-truth server.

GitHub also provides some auxiliary features like bug report tracking, reviewing/approving changes, hosting cloud computers to run tests and checks on changed code, and much more!

It is important to note that GitHub is just one of many services that offer git remote repository hosting. Some notable alternatives include GitLab and BitBucket.

Some of these services have options to host your own Git server rather than relying on a centralized one managed by the owning company (it is also totally feasible to just run your own git server out of your house or with your own cloud computing accounts). There is even a Git repository hosting service called tangled that runs on the same protocol that powers Bluesky, letting you log in with your Bluesky handle and host code in a decentralized and distributed network!

Commands for interacting with remote repositories

Git has built-in support for syncing with remote repositories. I'll go over a few of the common ones you are likely to use if you are a solo git user working on your own website.

• git remote add: First up is pointing your local git repository at a remote one. Once a repository is created in your desired remote git host, you can point your local repository at it by running git remote add <name> <url> where <name> can be whatever you want to refer to the remote repository as (one common name is origin) and the URL is usually provided to you by the service hosting the remote repository.

• git clone: If you don't have the repository locally and you want to download it from a remote host, you can run git clone <url> to download the repository onto your computer.

• git pull/push: To sync new changes from your local repository onto the remote one, you can use the git push command (provided you have already run git remote add). Vice-versa, you can sync changes from the remote repository onto your local one by running git pull. Keep in mind these commands only push/pull changes from the current branch you're on, so if you want to sync changes from a different branch, you need to checkout that branch first, make sure it has already been git remote add-ed, and then run the push/pull commands.

Git GUIs

If all of these commands seem daunting or you aren't quite comfortable yet using command line tools, fear not! There are plenty of folks out there who have created GUIs that help make all of this process more approachable. VSCode comes with Git tooling built in that lets you keep track of changes and commit them with a few mouse clicks:

One of my favorite GUI tools for Git is actually a TUI (Terminal User Interface)! It provides a nice UI for Git while still being contained entirely in the terminal so I don't have to switch windows:

Searching for "Git GUI" will bring up tons and tons of results, so feel free to try a few out to find the one that works best for you!

Wrapping up

While this only covered the basics, there are plenty of resources online for getting into more advanced workflows. One of my favorites is the learngitbranching interactive tutorial that has some great explainers and visualizations for git concepts. Another great one that is handy to reference if you've gotten yourself in a git pickle is Ohshitgit. Hopefully you're leaving this post with a better understanding of how to use git for a simple workflow like editing a blog or a static site.

Happy branching!