Numerous small edits

git-primer.tex

@@ -1,4 +1,4 @@
-\documentclass[twoside,anypage,draft]{report}
+\documentclass[twoside,anypage,draft,10pt]{report}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %% Packages %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -211,7 +211,7 @@ The \texttt{tabularray} package is, hands-down, the best package for creating ta
 
 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. 
 
-Git also allows you to experiment easily without worrying about messing up your current work by creating a branch and doing your experimental work on the branch. If you like the experimental work, you can merge it into your main branch, or if you decide you don't like it, you can delete it. Git makes experimenting both fun \textit{and} manageable. 
+Git also allows you to experiment easily without worrying about messing up your current work by creating a branch and doing your experimental work on the branch. If you like the experimental work, you can merge it into your main branch, or if you decide you don't like it, you can delete it. Git makes experimenting both fun \textit{and} manageable, but most importantly of all, Git gives you \textit{control}. 
 
 \section{What Git Can Do For You}
 
@@ -223,7 +223,7 @@ If you are a writer rather than a coder, Git still has a lot to offer you as wel
 
 \section{Git Concepts}
 
-If this is your first exposure to version control software 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 and probably different functions. Keep in mind that all of these technologies work differently, so you may have to retrain your brain to follow a different workflow.
+If this is your first exposure to version control software 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 like Subversion or Mercurial, then many of these concepts will be familiar to you, although they will probably have different names and probably different functions. 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.
 
@@ -235,13 +235,13 @@ You can work with a local repository only, or you can decide to work with one or
 
 \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 something 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. You can treat it like a sandbox, essentially.
 
