kjodle/the-codex
kjodle/the-codex
1
1
Fork 0
Code Issues Pull Requests Projects Releases 2 Wiki Activity

Additions to Git chapter

Browse Source
This commit is contained in:
Kenneth John Odle 2024-07-04 18:17:27 -04:00
parent 251a2c75ad
commit 74bb27a03b
1 changed files with 31 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
005/codex-005.tex
View File

@ -386,41 +386,41 @@ It's possible that the snap was configured wrong. It's also possible that I bork
\chapter{A \texttt{git} Workflow}
\lettrine[lines=2, loversize=0.2, findent=2mm, nindent=1mm, image=true]{git-icon}{} \texttt{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.
\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 \texttt{git}. I am far from a power-user or expert in \texttt{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.)
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.)
\section{What \texttt{git} Can Do For You}
\section{What Git Can Do For You}
\texttt{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 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.
\texttt{git} works best with text-based files—basically, anything that has a .txt, .html, .css, .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, \texttt{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.)
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.)
\section{\texttt{git} Concepts}
\section{Git Concepts}
If you are just starting out with \texttt{git} you'll make faster progress if you understand some of the basic concepts. If you are coming to \texttt{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.
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: \texttt{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 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 \texttt{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 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 \texttt{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.
\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 \texttt{git} that would manage our actual lives, this would be great. Until then, we will go on making bad decisions.}
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.}
\section{Installing \texttt{git}}
\section{Installing Git}
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 \texttt{git} and want to encourage as many people as might be helped by it to use it, so here we go.
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.
\subsection{On Linux}
If you have confirmed that \texttt{git} is not installed on your system, here are some options:
If you have confirmed that Git is not installed on your system, here are some options:
For Fedora-type systems, use \texttt{dnf}:
@ -434,11 +434,25 @@ For Debian-type systems, use \texttt{apt}:
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}.
\subsection{\texttt{git} Clients}
\subsection{Git Clients}
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.}
\texttt{git} is a command line based technology. Yes, there are GUIs out there for \texttt{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, \texttt{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.
\chapter{Easy Outlines in \LaTeX{}}