Although this is now in your hands, and it's also on the web, so if you really wanted to steal this, I've made it pretty darn easy. I can't imagine why anyone would want to, though. However, you don't need to, because this is licenced under a CC BY-NA-SA 4.0 Creative Commons license. More information is at
FYI, this is made in \LaTeX\,using the report document class. It then gets exported to a letterhalf (5.5 in x 8.5 in) pdf, which then gets made into a booklet using PDF Booklet, which you can find at
The image of Linus Torvalds on the front cover is courtesy JericoDelayah from the WikiMedia Commons and is at \kref{https://commons.wikimedia.org/wiki/File:4_RETAT_04_Linus_Torvalds.jpg}{https://commons.wikimedia.org\\/wiki/File:4\_RETAT\_04\_Linus\_Torvalds.jpg} where you can also find a link to the Creative Commons CC BY-SA 3.0 license there, as well.
I'm pushing this to my own git server as I write this. You can find it \href{https://git.kjodle.net/kjodle/the-codex}{here}: \kref{https://git.kjodle.net/kjodle/the-codex}{https://git.kjodle.net/kjodle/the-codex}. New issues will be pushed after they are complete. A list of topics I may cover in the future can be found at \kref{https://git.kjodle.net/kjodle/the-codex/wiki/List-of-Future-Topics}{https://git.kjodle.net/kjodle/the-codex/wiki/List-of-Fu\\ture-Topics}.
You can just skip over all the diversions in here if you want. It's just how my mind works. (And yes, there will be politics in this. \textit{You have been warned.}) Also, I use a lot of em-dashes, parentheses, and footnotes because that is also how my mind works. It's just one big long stream of consciousness up in here most days.
If you want to donate financial support for the creation of this zine (and all the hours of research that go into it), you can do so at
\noindent\textbf{Credit where credit is due:} A lot of people have come forth (mostly from Reddit) to help me out in various ways. See the preamble to this document in the source code to see them. One aspect of our society is that nobody \textit{has} to help you. It is wonderful when it happens, and I am grateful for their help.
I emerged from college with a second degree and a newly refreshed teaching certificate. My grades were good enough that I managed to earn a place in Sigma Tau Delta, the International English Honor Society.\footnote{\kref{https://www.english.org/}{https://www.english.org/}} I had a website, and had recently installed a Wordpress blog to talk about books.\footnote{\kref{https://bookblog.kjodle.net/}{https://bookblog.kjodle.net/}} ``Web 2.0'' was a buzzword and we still thought that social media could transform the world for the better.
We were wrong. Social media is a great way to make the world better. It's also a great way for nut jobs and conspiracy theorists and racists and fascists to connect with each other and increase their levels of hate and ignorance exponentially. What have we done?
\kdivb{Oh gosh, it's a diversion already.}{-2}
The problem with social media is that while you can broadcast to the world, the reality is that it quickly becomes an echo chamber. You follow people who have the same interests you do, and they follow you back, and it quickly becomes a community. This is a good thing, and this is pretty much where we thought social media would go.
The problem is that some people don't realize that a community is not the same thing as the entire world. If you are one of these people, and you only follow people who agree with your viewpoints, you start to think that the entire world (or the vast majority of it) thinks this way and that you are obviously in the very, very, very large majority.
Of course, you probably aren't. You're just a victim of selection bias.
What this means is that the people you've surrounded yourself with haven't been selected at random. You've selected them precisely because they share the same beliefs that you do. This is not a problem. The problem is thinking that the rest of the world looks like this group of people and then assuming you must be correct because ``everybody else thinks like this too.''
There are two great examples of this, one a comedy routine, one a presidential election (and so, yes—this matters).
The first one is a comedy routine by George Burns and his wife Gracie Allen which was broadcast on their radio show during the height of the Great Depression. This was a period in United States history when telephones were just becoming a widely available household appliance, but most people couldn't still couldn't afford them. I don't recall the skit exactly, and despite literally seconds of searching the web, I haven't been able to find it. But it went something like this:
\vspace{\baselineskip}
\begin{hangparas}{5mm}{1}
\noindent{}\texttt{George: What have you been doing lately, Gracie?}
\noindent{}\texttt{Gracie: I've been doing a survey to see how many of our friends have telephones.}
\noindent{}\texttt{George: And how many of them do?}
\noindent{}\texttt{Gracie: All the ones I've called.}
\end{hangparas}
\vspace{\baselineskip}
The point here is that of course anyone you call on the phone will have a telephone. Audiences in the 1930s understood this—and unfortunately they also understood the ``smart man/stupid woman'' trope as well.
The other occurred during the 1936 presidential election when a publication called \textit{The Literary Digest} predicted that Republican presidential candidate Alf Landon would win the election. Of course, this did not happen, and their margin of error was huge—almost 40 percentage points.
The problem was that the magazine employed a faulty polling technique, and so didn't capture a random sample of the population. It first surveyed its own readers, and then it surveyed two other readily available lists—registered automobile owners and registered telephone users.
At the height of the Great Depression, most people couldn't afford a magazine subscription, much less an automobile or a telephone, and these people tended to vote for Democratic candidates. The inaccuracy of the poll ruined the magazine's reputation, and it ceased publication two years later. (In point of fact, they not only failed to find a random sample, they relied solely on people who responded to their poll, and such people responded because they were vehemently opposed to Roosevelt. This is an example of ``non-response bias'' or ``participation bias'' but the point is the still the same—they failed to select a random group of people to poll.)
I am in a very different place now than I ever thought I would be. I'm not on Plan A or Plan B. In fact, I've pretty much run out of alphabet to describe exactly where I am now.
So where am I?
I work as a data reviewer for a contract research organization in the pharmaceutical industry. That means that drug companies send us samples of their products, and we test them for things like assay, impurities, appearance, disintegration, etc. People who majored in chemistry run the tests and I sit there and look at their procedures and results and make sure that everything was performed correctly and that the results are, indeed, valid.
In theory, I'm an analytical chemist. In practice, I'm a nerdy science accountant who spends his day with his nose buried in Excel spreadsheets. A \textit{lot} of Excel spreadsheets.
Except that I also used to design websites, so my spreadsheets are easy on the eyes, color-coded, and logically oriented—that is, they take you through the analytical method in a step-wise, chronological manner. In other words, we look at standard concentrations first, and then our system suitability tests, and then the actual tests. Every cell is also labeled, so it's clear what goes where. My boss admires them and I am justifiably proud of them. After all, these aren't just your ordinary, run-of-the-mill spreadsheets we're talking about here.
My spreadsheets are so beautiful that when my boss got a glimpse of them he immediately placed me in charge of mentoring new data reviewers, mostly so that they could see what my spreadsheets look like. And I get it. I worked really hard to make spreadsheets that are understandable not just to me but everybody because we may have a corrective action come up at some point and we need to be sable to see how we arrived at the results that have. So yep, I strive to make all my spreadsheets consistent and understandable to someone who has no familiarity with them.
\medskip
\texttt{tl;dr:} I'm \textit{really} good with Microsoft Excel.
\medskip
But it's not satisfying work. It pays the bills\footnote{Well, barely, after the recent fit of massive corporate price gouging—I mean, er…inflation.} It's not exactly the hind end of science, but it's close. (I once worked in a lab that did non-clinical testing\footnote{i.e., rats and mice} and believe me, \textit{that} is the hind end of science.\footnote{Science actually has many hind-ends. This is but one of them.}) I'm not really doing science; if anything I'm just a science accountant, making sure the books balance. It's boring—\textit{really }boring—and more than a bit mind-numbing.
Considering that my entire job exists to help keep the drug supply safe (well, the \textit{legal} drug supply anyway) safe that statement may sound frightening or even disturbing. But it's not really. You want this job to be boring. When it's not boring, it's generally because something has gone wrong, and and this is one of those industries (like nuclear energy or airplane manufacturing) where you really don't want things to go wrong.
I use Okular as a pdf viewer. Even though Ubuntu has a default pdf viewer, it doesn't have a lot of features and is unreliable in some ways. Okular has always been a better choice for me.
The problem is that there is no perfect way to install things in Linux. There are many different ways, and some ways are better than others. I had originally installed Okular from the GNOME Software. The version it installed was an older one though, and it would not update to a newer version that had a feature I wanted.\footnote{Specifically, the option to view bookmarks from a single pdf document, rather than all of them. I get why you \textit{sometimes} might want to view all the bookmarks to a single document, but it doesn't make sense to me to have that on all the time.}
I decided to uninstall that one and install it from Flatpak. This gave me the latest version (24.05.1) which did have this feature. The problem then became that Okular would not open new documents in tabs—it opened each one in a separate window, which I just find annoying. This works if you use \texttt{File $\rightarrow$ Open} to open your pdfs, but who does that? That's the point of a GUI—you can just double-click on files to open them.\footnote{As it turns out this is not so much an Okular issue as it is an ``Okular in Flatpak'' issue. See \kref{https://github.com/flathub/org.kde.okular/issues/36}{https://github.com/flathub/org.kde.okular/issues/36} and \kref{https://bugs.kde.org/show_bug.cgi?id=427653}{https://bugs.kde.org/show\_bug.cgi?id=427653} for more information.} So I uninstalled the Flatpak version until they get that bug fixed (although a bug report was filed for this issue in 2020, so it doesn't look like a priority).
I tried installing it directly through snap using this command:
\input{include/snapinstallokular}
\noindent{}and this \textit{did} give me the latest version. But it wouldn't open. I tried opening it from the command line and got this:
\begin{Verbatim}[breaklines=true]
/snap/okular/155/usr/bin/okular: error while loading shared libraries: libKF6Parts.so.6: cannot open shared object file: No such file or directory
\end{Verbatim}
This is, believe it or not, progress. What this is telling us is that Snap did not install all of the required dependencies, which in this case is \texttt{libKF6Pars.so.6}. So the issue now is: where can we can get that dependency from?
which tells us that this particular dependency is contained in \texttt{kf6-core22}. So to install that, we use:
\input{include/sudoinstallkf6}
Unfortunately that told me that this dependency was already installed. But it's probably not an updated version of it that will run with this newer, improved version of Okular. That's okay, we can fix that with
\input{include/snaprefresh}
That updates the dependencies and also means that Okular will run. A quick check of \texttt{Help $\rightarrow$ About Okular} confirmed that I am on version 24.05.1 and that new documents are opening in tabs when I double click on them in the file manager.
This naturally leads us to the question—\textit{what is a dependency?}
I'm so glad you asked.
The short answer is that a dependency is a piece of software that another piece of software relies on to do something. Which leads us to another question—why doesn't the software in question contain all the code that it needs to have in order to operate? Why do we bother with dependencies?
The short answer is that a lot of different software packages all need to do the same thing. So rather than include that other thing in each software package, we bundle it into a \textit{library}—a bit of software that other software packages can rely upon if they need to. When they do that, this library is now a dependency. The software package in question can't run without it.
To make things even less clear, a dependency doesn't necessarily have to be a library. It could be something like a configuration file, a device driver, or a database.
This is where things get confusing when it comes to computers. Not all dependencies are libraries (some are other things, like I mentioned), but not all libraries are dependencies. They are only dependencies for a particular bit of software. You can have a library on your computer which isn't used by any particular software package, and thus it is not a dependency. You can also have a library which is used by software package Foo, and so it's a dependency of Foo, but it's not used by software package Bar, so it's not a dependency of Bar.\footnote{If you are not familiar with the ``Foo'' and ``Bar'' terminology, they are simply words that computer people use to substitute for anything else, be it a software package, a function, etc.}
For what it's worth, it's not just Linux that does this. Windows also makes use of \texttt{.dll} file—Dynamic Link Libraries. These contain code and data that can be used by multiple programs. For example, there is a .dll file that just handles ``Open'' dialogue boxes. If you are writing a program for Windows, you don't need to worry about creating your own ``Open'' dialogue boxes. You can just call up this .dll file instead.
That's the real reason for using libraries. If you are writing software, chances are it's goign to do a lot of things that other software packages do, like throwing up an ``Open'' dialogue, or printing a document, or displaying something on a monitor. There is no point in creating everything from scratch when so many of the basic things (and a lot of the advanced things) have already been built.
Using shared libraries also reduces the number of resources your computer is using. If you have ten different applications running, they can used these shared libraries which are probably already loaded into memory, rather than loading their own. As a result, you use less memory and things run faster.
Another advantage of using shared libraries is that they are well-written and usually perform without issues, because they are written by people who really know what they're doing. I may not have the foggiest idea of how to create an ``Open'' dialogue box, but I could figure it out if I had unlimited time and resources. The problem is that my time and resources are finite, so it's a better use of my time to rely on a library that already does this thing and does it well.
The biggest advantage of using shared libraries (these days, at least) is \textit{security}. If a security flaw is found in a shared library, it only has to be fixed once. And because many, many people are using those shared libraries, security vulnerabilities have a better chance of being found—and fixed—quickly.
Once you start to get into Linux, you inevitably hear about ``Dependency Hell''. This used to be a huge problem, but it has largely gone away.
Note that I said ``largely'' and not ``completely''. Hence, dependency \textit{heck}.
Dependency hell is what happens when you try to install new software on your computer, but some of the dependencies are missing, conflict with one another, or have been deprecated.\footnote{Because this is no longer much of a problem, I don't want to get into it too much. If you are interested, Wikipedia has an excellent article on depency hell at \kref{https://en.wikipedia.org/wiki/Dependency\_hell}{https://en.wikipedia.org/wiki/Dependency\_hell}.} This problem has largely gone away due to the use of package managers, which handle the actual compiling and installation of software, because they handle issues with dependencies on their own.
For example, on Debian/Ubuntu systems, the default package manager is \texttt{apt}. Red Hat/Fedora uses \texttt{dnf}, openSUSE uses \texttt{zypper}, Gentoo uses \texttt{emerge}, and ArchLinux uses \texttt{pacman}. In fact, the ArchLinux wiki has a page which extensively documents the difference between these different package managers.\footnote{See \kref{https://wiki.archlinux.org/title/Pacman/Rosetta}{https://wiki.archlinux.org/title/Pacman/Rosetta}.} If you've never gotten further than \texttt{sudo apt install foo}, you will find a lot of useful information there.
I know I did. For example, I usually install software using \texttt{sudo apt install foo}, but there is a parameter (which I would know about if I had read the \texttt{man} file for \texttt{apt}, which I obviously have not—in general when working in \texttt{sudo} I just want to do my business and get out) which will just do a dry run of the install: \texttt{sudo apt install --dry-run}.
For example, if I'm thinking about install meld (which is a great little tool for visually comparing files and directories, and which will help you merge them), but I'm not sure what all is going to be installed, I can just run
so don't depend on the relevance to the real current situation!
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following packages were automatically installed and are no longer required:
libwmf0.2-7 php8.2-common php8.2-mysql
Use 'apt autoremove' to remove them.
The following NEW packages will be installed:
meld
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Inst meld (3.20.4-2 Ubuntu:22.04/jammy [all])
Conf meld (3.20.4-2 Ubuntu:22.04/jammy [all])
\end{Verbatim}
This is highly useful information, so let's break this down a bit.
\begin{enumerate}
\item First, \texttt{apt} is telling me that this is only a situation, so I don't have to go into Karen mode when I try to run this application later and can't find it.
\item It's also reminding me that \texttt{apt} needs root privileges to actually do anything. I didn't use \texttt{sudo} here because I don't want to get in the habit of using it all the time.\footnote{Which is the same reason I don't use the ATM at a casino. If I'm out of money, it's time to go home.}
\item It also tells me that I have a couple of packages that I don't really need, and it provides the command I need to remove them.
\item It then tells me which packages it will install. In this case, it's only going to install the \texttt{meld} package, which means either that \texttt{meld} doesn't need any dependencies, or that all the ones that it needs to function are already on my system.
\end{enumerate}
This is the kind of information I need to think about before I install something. How many new packages will I have to install? How much space will it need? What am I even doing with my life? (Okay, there's no option for that, but it sure would be nice if there were one, wouldn't it?)
\section{Containers}
As a way around any risk of dependency hell (or dependency heck), software developers have also started putting their software into containers. A container is basically an entire runtime environment: it's your application, all of its required libraries and binaries, along with any configuration files, all bundled into a single package.
And yes, if it seems like we are moving backward, we are, in a way. I'm not going to say too much about these because I am not terribly familiar with them, although I've used a few of them. This is going to be a very brief rundown, because if I go into too much detail, I am likely to be wrong.\footnote{To be honest, I'm not even sure that the word ``container'' is the right word here because a lot of people on the internet cannot agree. Just be aware that if you research any of this on the web, be aware that you will find a lot of people who agree with my characterization (yay! I'm right!) and you will also find a lot of people who disagree with my characterization (poop! I'm wrong!). Such is life.}
\paragraph{Snap} First developed by Canonical (the for-profit company behind Ubuntu) this creates a new directory in your \texttt{\$HOME} directory to install snaps. (I did not like this at first, but okay, whatever.) One of the ideas behind snaps is that you can run different versions of the same program. Which would be handy, except that the people responsible for maintaining the snap packages do a pretty crap job of it, and most snaps are a version or two (or more) behind the current release version.
\paragraph{Flatpak} A quick look at the Flatpak home page\footnote{\kref{https://flatpak.org/}{https://flatpak.org/}} shows that they consider themselves ``The future of apps on Linus''. That's pretty confident. But the idea is pretty much the same as a snap. You first have to install \texttt{flathub}, then you download the relevant file from \kref{https://flathub.org/}{https://flathub.org/} and install it. It's not perfect, but for the one app\footnote{Paper Clip, which allows you to quickly and easily edit a pdf file's metadata. If you need to do that, I highly recommend it. See \kref{https://flathub.org/apps/io.github.diegoivan.pdf_metadata_editor}{https://flathub.org/apps/io.github.diegoivan.pdf\_metadata\_editor} for details.} I need that is only available as a Flatpak, I suppose it works well enough. But I would hate to have to install all of my software this way.
\paragraph{AppImage} Thi sis perhaps the simplest one I've used—you just download a file, make it executable, and then run it. I don't have too much of an issue with this one, but I only have a couple of apps that run from an AppImage. (Among them is the Cool Retro Terminal,\footnote{\kref{
https://github.com/Swordfish90/cool-retro-term}{
https://github.com/Swordfish90/cool-retro-term}} which takes me right back to my days in seventh grade. It's pretty cool, but depending on the day it either makes me sad or happy, so I don't use it often.
Dependency hell is suppposed to be a thing of the past, so I'm not quite sure why I ran into an issue with dependencies when trying to install a different version of Okular.
It's possible that the snap was configured wrong. It's also possible that I borked\footnote{I.e., I misconfigured or broke something.} something without realizing it when I was doing something else. (I do have a tendency to tinker with things under the hood.) Unlike the days of old I did not have to spend hours or days trying to figure this out. A couple of quick web searches got me up and running again.
\lettrine[lines=2, loversize=0.2, findent=2mm, nindent=1mm, image=true]{git-icon}{} Git is version control software. That is, it allows you to record and track changes to a set of files over time. You can then compare different revisions or even revert some files or the entire project back to a previous version.
What I'm going to do here is describe how I understand and use Git. I am far from a power-user or expert in Git, so I may get some things wrong. Please let me know if I do, or if you need clarification on some things. (My email address is on page 40.)
Git is great if you are a software developer, because as you work you make a \textit{lot} of changes to your code. It's also great if you are a writer, because you can work with complete confidence that you can experiment as much as you want and not have to worry about losing or overwriting something. You can also revert to an earlier version, or \textit{branch} in order to experiment. But more about that later.
Git works best with text-based files—basically, anything that has a \texttt{.txt}, \texttt{.html}, \texttt{.css}, \texttt{.php}, etc. extension will work. There's no reason that you can't add binaries, such as images, pdfs, Microsoft Word fles, or LibreOffice files. (I'm writing this zine in \LaTeX{}, and do include a few images in most issues, for example.) The issue is that because they are binaries, Git won't be able to tell you the difference between versions. (I would add, though, that if you are writing, you really should separate out the content and the styling from the beginning, so that you can focus on the story you want to tell.)
If you are just starting out with Git you'll make faster progress if you understand some of the basic concepts. If you are coming to Git from a different version-control software, then some or all of these concepts will be familiar to you, although they will probably have different names. Keep in mind that all of these technologies work differently, so you may have to retrain your brain to follow a different workflow.
\paragraph{Concept One: Git exists in both time and space.} This is true of just about all version control software, or at least all the different types I am aware of.
\paragraph{Concept Two: The basic time unit of Git is a \textit{commit}.} A commit is simply a snapshot of where your project stands at any given moment. When you make a commit, it's like taking a picture of your project at that particular moment.
\paragraph{Concept Three: The basic space unit of Git is a \textit{repository}.} All those commmits have to live somewhere, and a repository is just a place where all those commits exist. Repositories (or ``repos'' for short) can be \textit{local}—that is, they exist on your computer only—or they can be \textit{remote}—meaning that can live on other computers somewhere else. That ``somewhere else'' is usually a publicly available server. You can create your own\footnote{You can see mine at \kref{https://git.kjodle.net/}{https://git.kjodle.net/}, for example.} or you can get an account at someplace like Gitlab\footnote{\kref{https://gitlab.com/}{https://gitlab.com/}} which is for-profit and wants your money, or Github\footnote{\kref{https://github.com/}{https://github.com/}} which is now owned by Microsoft and wants your soul.
You can work with a local repository only, or you can decide to work with one or more remote repositories. The choice is up to you.
\paragraph{Concept Four: Repositories are multi-dimensional.} If you make a series of commits to a repository, it will be linear in nature. This is perfectly ordinary. But you may get to a point where you want to experiment with a change and you're not sure whether you'll like the new version or the old version better. Rather than commit that new version, which overrides the original version, you can \textit{branch} and have both versions existing at the same time. A branch is basically a copy of a repository at this point in time (i.e., from the last commit). You can then switch between branches and test things out.
If you like the changes you have in the branch, you can then \textit{merge} them into your main branch. If you don't like them, you have a choice. If, on the one hand, you want to keep them around (in case you change your mind later, or as an example of what \textit{not} to do) you can just return to your main branch and continue working there. That experimental branch will still be hanging out there, existing in our space, but in a parallel dimenstion. If, on the other hand, you want to forget that you ever did that, you can return to your main branch and then delete it entirely. It will be like it never existed.\footnote{If only we could get a version of Git that would manage our actual lives, this would be great. Until then, we will go on making bad decisions.}
I really dislike writing about how to install things, because 1) space in this zine is limited, 2) methods are subject to change over time, and 3) those instructions are usually available at the other end of a web search. But I love Git and want to encourage as many people as might be helped by it to use it, so here we go.
If you are using some version of Linux, chances are pretty good that git is already pre-installed on your system. If you're not sure whether it is or not, you can always open a terminal and type \texttt{git --version}. You'll either get the version that is currently installed on your system, or a message like ``command not found'', meaning that it isn't installed on your system.
I simply have no idea. I don't use Windows except at work.\footnote{The last version of Windows that I used in real life was Windows 7. I loved that version of Windows and got a lot of work done on it. But Windows 10 is ugly and clunky and mostly spyware. Windows 11 is ugly and entirely spyware.} I also don't have access to a secure macOS install, so I can't experiment. But instructions are available on the web. Start with \kref{https://git-scm.com/book/en/v2/Getting-Started-Installing-Git}{https://git-scm.com/book/en/v\\2/Getting-Started-Installing-Git}.
Git is a command line based technology. Yes, there are GUIs out there for Git, and if you are on Windows or macOS, you may find them useful. You can see a fairly comprehensive list at \kref{https://git-scm.com/book/en/v2/Getting-Started-Installing-Git}{https://git-scm.com/book/en/v2/G\\etting-Started-Installing-Git}.
In general, I advise against using any type of GUI. For one thing, Git is fairly easy to manage from the command line, so using a GUI just adds a level of abstraction that we don't really need. For another, the command line is forever, but GUIs come and go. If your GUI gets to a point where it's development is discontinued, or it decides to adopt a subscription model that you can't afford, you're screwed.
\section{Local Repositories}
Let's start with local repositories. Assuming you have folder full of files you want to track using Git, open a terminal window in that location (which is now called your ``working directory'') and type \texttt{git init}. Congratulations! You now have a local Git repo!
What has happened is that Git has created an invisible directory (\texttt{.git}) that it will use to store the metadata and database for your project. Do \textbf{not} delete this folder!
We haven't made any commits yet, though. All we have are files in our working directory. To make a commit, we need to \textit{stage} our files by using the \texttt{git add} command. You can do this a couple of different ways: we can either list each file one by one (\texttt{git add file1.txt file2.txt}) or we can just add them all in a single go by using the \texttt{*} wildcard (\texttt{git add *}).
Now that we've added our files, they are considered to be \texttt{staged}, which means that they are ready to commit. We can make a commit now, or we can modify or create new files, and then add them as well. The choice is yours—Git really doesn't penalize you either way. Personally, I prefer to make many smaller commits to avoid losing data.
If we're happy with the files we've staged, we can now commit them by using \texttt{git commit -m "<commit message>"}. Note that we have to add a commit message. This can be anything you like, but it helps to make it something that will be useful down the road like ``updated chapter three''. You'll get some miscellaneous messages about what Git is doing and then it is done. You've created your first commit, and all of your staged files are now \texttt{committed}.\footnote{You can also make this process even more efficient by creating some bash alias for the various Git commands. See ``More Fun with bash'' in issue \#4.}
If you want to experiment, the best way to do that is to create a \textit{branch}. To do that, just use \texttt{git branch <name>}. To move to that branch, you check it out\footnote{For a visual depiction, see, \kref{https://www.youtube.com/watch?v=8qxDBiiVjlQ}{https://www.youtube.com/watch?v=8qxDBiiVjlQ}.} using \texttt{git branch checkout <name>}.
Of course, there's a shortcut to this. We can use
\input{include/checkout}
which creates a branch called <name> and moves us to it automatically.
Remote repositories make it each to share your work and to collaborate with others. You can do all sorts of things locally, but at some point, you're probably going to want to put your work out there.
\subsection{Getting a Remote Repository}
If you set up a remote repo on some place like GitHub, or you find a repo somewhere that you would like to work with on your own, you can \textit{clone} that remote repo like this:
\input{include/clone}
For example, if you wanted to get a copy of the Apollo 11 Guidance Computer source code because you happen to be planning a trip to the moon of your own,\footnote{I was delighted to find out that this was available on GitHub. I first learned about this in the Volume Thirty-Eight, Number Four issue of \textit{2600} in an article called ``Supply and Demand, Apollo 11, and GitHub'', which is something I will probably talk about in the future.} you would just type \texttt{git clone https://github.com/chrisl\\garry/Apollo-11}. Git would create a directory called ``Apollo-11'' and clone a local version of that entire repository into it.
If you want to see the remotes attached to this repo, you can just type \texttt{git remote -v}. In this case, it would show you something like this:
Of course, those remote repositories don't belong to you, so you can't push any changes you make to them. What you can do is create your own remote repo on a Git-hosting system. I'll do that on my Git site at \kref{https://git.kjodle.net/kjodle/Apollo-11}{https://git.kjodle.net/kjodle/Apollo-11}. To add that remote to my local repo, I will use this:
\input{include/remoteadd}
And running the \texttt{git remote -v} command again shows that I have two different remotes:
I named my remote origin ``ogit'', which is the first letter of my last name combined with ``git''. Let's get rid of those remotes on GitHub, since I can't push any changes to them anyway. to do that we'll use this command:
\input{include/remoteremove}
Running \texttt{git remote -v} again shows that I now just have the remote on my own website:
Are we ready to upload this code from my local repository to my remote repo? Not yet. Let's see what our local branches are by running \texttt{git branch}, which gives us this:
\begin{Verbatim}[]
* master
\end{Verbatim}
In this case, I only have a single branch, which is named ``master''. It also has an asterisk because it's the current branch. The problem here is that my Git website always names branches ``main''. So we need to change that branch name by running
\input{include/branchrename}
Running \texttt{git branch} again confirms that our branch has been renamed:
\begin{Verbatim}[]
* main
\end{Verbatim}
\subsection{Pushing Changes to a Remote Repository}
Okay, we have a local repository, we have a remote repository attached to that local repository, and our current branch on both repos have the same name. It's time to move our code from our local repository to our remote one. For that we use, \texttt{git push} <name of remote repo> <name of remote branch>. Since our remote is named ``ogit'' and our branch is named ``main'', the full command looks like this:
\input{include/push}
Git thought for a second, and produced output like this:
Total 3414 (delta 2327), reused 3414 (delta 2327), pack-reused 0
remote: . Processing 1 references
remote: Processed 1 references in total
To https://git.kjodle.net/kjodle/Apollo-11
* [new branch] main -> main
\end{Verbatim}
That really did take only about 1 second to push 3.1 MiB\footnote{That's not a typo. MiB stands for a \texttt{mebibyte}. See ``The Later Salad Days'' in issue \#2 for more information.} of data. One nice thing about Git is that it is remarkably fast.
Here's the cool thing about Git: if you visit that original repository that I cloned on GitHub, you'll see that it has 547 commits. If you then visit the repository I created at \kref{https://git.kjodle.net/kjodle/Apollo-11}{https://git.kjodle.net/kjodle/Apollo-11}, you'll see that it also has 547 commits.
This is one of the nice things about Git: when you clone that remote repository, you are getting \textit{everything} associated with that repo. Other version control applications just checkout the most recent version. Hence the term ``clone'' rather than ``checkout''.
For what it's worth, you can have multiple remotes. I can create a remote repository on GitHub, clone it to my local machine, then create a remote somewhere else and add that remote to my local repo. To keep both remotes up to date with local changes, you'll need to push twice, once with \texttt{git push remote1 main} and again with \texttt{git push remote2 main}.
One of my favorite aspects of Git is that it's fairly intuitive to understand and start using right out of the box, but it's also robust enough to meet the needs of large teams and organizations. What I've done in the following table is to summarize the commands I've used in this primer, along with examples where appropriate. I've also included a few commands in this table that you probably won't use unless you are collaborating with others which I haven't discussed because it's outside the range of my experience. But I did want to include them to make the table a little more complete.
Ever since I first learned about outlining in high school (or was it earlier?) I've always loved being able to organize information hierarchically. The irony is that I also love biology and the natural world does not necessarily organize itself in a hierarchical way. Cross-pollination and inter-species breeding is a thing.
You can use the built-in \texttt{enumerate} environment to create outlines, but it requires lots and lots of nested enumerate environments. (\texttt{html} is the same way—an occupational hazard, I suppose, of liking outlines.) I grew up using a typewriter, so I've always been looking for something simpler.
The indents in your source code are absolutely not necessary, but you can indent with tabs or spaces to help you keep visual track of things. The levels are controlled by the number after the backslash.
A couple of caveats: First, you are limited to four levels of indentation. (This is a part of \LaTeX{}.\footnote{It is possible to build list environments with more than four levels, but I don't think they would automatically work with the \texttt{outlines} package. However, its code is fairly straightforward and simple, so if I get time, I may play around with making my own package.}) But you can always introduce a normal, non-itemized paragraph into your list by using \verb|\0| as a list item, which prevents you from having to end a previous environment and creating a new one.
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{outlines Example with Normal Paragraph}]
\begin{outline}[enumerate]
\1 First Item
\2 First sub-item
\2 Second sub-item
\0 This is a non-itemized, non-indented paragraph
\1 Second Item
\2 Another sub-item
\3 A sub-sub-item
\3 Yet another sub-item
\end{outline}
\end{Verbatim}
gives us this:
\begin{outline}[enumerate]
\1 First Item
\2 First sub-item
\2 Second sub-item
\0 This is a non-itemized, non-indented paragraph
\1 Second Item
\2 Another sub-item
\3 A sub-sub-item
\3 Yet another sub-item
\end{outline}
This also resets all the counters after that normal paragraph. I think this is fairly typical behavior for outlines, however.
I also passed the \texttt{[enumerate]} option to the environment, so that instead of symbols, it uses numbers and letters to label the list items, rather than symbols. I like this.
Unfortunately, this is not the style of outlining I learned in high school.\footnote{Apparently, I learned what the Purdue OWL calls a ``decimal outline''. See \kref{https://owl.purdue.edu/owl/general_writing/the_writing_process/developing_an_outline/types_of_outlines.html}{https://owl.purdue.edu/owl/general\_writing/the\_writing\_process/developing\_an\\\_outline/types\_of\_outlines.html}.} However, it is possible to use \texttt{renewcommand} to change the counter style when using the \texttt{[enumerate]} option to get what we want. What we need to know is that the \texttt{enumerate} list style uses two sets of placeholders to keep track of things. \texttt{labelenumi} etc. determines what kind of label you see, and \texttt{enumi} etc. keeps track of the counter. So we can do something like this:
Keep in mind that because we are using the standard \texttt{enumerate} commands, this will affect \textit{all} numbered listst that follow it. We would have to reset these if we need to prevent that from happening. For that, we can use this code:
\begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{Commands to Reset enumerate Environment}]
\renewcommand{\labelenumi}{\arabic{enumi}.}
\renewcommand{\labelenumii}{(\alph{enumii})}
\renewcommand{\labelenumiii}{\roman{enumiii}.}
\renewcommand{\labelenumiv}{\Alph{enumiv}.}
\end{Verbatim}
If you need to pop in and out of your outlines and also numbered lists quite a bit, you could just turn both sets of those \texttt{renewcommand} lines into macros to make your mischief a bit easier to manage.
\section{Customizing \texttt{enumerate} and \texttt{itemize} List Environments}
Given all that, it's pretty easy to see how to customize list environments. You just need to know the commands that those environments use to keep track of things. Here's a list of the commands used to generate the labels for both environments:
\subsection{the \texttt{ccicons} package}I release this zine under a Creative Commons license (which you can read about on page 2). Prior to this, I had already included a small image that summarizes that license, which I had downloaded from the Creative Commons website. As it turns out, the \texttt{ccicons} package will do this for you—no need to add that image.
(I actually learned about this while working on issue \#4, but it was very close to the end and I came across it accidentally—it wasn't something I was looking for. But serendipity is somethings a thing, so here we are.)
You can add icons individually, but it also has commands to typeset each license and its icons. Because it's basically just a font, you can do with it whatever you would normally do with other text. For example, these lines
\subsection{Using \texttt{input} to Keep Your \LaTeX{} GUI Happy}
You'll notice that chapter \ref{dephell} has a couple of code samples that include code that you enter into the terminal. As such, they include a dollar sign (\$) to indicate the prompt.
While it's easy enough to include those in a \texttt{verbatim} environment, I'm using a GUI to create this (Texmaker,\footnote{See \kref{https://www.xm1math.net/texmaker/}{https://www.xm1math.net/texmaker/} for more information.} in fact) and anything in math mode—that is, anything that follows a dollar sign—is highlighted in green until it gets to another dollar sign. If it doesn't, then everything after that dollar sign is green, which kind of defeats the purpose of code highlighting.
The easy way around this is to write up those code samples in an independent \texttt{.tex} file, and then use the \texttt{input} command to add them at the appropriate point in my story. That keeps the source code in my GUI nice and clean looking, and means that the text highlighting actually means something.
Also, there is a similar command (\texttt{include}) that works in a similar way, but adds a pagebreak before and after the included text. This is pretty handy if you are working on a longer document. For more information, see \kref{https://tex.stackexchange.com/questions/246/when-should-i-use-input-vs-include}{https://tex.stackexchange.com/questions/246/when-should-i-use-\\input-vs-include}.
I have a table of basic Git commands on page \pageref{tb:gitcommsum}. One of the commands is \texttt{git -{}-version}. Notice that ``version'' has two hypens in front of it, as is typical with full-word bash options. But just typing two hypens didn't display two hypens, it displayed a single hyphen. I was momentarily confused.
What I forgot is that \LaTeX{} has a habit of collapsing multiple hyphens into ligatures. Two hyphens get converted to an en-dash, and three hypens get converted to an em-dash. But because this was displaying in a monotype font, it looked like an ordinary hyphen, even though it was an en-dash.
The fix for this was to use the \texttt{\{\}} token between the two hyphens. Without it, \LaTeX{} sees the two hyphens as a single entity, whereas with it, it sees them as two separate entities. Using this in my file \texttt{git -\{\}-version} gives me what I needed: \texttt{git -{}-version}.
Sometimes the simplest things are the easiest ones to forget.
Read that \textit{again—there is a Hannah Montana version of Linux}.\footnote{Get it while it's hot at \kref{https://hannahmontana.sourceforge.net/}{https://hannahmontana.sourceforge.net/}.}
The developer (who has chosen to remain anonymous—I understand this desire) said that they decided to create this in order to attract young users to Linux. As the FAQ\footnote{\kref{https://hannahmontana.sourceforge.net/faq.html}{https://hannahmontana.sourceforge.net/faq.html}} says, ``I created this idea after a lot of reading and work''.
The problem with this sort of approach is that television shows geared toward tweens and teens come and go like busboys in a restaurant. Here today, gone five minutes later. I have no doubt that a lot of middle school students in 2024 have no idea who Hannah Montana is. (As it \textit{should} be.)
Still, I applaud the work that went into this. If nothing else, it shows that you can pretty much do anything with Linux if you have the time and the energy and also the curiosity.
\noindent{}This one got done a lot faster than \#4. I got stuck with the previous issue because I got distracted by some other things going on in my life (like my job). As a result, this zine went from feeling like a ``get to do'' kind of thing to a ``have to do'' kind of thing. Like just about everybody else, I have far too many ``have to do'' things in my life already.
What got me unstuck\footnote{I don't believe in writer's block. As Stephen King said, there's no such thing. After all, snow plow drivers don't get snow plow driver's block. That said, it is possible to adopt some unhealthy thinking patterns that make you get \textit{stuck}.}—that is, what turned this from a ``have to do'' back to a ``get to do''—was to focus on the process, and not the product. I left myself have fun with it, in other words. That's something I need to periodically remind myself of, even when the thing in front of me is an actual ``have to do'' like my job. Despite the fact that my job is boring me to death, there are still aspects to it that are quite enjoyable. I try to enjoy them as much as possible, and not let them be overshadowed by the parts I don't really like.
In old news, I do occasionally make other zines besides this one, and I have a website for all of them at \kref{https://just13.click/}{https://just13.\\click/}. I used to have a mailing list, but Mailchimp blew it up. If you want an email notification of when I produce a new zine, feel free to send me an email at \texttt{wolfgangswishlist@gmail.com} and let me know which zines you want to hear about.
I also have some ideas for other zines that might cover some of the topics I talk about in here in greater depth. I'm not sure how that's going to evolve just yet, so stay tuned.
On page 2 is a link to a list of topics I intend to cover in future issues. If you have ideas for things you'd like me to talk about, send me an email at the above address.