-\paragraph{Concept Five: Git works best with text-based files\index{files, text-based}} Basically, this means 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 files, or LibreOffice files. (This document does include at least one image file, for example.) The issue is that because they are binaries, Git won't be able to tell you the difference between versions.
+\paragraph{Concept Five: Git works best with text-based files\index{files, text-based}} Anything that has a \texttt{.txt}, \texttt{.html}, \texttt{.css}, \texttt{.php}, etc. extension is easy to track through Git. There's no reason that you can't add binaries, such as images, pdfs, Microsoft Word files, or LibreOffice files. (This document does include at least one image file, for example.) The issue is that because they are binaries, Git won't be able to tell you the difference between versions.
 
 \section{Git Clients}
 
 Git is a command line based technology. Yes, there are GUIs (Graphical User Interfaces) 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/Appendix-A:-Git-in-Other-Environments-Graphical-Interfaces}{https://git-scm.com/book/en/v2/Appendix-A:-G\\it-in-Other-Environments-Graphical-Interfaces}.
 
-In general, I advise against using any type of GUI with Git. 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 in trouble.
+In general, I advise against using any type of GUI with Git. For one thing, Git is fairly easy to manage from the command line, so using a GUI just adds a level of abstraction that you 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 in trouble.
 
 Finally, a GUI can also obscure what Git is actually doing, meaning that you might end up with less understanding of Git than you would develop by working on the command line.
 
@@ -249,7 +249,7 @@ Finally, a GUI can also obscure what Git is actually doing, meaning that you mig
 
 That said, this document assumes that you are familiar with working on the command line in whatever OS you are accustomed to. You do not have to be an expert with it (that comes with time) but you should know how to open a terminal window, enter commands, and interpret whatever feedback you get. 
 
-I work in Linux, so the commands and system responses you see here are from that environment, as are the various paths you will see. If you work in Windows or maxOSX, you will need to adjust paths accordingly.
+I work in Linux, so the commands and system responses you see here are from that environment, as are any file paths you will see. If you work in Windows or maxOSX, you will need to adjust parameters accordingly.
 
 \chapter{Local Repositories}
 
@@ -261,7 +261,7 @@ What has happened is that Git has created an invisible directory (\texttt{.git})
 
 Technically, the \texttt{.git} directory is the actual repository. You will often hear people refer to the folder that contains your working files along with the \texttt{.git} directory as a repo. It's best to think of the directory with your working files as your ``working directory'' and the \texttt{.git} directory as the repository. (Be aware that not everybody makes this distinction, though.)
 
-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: 
+What we are lacking at this point is a basic time unit, because we haven't made any commits yet. All we have are files in our working directory. To make a commit that tracks what our project looks like here right here right now, we need to \textit{stage} our files by using the \texttt{git add} command. You can do this a couple of different ways: 
 
 \begin{itemize}
 \item We can list each file one by one (i.e., \texttt{git add file1.txt file2.txt}).
@@ -301,28 +301,32 @@ Untracked files:
 	file3.txt
 \end{Verbatim}
 
-The first two lines indicate that so far, nobody has made changes to your remote repository (if you have one). This is typical if you are the only person working on this project, but you may see something different if other people have pushed changes to the remote. We'll talk about this later. 
+The first two lines indicate that so far, nobody has made changes to your remote repository if you have one (see the next chapter for more details). This is typical if you are the only person working on this project, but you may see something different if other people have pushed changes to the remote. We'll talk about this later. 
 
-It then shows files that you have stages under the ``Changes to be comitted:'' list. Notice that if you have committed a file accidentally (which can happen if you are using wildcards), Git is nice and provide the command you need to reverse that change.
+It then shows files that you have staged under the ``Changes to be comitted:'' list. Notice that if you have committed a file accidentally (which can happen if you are using wildcards), Git is nice and provide the command you need to reverse that change (\texttt{git restore}).
 
 Finally, it shows you \textit{untracked} files. In other words, these are files that have been created or edited since the last commit, but have not yet been added to a new commit.
 
+Do you \textit{want} to track those untracked files? If you do, go ahead and add them using the \texttt{git add} command. If not, add them to the \texttt{.gitignore} file.
+
 \section{Ignoring Certain Files}
 
-Suppose that you have files in your repository that you \textit{don't} want Git to keep track of. Perhaps they are just notes to yourself that you will later delete, or some test files will not be a permanent part of this project. In such a case, we can use an ignore file to tell Git to not worry about those files. 
+Suppose that you have files in your repository that you \textit{don't} want Git to keep track of. Perhaps they are just notes to yourself that you will later delete, or some test files will not be a permanent part of this project. In such a case, you can use an ignore file to tell Git to not worry about those files. 
 
-The ignore file is an invisible file named \texttt{.gitignore} in your working directory. It's invisible, so it has to start with a period.
+The ignore file is an invisible file named \texttt{.gitignore} in your working directory. (Invisible files and directories always start with a period.)
 
 You can list individual files, or you can use wildcards to match multiple files. For example:
 
 \begin{itemize}[noitemsep]
-\item An asterisk (\texttt{*}) will match any number of characters except a forward slash. Using \texttt{*.ps} will cause Git to ignore any files that have a \texttt{.ps} extension.
-\item A question mark (\texttt{?} will match a single character except a forward slash. Using \texttt{fo?.txt} will cause Git to ignore both \texttt{foa.txt} and \texttt{fob.txt}, but not \texttt{fogg.txt}.
+\item An asterisk (\texttt{*}) will match any number of characters except a forward slash. Using \texttt{*.ps} will cause Git to ignore any files that have a \texttt{.ps} extension in the current directory.
+\item A question mark (\texttt{?} will match a single character except a forward slash. Using \texttt{fo?.txt} will cause Git to ignore both \texttt{foa.txt} and \texttt{fob.txt}, but not \texttt{fogg.txt} in the current directory.
 \item A forward slash (\texttt{/}) serves as a directory separator. Using \texttt{foo/} will cause Git to ignore all the files in the \texttt{foo} directory.
-\item Blank lines don't match anything, so you can use them as separators for visibility.
+\item Blank lines don't match anything, so you can use them as separators for readability.
 \item Any line starting with a \texttt{\#} is a comment, so you can remind yourself of why you are ignoring something.
 \end{itemize}
 
+Keep in mind that your Git installation may be configured differently than the general guidelines above, so it's always best to test out your \texttt{.gitignore} file by running \texttt{git status} first.
+
 \section{Committing Staged Files}
 
 Now that you've added your files, they are considered to be \textit{staged}, which means that they are ready to commit. You can make a commit now, or you can modify or create new files, and then add them as well. The choice is yours—Git doesn't penalize you either way. Personally, I prefer to make many smaller commits to avoid losing data (and metadata).
@@ -336,11 +340,11 @@ Remote repositories make it possible to share your work and to collaborate with
 
 \section{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:
+If you set up a remote repo a 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''.} 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.
+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''.} you would just type \texttt{git clone https://github.com/chrislgarry/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:
 
@@ -349,7 +353,7 @@ origin	https://github.com/chrislgarry/Apollo-11 (fetch)
 origin	https://github.com/chrislgarry/Apollo-11 (push)
 \end{Verbatim}
 
-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 Codeberg at \kref{https://codeberg.org/kjodle/Apollo-11}{https://codeberg.org/kjodle/Apollo-11}. To add that remote to my local repo, I will use 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've created one on Codeberg at \kref{https://codeberg.org/kjodle/Apollo-11}{https://codeberg.org/kjodle/Apol\\lo-11}. To add that remote to my local repo, I will use this:
 
 \input{include/remoteadd}
 
@@ -416,8 +420,6 @@ If you visit that original repository that I cloned on GitHub, you'll see that i
 
 As we can see from this example, 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}.
 
-\todo[inline]{Add information about changes to remote repos by other people (See "git status" in "local repositories".}
-
 If you are working on a project that others are also working on, running \texttt{git status} may show you something like this:
 
 \begin{Verbatim}[frame=lines, numbers=left, xleftmargin=5mm, framesep=3mm, breaklines=true, label=\fbox{Atypical Output from git status}]
@@ -426,6 +428,8 @@ Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
   (use "git pull" to update your local branch)
 \end{Verbatim}
 
+If you are collaborating with other people on a project, you may see different messages here. Others working on the project may have made changes that will conflict with your changes and could be difficult or impossible to reconcile. Always communicate with other project owners and use branching to prevent this.
+
 
 
 \chapter{Branches}
@@ -498,7 +502,7 @@ What does \texttt{git pull} do? It's a combination of two Git commands: \texttt{
 
 \chapter{Next Steps}
 
-\section{Additional Files}
+\section{README.md}
 
 If you pull or clone a remote repository, you may notice files like \texttt{.gitignore} and \texttt{README.md}. The first tells Git which files to \textit{not} track. (And yes, you will want to make use of this at some point.) The second is a text document written in Markdown (hence the \texttt{.md} file extension) which appears on the front page of the online repo.
 
@@ -530,23 +534,23 @@ One of my favorite aspects of Git is that it's fairly intuitive to understand an
 	row{1}     = {font=\bfseries},
 }
 Command & Purpose {\& Example, if applicable} \\
-\texttt{git init}	& {Creates a local git repository \\ \texttt{git init} } \\
-\texttt{git clone}	& {Clones a remote repository locally \\ \texttt{git clone} <URL of remote reposistory> } \\
 \texttt{git -{}-version}	& Displays the version of git installed on your system \\
 \texttt{git add}	& {Stages (i.e., adds) files to a commit \\ \texttt{git add file1 file2} } \\
-\texttt{git add *}	& Stages (i.e., adds) all visible files to a commit \\
 {\texttt{git add -A} \\ \texttt{git add --all}}	& Stages (i.e., adds) all files (including invisible ones) to a commit \\
+\texttt{git add *}	& Stages (i.e., adds) all visible files to a commit \\
 \texttt{git branch}	& Show all branches (the current branch is labeled with an asterisk) \\
 \texttt{git branch -{}-show-current}			& Show only the current branch \\
+\texttt{git clone}	& {Clones a remote repository locally \\ \texttt{git clone} <URL of remote reposistory> } \\
 \texttt{git commit}	& {Commits stages files \\ \texttt{git commit -m} ``<commit message>'' } \\
 \texttt{git fetch} & Get the change history of a specific tracked remote and branch \\
-\texttt{git log} & \\
+\texttt{git init}	& {Creates a local git repository \\ \texttt{git init} } \\
+\texttt{git log} & Show the commit logs. Will show a lot of information unless you include options to limit the number of logs displayed. \\
 \texttt{git merge} & Incorporate changes from the named commits into the current branch \\
 \texttt{git pull} & A combination of \texttt{fetch} and \texttt{merge} \\
 \texttt{git push}	& {Pushes a commit from a local repo to a remote repo \\ \texttt{git push} <name of remote repo> <name of remote branch> } \\
 \texttt{git remote}		& {Show only the names of remote repos  \\ \texttt{git remote} } \\
 \texttt{git remote -v}	& {Show both the names and URLs of remote repos  \\ \texttt{git remote -v} } \\
-\texttt{git rev-list} & \\
+\texttt{git rev-list} & List commit hashes in reverse chronological order. (This command is more useful if you specify options.) \\
 \texttt{git status}	& Show which files have been staged and which files are waiting to be staged \\
 \texttt{git status -s}	& As above, but in short form \\
 \texttt{git status -u}	& As above, but only show untracked files \\