Tidied up links and footnotes

This commit is contained in:
Kenneth John Odle 2024-08-22 13:38:24 -04:00
parent 1ba4555a0d
commit caa596ed73

View File

@ -143,7 +143,7 @@
\title{
{\fontsize{36}{40}\selectfont A Git Primer}\\
\vspace{10mm}
{\fontsize{12}{16}\selectfont Typeset in \LaTeX{}}
{\fontsize{12}{16}\selectfont Typeset in \LaTeX{}}\\
\vspace{10mm}
{\fontsize{12}{16}\selectfont v. 0.1.0}
}
@ -183,7 +183,7 @@ If this is your first exposure to version control software you'll make faster pr
\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 or you can get an account at some place like Gitlab or GitHub, which are privately run for-profit companies, or at someplace like Codeberg,\footnote{\kref{https://codeberg.org/}{https://codeberg.org/}} which is run by a non-profit entity.
\paragraph{Concept Three: The basic space unit of Git is a \textit{repository}.} All those commmits have to exist 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 or you can get an account at some place like Gitlab or GitHub, which are privately run for-profit companies, or at someplace like Codeberg,\footnote{\kref{https://codeberg.org/}{https://codeberg.org/}} which is run by a non-profit entity.
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.
@ -195,7 +195,7 @@ Git is a command line based technology. Yes, there are GUIs (Graphical User Inte
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.
A GUI can also obscure what Git is actually doing, meaning that you might end up with less understanding of Git than you would by working on the command line.
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 by working on the command line.
\section{Assumptions}
@ -209,7 +209,7 @@ Assuming you have a folder full of files you want to track using Git, open a ter
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!
Technically, the \texttt{.git} directory is the actual repository. But most people think of the folder that contains your working files along with the \texttt{.git} directory as a repo. As far as I can tell, it doesn't really matter. Just be aware that a) this distinction exists, and b) some people on the internet can be incredibly pedantic about it (sometimes with reason, and often without).
Technically, the \texttt{.git} directory is the actual repository. But most people think of 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.
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 (i.e., \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 *} which will \textit{not} add invisible files, or \texttt{git add -A} which \textit{will} add invisible files).
@ -235,7 +235,7 @@ This is the point where you can experiment and have fun on this branch without w
It's always a good idea to clean up after ourselves. If we don't need that experimental branch any more, we can delete it with \texttt{git branch -d <branchname>}.
In reality, things are rarely going to be this simple, unless you are only making very basic changes to a branch. You'll possibly get all sorts of error messages or warning messages, and will get confused or even scared. The nice thing about Git is that most of the solutions you need are easily found at the other end of a web search.
In reality, things are rarely going to be this simple, unless you are only making very basic changes to a branch. You'll possibly get all sorts of error messages or warning messages, and will get confused or even scared. The nice thing about Git is that most of the solutions you need are easily found at the other end of a web search by looking up the error message you received.
\section{A Basic Branching Example}
@ -333,22 +333,21 @@ To https://codeberg.org/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 of the nice things about Git is that it is remarkably fast.
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}.} of data. One of the nice things about Git is that it is remarkably fast.
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://codeberg.org/kjodle/Apollo-11}{https://codeberg.org/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''.
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://codeberg.org/kjodle/Apollo-11}{https://codeberg.org/\\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}.
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}.
There is a lot more to it than this (I haven't even talked about \texttt{git status} yet!), so I guess I will leave that for part 2 of this primer.
\chapter{Collaborating With Yourself}
I mentioned earlier that you could use Git if you're a writer to keep track of changes to projects, provided you were willing to work with text files. My goal here is to provide at least one workflow for doing that. I'm going to assume a few things:
I mentioned earlier that you could use Git if you're a writer to keep track of changes to projects, provided you were willing to work with text files. My goal here is to provide a basic workflow for doing that. I'm going to assume a few things:
\begin{enumerate}[noitemsep]
\item You have a remote somewhere on a repository host (like GitHub or your own website).
\item You write all your stories in plain text files in a local repo.
\item Your repository host allows you to edit files on their website. (I can do this on my own site with Gitea\footnote{\kref{https://gitea.com/}{https://gitea.com/}} but I'm not sure about other sites.
\item Your repository host allows you to edit files on their website. (Codeberg uses Gitea\footnote{\kref{https://gitea.com/}{https://gitea.com/}} which allows this option, and other Git hosts have similar options.)
\end{enumerate}
The advantage to the workflow I'm describing here is that you can work on your files even if you are not working from your normal machine. Thanks to family medical issues, I sometimes spend a lot of time in hospital waiting rooms and I bring my Chromebook with me. I can edit my files on the web, and then pull down changes to my main laptop (which never leaves my house) when I get home. This is how I do it.
@ -365,11 +364,11 @@ At the end of the day, I'll home and go into my local repo, open a terminal in t
What does \texttt{git pull} do? It's a combination of two Git commands: \texttt{fetch} and \texttt{merge}.
\texttt{git fetch} gets the change history of the tracked remote and branch, whereas \texttt{git merge} combines the current branch with the specified branch. My local repository will now look like My remote repository. I can write to my heart's content, push those changes, and call it a day. If I'm back at the hospital waiting room again some time later, I can just repeat the process.\footnote{Again, for a visual depiction of this, please visit \kref{https://www.youtube.com/watch?v=FG1NrQYXjLU}{https://www.youtube.com/watch?v=\\FG1NrQYXjLU}.}
\texttt{git fetch} gets the change history of the tracked remote and branch, whereas \texttt{git merge} combines the current branch with the specified branch. My local repository will now look like My remote repository. I can write to my heart's content, push those changes, and call it a day. If I'm back at the hospital waiting room again some time later, I can just repeat the process.
\chapter{Other Things}
\chapter{Next Steps}
\section{Extra Files}
\section{Additional Files}
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.
@ -379,6 +378,8 @@ These things aren't a part of Git, but they are something that is offered by Git
To \textit{fork} a remote repository is to make a copy of it so that you can contribute to this project. You fork somebody else's project, clone it locally, make your changes, push those changes to your remote repo, and then make a \textit{pull request}, which alerts the owner of the original repository that you have changes you'd like them to incorporate into their project. They can then pull those changes in, or they can ignore them.
\section{bash Aliases}
\chapter{Summary of Git Commands}
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.
@ -419,10 +420,12 @@ Command & Purpose {\& Example, if applicable} \\
\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 \\
\texttt{git status -v} & Verbose output (default) \\
\end{longtblr}
\chapter*{Changelog}
\addcontentsline{toc}{chapter}{Changelog}
\begin{longtblr}
[