Git Basics^
Git is one of the most useful tools for writers and developers. Version control may seem useful when you’re looking at a word processor, but once you figure out the basics of a real version control tool like Git these alternatives seem hobbled and weak.
Writers don’t often work with plain text files, so it’s an extra step for them to transition off word processors. For programmers and systems administrators, the benefits of Git usage are immediately apparent.
Tip
During my time on desktop environments,
like GNOME and KDE, I often initialized a Git repository on my
$HOME/.config directory to track and roll back changes
whenever something happened that borked my config.
This article covers the basics of Git usage, including the initialization of repositories, checking status, committing and rolling back changes, and the rudiments of branches.
Repositories^
In the context of Git usage, a repository is a fancy word for a directory tree. Whenever you perform write operations in this tree, it generates artifacts that Git can read and manage. The repository is generally local to the your machine, but the local instance can synchronize with to remote repositories, such as those hosted on GitHub or GitLab.
Initialize a Repository^
In order to operate on a local repository, you first need to
initialize it. The initialization process creates a hidden
.git/ directory, where Git stores reference information.
To initialize a repository, create and/or navigate to the
directory you want to use and run git:
$ cd ~/repos/avocet
$ git init
Clone a Repository^
As mentioned, repositories are sometimes hosted on remote sources. These remote sources may be business services like GitHub and GitLab, but Git does not require these services. You could just put a base repository on a server and access it through the server’s IP address.
Git can access a remote repository but it operates on a local
instance of that repository. In order to copy that repository
from its remote location to your local instance, you need to
call the clone command.
$ git clone https://git.suckless.org/st
For more information, see Git Remotes.
Check Repository Status^
Git compares the current state of the repository to the reference state and looks for changes. The easiest way to see this is to check the status of the repository.
$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
Untracked files:
(use "git add <file>..." to include in what will
be committed)
Makefile
src/
nothing added to commit but untracked files present
(use "git add" to track)
Here, Git notes that it is currently on the main branch and
that the local branch of main is ahead of the remote (id
est, origin/main) by one commit. You would need to perform a
push operation to send this commit up to remote.
Git also notes that there the Makefile and the contents of
the src/ directory are currently untracked. Untracked files
are largely ignored by Git, you can checkout other branches
without affecting them, but they can generate an error if the
branch contains a file at the same path.
Snapshots^
When you save a file, your text editor takes the buffer in working memory and writes it to disk. The write itself overwrites the previous state of the file, which is not always convenient. In the case of a rogue macro or typo, the overwrite may leave the file in a less desirable state. While still in your editor, you can roll back the write by clicking some undo process and saving the reversion—but the process becomes more complicated when undo history is lost or you come back to the file later.
As when the text editor saves a file, when you commit changes in Git you take a snapshot of the current directory state. This serves two purposes:
You can now undo changes across a directory, reverting several files to their earlier state.
You can share the changes by pushing them up to a remote repository where others can see them.
The changes are all bundled together in a package called a “commit” that includes a commit message to describe the change so that others (including you at some future date) can better understand the nature and scope of the change.
Add Change to Staging^
Commits are not usually ad hoc operations. You take time to make the changes and you take time to stage the commit. To stage a change, add the updated file and then use the status message to see what’s now staged for the commit:
$ git add src/main.c
$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: src/main.c
Untracked files:
(use "git add <file>..." to include in what will be committed)
Makefile
src/log.h
src/internal/
src/external/
As you can see, src/main.c is now listed in the changes to
be committed, with a note that the commit will add the file to
the repository. If the file was already in the repository, the
status message would note it as changed.
Remove Changes from Staging^
In cases where you have added a file that you don’t want to add, you can issue a restore command to remove it from staging:
$ git restore --staged src/main
$ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
Untracked files:
(use "git add <file>..." to include in what will
be committed)
Makefile
src/
nothing added to commit but untracked files present
(use "git add" to track)
In cases where you have a modified file, the restore process removes the changes from staging but does not remove the changes from the file.
Commit Changes^
To make a commit is to take a snapshot of the changes staged in the repository. Commits are identified by hashes, making it easy to find them when you want to roll back to an earlier state.
To commit the staged changes, use the commit command:
$ git commit
Commits should always include a commit message which lays out exactly what changes you’ve made in the file. Git automatically opens the configured text editor to give you a place to write out the commit message.
In cases where your commit message is relatively simple, such as
a note of the basic change you’ve made, you can use the -m
option:
$ git commit -m "ATTREE-17: Adds Support for C Code Blocks"
This sets the simple one-line message for later clarification as
to what the commit changes. To view recent commits, use the
log command:
$ git log
commit 3792d14828260e91f5934a5abd5451067bc3c78b (HEAD -> main)
Author: Kenneth P. J. Dyer <kenneth@dyerhouse.com>
Date: Tue Jan 13 14:55:10 2026 -0600
Removes content to make room for Sphinx rebuild
commit e7dc7bf59a84c65a78870f211e639cd7b1b9339c (origin/main, origin/HEAD)
Author: Kenneth P. J. Dyer <kenneth@dyerhouse.com>
Date: Sat Nov 1 17:40:11 2025 -0500
Updates
commit 426e0d1193b2d641ff59e6095fbb7ac7dce99ef5
Author: Kenneth P. J. Dyer <kenneth@dyerhouse.com>
Date: Tue Jul 22 16:42:29 2025 +0000
Cleanup for reconfigure
Revert Changes^
In cases where you have made changes to a file that you don’t
like and want to wholesale roll the file back to its commit
state, you can do so through the checkout command.
For example, say you’ve tested changed your build process in Make from PDF to HTML but after a while decide that the PDF approach works better for you.
$ cat Makefile
build:
sphinx-build -ab dirhtml src /var/www/html/dyerhouse
$ git checkout -- Makefile
$ cat Makefile
build:
sphinx-build -ab pdf src ~/documents/dyerhouse
Here, Git uses the committed state of Makefile and uses it
to overwrite the current state, restoring it to its content at
the time of the last commit.
Remove Files from Repositories^
In cases where you want to remove files from a repository, use
the rm command. If you need to remove an entire directory,
add the -r flag.
$ git rm src/main.c
$ git rm -r src/bad_directory
Note, Git only tracks files in the repository. If you have a directory that is empty, Git ignore it. If you remove the last file in a directory, Git helpful deletes the directory as well.