Git for Managing Small Projects – InApps 2022

I’m a technology writer, not a full-fledged software developer. Once-in-a-while-fledged is probably more accurate. Managing various CAD/CAM systems, writing application requirements, doing software/hardware integrations and such were my stock-in-trade during my Corporate America years.

Now, I prototype microcontroller projects, explore the latest new technologies and am ramping up 3D printing skills for my steampunk interests, how-to stories and conference tech talks.

The open source git software always looked like it might help organize my firmware revisions, application changes, story drafts and project files. Tracking small, fast-moving projects, like my hands-on tech stories, are a real chore. For whatever reason, I just never got going with git. Of course, finding various bits of content and code for reuse are also a huge challenge. When my editor recently asked if I’d want to create a git tutorial series, I naturally said “yes.” Would git make my life any better? I don’t know yet… we’ll find that out together.

This series explores how git might work for small, real-world hardware/software projects. Git appears cryptic and complicated to the new user. And, it certainly is. Regardless, we’ll get familiar with the git way of doing things and look at how it might (or might not) fit our specific needs. As the series progresses we’ll delve deeper into details, odd quirks and how to tweak the workflows. The inaugural edition will begin with installing git on a Linux laptop and using a few commands, in a terminal, to set up a basic system.

What Is Git and Why Use It?

git is used for tracking and managing changes in files. It works primarily with text files although other file types can be handled with add-ons and extensions. That’s great because I do a lot of work with text files, although not necessarily always source code. git also lets multiple developers easily work together on the same project with speed and efficiency. Tracking and history are available, even when off-line. The system supports non-linear development through branching and is open source. git differs from other version control systems in that it uses the concept of snapshots to index, log changes and house the contents of a project over time. Each commit is an offspring of the first or parent project snapshot. Unsurprisingly, git uses a tree structure for indexing, logging and storing changes.

Put git on Your Linux Notebook

I use Linux for all my computing needs. My late-model Dell notebook sports a Core i7 Intel processor, NVidia GeForce graphics, 16 GB of RAM and a lightning-fast 500GB solid-state drive. The machine is capable of running the Chrome browser, LibreOffice, FreeCad and the Prusa slicer program, all simultaneously without even breaking a sweat. Xubuntu is my Ubuntu 20.04.2 LTS variant of choice with the XFCE desktop. It’s simply a joy to use a modern Linux notebook.

Other hardware, such as various Raspberry Pi, BeagleBone, a RockPi and so on typically operate with ARM versions of Linux in standalone and server roles. This series caters to Linux-based machines, primarily using the command line. You can certainly use git to maintain a project on a Raspberry Pi.

git is also available on Windows and the Mac. The principles discussed can transfer over to work on those machines, although I won’t be discussing any details related to those platforms.

Putting git on a Linux notebook can be done in one of two ways. From a desktop screen use a package manager such as synaptic. Alternately use apt on the command line, in a Linux terminal.

From the desktop start synaptic, search for “git” and then check-mark the installation box. Hit the “apply” button and the program will soon be ready for use. synaptic also installs git-doc, git-man and a few other support packages. Be sure to examine the synaptic program list with the “git” prefix for other interesting supporting applications you might want to install and try out.

Installing git from the command line is almost as easy.

Open a terminal on your desktop.

Next, go through the normal apt package installation ritual, typing in your password as required.

rob-notebook: sudo apt update
rob-notebook: sudo apt upgrade
rob-notebook: sudo apt install git

After a short period, the main git application and its supporting programs will install.

Next, personalize git with your identity information and a few preferences. This is important because git logs change so everybody knows who worked on what in a project. It makes collaboration transparent and easy to follow.

rob-notebook: git config --global user.name drtorq
rob-notebook: git config --global user.email [email protected]
rob-notebook: git config --global core.editor vim
rob-notebook: git config --global init.defaultBranch main

Look at the currently set config parameters with the following command.

rob-notebook: git config --list

If you are comfortable with vi (VIM) or one of the other Linux text editors, you can also edit the ~/.gitconfig file, for preference adjustments.

