Updated Git section; added image

This commit is contained in:
Kenneth John Odle 2024-08-14 19:14:10 -04:00
parent 3e57d388ce
commit 1530f7fe45
2 changed files with 21 additions and 21 deletions

View File

@ -462,7 +462,7 @@ It's possible that the snap was configured wrong. It's also possible that I bork
\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. \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 Git. I am far from a power-user or expert in Git, so I may get some things wrong. This is definitely not intended to be at all comprehensive, but more just a way for you to get your feet wet. My goal is to encourage you to think about how you might benefit from using Git. What I'm going to do here is describe how I understand Git. I am far from a power-user or expert in Git, so I may get some things wrong. This is \textit{not} intended to be comprehensive, but more just a way for you to get your feet wet. My goal is to encourage you to think about how you might benefit from using Git.
\section{What Git Can Do For You} \section{What Git Can Do For You}
@ -472,7 +472,7 @@ Git works best with text-based files—basically, anything that has a \texttt{.t
\section{Git Concepts} \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, 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.
\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 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.
@ -482,9 +482,7 @@ If this is your first exposure to version control software you'll make faster pr
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. 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 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. \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—but more about that later.
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 dimension. 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 and living with the consequences.}
\section{Git Clients} \section{Git Clients}
@ -492,7 +490,7 @@ Git is a command line based technology. Yes, there are GUIs out there for Git, a
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 screwed. 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 screwed.
A GUI can also high what Git is actually doing, meaning that might end up with less understanding of Git than you would by working on the command line. A GUI can also obscure what Git is actually doing, meaning that might end up with less understanding of Git than you would by working on the command line.
\section{Local Repositories} \section{Local Repositories}
@ -504,23 +502,21 @@ Technically, the \texttt{.git} directory is the actual repository. But most peop
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: 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).
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 doesn't penalize you either way. Personally, I prefer to make many smaller commits to avoid losing data (and metadata). Now that you've added our 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 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'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}.\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.}
\section{Branches} \section{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\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 <branchname>}. 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 <branchname>}.
Of course, there's a shortcut to this. We can use Of course, there's a shortcut to this. You can use
\input{include/checkout} \input{include/checkout}
which creates a branch called ``branchname'' and moves us to it automatically. \noindent{}which creates a branch called ``branchname'' and moves us to it automatically.
This is the point where we experiment and have fun on this branch without worrying about our main branch. Wouldn't it be nice if life were like this?\footnote{Gosh, I've mentioned this twice. There are lots of science fiction stories about this possibility. I guess it's time to go read one. Or write one.} This is the point where you can experiment and have fun on this branch without worrying about messing up your main branch. Wouldn't it be nice if life were like this?\footnote{Gosh, I've mentioned this twice. There are lots of science fiction stories about this possibility. I guess it's time to go read one. Or write one.} If you like the changes that you made on this branch, you can then go back to your main branch (\texttt{git checkout main}) and \textit{merge} those changes.
If we like the changes that we made on this branch, we can then go back to our main branch (\texttt{git checkout main}) and \textit{merge} those changes.
\input{include/merge} \input{include/merge}
@ -560,7 +556,7 @@ origin https://github.com/chrislgarry/Apollo-11 (fetch)
origin https://github.com/chrislgarry/Apollo-11 (push) origin https://github.com/chrislgarry/Apollo-11 (push)
\end{Verbatim} \end{Verbatim}
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: I named my remote origin ``ogit'', which is the first letter of my last name combined with ``git''. I need to get rid of those remotes on GitHub, since I can't push any changes to them anyway. To do that I'll use this command:
\input{include/remoteremove} \input{include/remoteremove}
@ -577,7 +573,7 @@ Are we ready to upload this code from my local repository to my remote repo? Not
* master * master
\end{Verbatim} \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 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
\input{include/branchrename} \input{include/branchrename}
@ -589,11 +585,11 @@ Running \texttt{git branch} again confirms that our branch has been renamed:
\subsection{Pushing Changes to a Remote Repository} \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: 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 remote branch>. Since the remote is named ``ogit'' and the branch is named ``main'', the full command looks like this:
\input{include/push} \input{include/push}
Git thought for a moment, and produced this output: I did that, and Git thought for a moment, and produced this output:
\begin{Verbatim}[breaklines=true] \begin{Verbatim}[breaklines=true]
Enumerating objects: 3414, done. Enumerating objects: 3414, done.
@ -628,19 +624,23 @@ I mentioned earlier that you could use Git if you're a writer to keep track of c
The advantage to the workflow I'm describing here is that you can do 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. The advantage to the workflow I'm describing here is that you can do 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.
Physically go to your remote location (library, caf\'e, hospital waiting room, etc.) and login to your repository host. Make whatever changes you want online and save your files. I'll physically go to wherever we are for the day (library, caf\'e, hospital waiting room, etc.) and login to my repository host. I can edit files online using this button:
Go home and go into your local repo. Open a terminal in that directory and use the \texttt{git pull} command: \begin{center}
\noindent{}\frame{\includegraphics[scale=0.75]{gitea-online-edit}}
\end{center}
At the end of the day, I'll home and go into my local repo, open a terminal in that directory and use the \texttt{git pull} command:
\input{include/pull} \input{include/pull}
What does \texttt{git pull} do? It's a combination of two Git commands: \texttt{fetch} and \texttt{merge}. 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. Your local repository will now look like your remote repository. You can write to your heart's content, push those changes, and call it a day. If you're back at the hospital waiting room again some time later, you 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 your 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}.}
\section{Extra Files} \section{Extra 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} pay any attention to. (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. 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.
\section{Forks and Pull Requests} \section{Forks and Pull Requests}

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB