kjodle/a-git-primer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Numerous updates and format changes; added inline todos

Browse Source
This commit is contained in:
Kenneth John Odle 2024-08-23 12:57:34 -04:00
parent 0e203b926e
commit 6eb5b6c52e
1 changed files with 46 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
git-primer.tex
View File

@ -1,4 +1,4 @@
\documentclass[twoside,11pt,anypage]{report}
\documentclass[twoside,anypage,draft]{report}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Packages %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@ -31,11 +31,16 @@
\usepackage[]{footmisc}
\usepackage{ninecolors}
\usepackage{setspace}
\usepackage[obeyDraft, textcolor=red2, bordercolor=red, backgroundcolor=white, textsize=small]{todonotes}
%\usepackage{showframe}
%\renewcommand*\ShowFrameColor{\color{red}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% To-do list %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Indices %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{imakeidx}
@ -55,7 +60,6 @@
\NumTabs{18} % Define 18 tab stops (at 1/4" intervals) [tabto package]
\raggedbottom % Don't force text to fill page
\setlength{\belowcaptionskip}{4pt} % Adjust space between caption and figure
\renewcommand*\contentsname{In This Issue…} % Change the name of the TOC
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@ -149,7 +153,7 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Document Information %%%%%%%%%%%%%%%%%%%%%
\author{Kenneth John Odle}
\author{Kenneth John Odle\\kenneth.odle@tutanota.com}
\title{
{\fontsize{36}{0}\selectfont A Git Primer}\\
{\fontsize{14}{0}\selectfont for Coders and Creatives}\\
@ -174,6 +178,10 @@ All contents \copyright\the\year{} Kenneth John Odle
\vspace{20mm}
\noindent{}This document is formatted to print well on both letter and A4 size paper. Printing on A4 paper will result in slightly wider top and bottom margins than you see in the digital document, and printing on letter-size paper will result in slightly wider left and right margins than you see in the digital document.
\vspace{20mm}
\noindent{}This document is typeset in \LaTeX{}.
\todo[inline]{Talk about some of the major packages: titlesec, verbatim, tabularray}
\tableofcontents
\thispagestyle{empty} % hide page numbers on TOC
@ -185,7 +193,7 @@ All contents \copyright\the\year{} Kenneth John Odle
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 easier for you.
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.
\section{What Git Can Do For You}
@ -193,6 +201,8 @@ Git is great if you are a software developer, because as you work you make a \te
Git works best with text-based files\index{files, text-based}—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 files, 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. Plain text files are your friends.)
\todo[inline]{Add stuff about "If you are a coder" and "If you are a creative".}
\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.
@ -213,33 +223,49 @@ 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.
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.
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.
\section{Assumptions}
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.
\chapter{Local Repositories}
Repositories are the basic space unit of Git. You can have as many of them as you want, both locally and remotely. Most people only have a single local repository, so let's start there.
Assuming you have a 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!
Assuming you have a folder full of files you want to track using Git, open a terminal window in that location 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!
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.
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: 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).
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:
\begin{itemize}
\item We can list each file one by one (i.e., \texttt{git add file1.txt file2.txt}).
\item We can use the \texttt{*} wildcard (i.e., \texttt{git add *}) which will \textit{not} add invisible files.
\item We can use the \texttt{-A} switch (i.e., \texttt{git add -A}) which \textit{will} add invisible files.
\end{itemize}
Before you stage files, though, it's a good idea to examine the status of your project. The command for that is \texttt{git status}.
\todo[inline]{Add information about git status.}
\todo[inline]{Add information about \texttt{.gitignore}.}
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).
If you're happy with the files you've staged, we can now commit them by using \texttt{git commit -m "<commit message>"}. Note that you 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}.
If you're happy with the files you've staged, we can now commit them by using \texttt{git commit -m "<commit message>"}. Note that you 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 committed.
\chapter{Branches}
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 using \texttt{git branch checkout <branchname>}.
If you want to experiment, the best way to do that is to create a \textit{branch}. There are two steps to this:
\begin{enumerate}
\item Create a branch using \texttt{git branch <name>}.
\item Move to that branch using \texttt{git branch checkout <branchname>}.
\end{enumerate}
Of course, there's a shortcut to this. You can use
@ -269,11 +295,13 @@ Let's go ahead and commit those using the following set of commands:
\input{include/branch001}
Notice that we don't have a remote repository at this point, so all we are doing is making commits.
\todo[inline]{Talk about git \texttt{diff here}.}
\chapter{Remote Repositories}
Remote repositories make it possible 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, or just to show off.
Remote repositories make it possible 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, or to just show off.
\section{Getting a Remote Repository}
@ -290,7 +318,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 my Git site 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'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:
\input{include/remoteadd}
@ -314,13 +342,13 @@ berg https://codeberg.org/kjodle/Apollo-11 (fetch)
berg https://codeberg.org/kjodle/Apollo-11 (push)
\end{Verbatim}
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:
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 named 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 I need to change that branch name by running
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 Codeber always names branches ``main''. So I need to change that branch name by running
\input{include/branchrename}
@ -332,11 +360,11 @@ Running \texttt{git branch} again confirms that our branch has been renamed:
\section{Pushing Changes to a Remote Repository}
Okay, I have a local repository, I have a remote repository attached to that local repository, and the current branch on both repos have the same name. It's time to move that code from the local repository to the remote one. For that I'll use \texttt{git push} <name of remote repo> <name of current branch>. Since the remote is named ``ogit'' and the branch is named ``main'', the full command looks like this:
Okay, I have a local repository, I have a remote repository attached to that local repository, and the current branch on both repos have the same name. It's time to move that code from the local repository to the remote one. For that I'll use \texttt{git push} <name of remote repo> <name of current branch>. Since the remote is named ``berg'' and the branch is named ``main'', the full command looks like this:
\input{include/push}
I did that, and Git thought for a moment, and produced this output:
Git thought for a moment, and produced this output:
\begin{Verbatim}[breaklines=true]
Enumerating objects: 3414, done.
@ -351,9 +379,9 @@ 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}.} of data. One of the nice things about Git is that it is remarkably fast.
That really did take only about a 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 unique features of 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''.
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}.