rob-notebook: vi ~/.gitconfig

git config printout in vi

Use git for a Simple Project

A git project instance needs a local working directory on your laptop. Make a new directory, then move down into it to get started.

rob-notebook: cd ~
rob-notebook: mkdir track-h
rob-notebook: cd track-h
rob-notebook: git init

The git-init command creates a .git subdirectory with a number of other directories and files. cd into the .git directory to take a look. Be aware that if you look up git in man, you’ll notice that the commands are hyphenated.

rob-notebook: man git

I’ll continue using the command-hyphenation convention in the body of this article because it makes reading a little easier. Just remember to remove the hyphen when you use the command in the Linux terminal.

rob-notebook: cd .git
rob-notebook: ls

files in the .git directory

Add Files to a git Repository

A git repository, whether locally on your Linux notebook or up in the cloud is a collection of files that make up your project. It might contain tracked and un-tracked files, the project history, related files like a readme, as well as the changes made over time to all those files.

Git has three general sections, the working directory, a staging area and the git repository.

In our case track-h, is the working directory. Files to edit and include in your project are copied into that directory. At this point, the files only reside in the directory and are not being tracked by git. Staging specifies which files we want to actively track and queue up for each new snapshot or commit of our project. Staging is done with the “add” command. We “commit” our staged files to our git repository to permanently save the contents and history of each project snapshot. Each commit is an indexed snapshot of the project.

Once a directory is initialized as a git repository, copy in your project files.

I made three example files, file1.txt, file2.txt and file3.txt. Each has a line of text, “this is the [xxxx] text file.”, with [xxxx] being a number.

The git-add command inserts a file name into the git repository list and starts tracking its activity.

rob-notebook: git add file1.txt

Check the file status with the git-status command.

rob-notebook: git status

The following graphic shows the current status of the files in our local repository.

file added to the git index

Now, add the second file to the index.

rob-notebook git add file2.txt

Here’s the status showing that we are now tracking two files. Notice that file3.txt is not being tracked, at this time.

2nd file added to the git index

Use git-status, anytime to see the current state of your files.

Suppose, you edit file1.txt, putting “this is a second line of text” after the first line. Now, git-status shows that you’ve edited the file and it is the current version of the file, when finally “committed.” In other words, we are still changing the file in the staging area. You can do this as much as you like and git will remind you that you are changing existing files.

Say you want to throw away all the edits to the file and go back to the original, when you first added the file. Use the restore command.

rob-notebook: git restore file1.txt

What if you want to stop tracking file1.txt altogether? Use the git rm command.

rob-notebook: git rm --cached file1.txt

Now, git status will show file1.txt is an untracked file and again only resides in the track-h directory. It isn’t added to the staging index or committed to a new snapshot.

Making Changes More Permanent

With our edited files in the working directory and their names added to the repository index, we can “commit” them to a snapshot of the project. The git-commit command fills that purpose. Before we do that though, the edited files should be “added” again, to tell git that everything is how we want it for the next commit.

rob-notebook: git add file1.txt file2.txt file3.txt

Or, you can just do all the files that were edited with the -all option.

rob-notebook: git add -all

Next, use git-commit.

rob-notebook: git commit -m “first files committed to our project”

The -m option adds a message to the commit so you’ll have a summary of the changes to your project.

Get a summary of the commit with the git-log command.

rob-notebook: git log

git log printout

Notice that the author and date information appears at the top of the printout. Our “summary” shows up at the bottom. The huge number at the top is the internal repository index of this particular commit. To the right of the commit number is the branch reference, in our case defaulting to “master.”

Make a few edits to your files, then do a git-add –all and a git-commit. Look at the git-status and git-log to get a feel for the workflow.

Wrap up

This is a great place to end this article on the basics. We’ll pick up, next time, on examining the tree structure, analyzing the commits and getting content back out, once we’ve put it into git.

Contact Rob “drtorq” Reilly for consultation, speaking engagements and commissioned projects at [email protected] or 407-718-3274.