added cloning using git command line client

Author: thomasWeise

bookbase

@@ -37,7 +37,7 @@ \chapter*{Preface}%
 %
 This book contains a lot of examples.
 You can find all of them in the repository \url{\programmingWithPythonCodeRepo}.
-You can clone this repository and play with these example codes.%
+You can clone this repository as discussed in \cref{sec:gettingExamples,sec:gitClone} and play with these example codes.%
 %
 \begin{sloppypar}%
 The text of the book itself is also available in the repository \url{\programmingWithPythonRepo}.

text/front/preface/preface.tex

@@ -1,4 +1,5 @@
 \hsection{Getting the Examples from this Book}%
+\label{sec:gettingExamples}%
 %
 \begin{figure}%
 \centering%
@@ -57,7 +58,7 @@
 On the website, you can directly download all the examples as illustrated in \cref{fig:downloadExamples}.
 First, you would click on the little downward facing triangle in the button \menu{Code}.
 This will open a small dialog \menu{Clone} in which you can click on the \menu{Download ZIP} button.
-This, in turn, enters the URL~\expandafter\url{\programmingWithPythonCodeRepo/archive/refs/heads/main.zip} into your browser's download queue.
+This, in turn, enters the \pgls{URL}~\expandafter\url{\programmingWithPythonCodeRepo/archive/refs/heads/main.zip} into your browser's download queue.
 A \texttt{zip}~archive is a single file that can contain other files and folders and can be opened by the standard file managers both on \ubuntu\ and \windows.
 Once downloaded, the archive contains all the examples that we use in our book.%
 \end{sloppypar}%
@@ -75,7 +76,8 @@
 %
 Once the repository has been downloaded, \pycharm\ may ask you whether you trust this project.
 After making sure that you indeed downloaded the examples for this book (and if you deem this code trustworthy), you can click \menu{Trust Project}, as \cref{fig:clone04trustProject}.
-Finally, as \cref{fig:clone05finished} shows, you can now see and play with and run all the examples in \pycharm.%
+Finally, as \cref{fig:clone05finished} shows, you can now see and play with and run all the examples in \pycharm.
+A more comprehensive discussion on how to clone repositories is given in \cref{sec:gitClone}.%
 %
 \endhsection%
 %

text/main/basics/gettingStarted/examples/examples.tex

@@ -1263,7 +1263,7 @@
 
 As example, let us create a simple API that allows us to write output in a subset of the \acrfull{XML} format~\cite{BPSMM2008EMLX1FE,K2019ITXJY,CH2013XFCAMLTMC}.
 \pgls{xml} is a format for data interchange which was predominant in distributed systems the~2000s.
-After that, it began to fade out in favor~\cite{A2020XLATDOEOL} of \pgls{json}~\cite{E2017SE4TJDIS,B2017TJONJDIF} and \pgls{yaml}~\cite{DNMAASBE2021YAMLYV1,K2019ITXJY,CGTYB2022YFFDCAIE}.
+After that, it began to fade out in favor~\cite{A2020XLATDOEOL} of \pgls{json}~\cite{E2017SE4TJDIS,RFC8259} and \pgls{yaml}~\cite{DNMAASBE2021YAMLYV1,K2019ITXJY,CGTYB2022YFFDCAIE}.
 It is still very relevant today, for example, as foundation of several document formats such as those used in LibreOffice~\cite{DF2024LTDF,GL2012LTSOOSSCBAFACSOL} and Microsoft~Word~\cite{MS2024MW,DR2019STFAWAUMW}, or as the basis for the SVG graphics format~\cite{DDGLMSWFJJ2011SVGSSE}.
 If you are a bit familiar with web design, then you will find that \pgls{xml} looks a bit like HTML~\cite{HBFLDNOP2014HAVAAAFHAX}.%
 %

text/main/classes/dunder/dunder.tex

@@ -537,7 +537,7 @@
 To do so, we call the built-in function~\pythonilIdx{open}.
 We pass in the filename~\textil{"example.txt"} as first parameter.
 The second parameter, \pythonil{mode}\pythonIdx{open!mode}, is set to~\pythonil{"w"}, which means \inQuotes{open for writing.}
-The parameter \pythonil{encoding}\pythonIdx{open!encoding} is set to~\pythonil{"UTF-8"}\pythonIdx{UTF-8}, which defines that the text should be translated to binary form when it is stored in the file via the usual \pgls{utf8}~encoding~\cite{Y2003UATFOI1,ISOIEC106462020ITUCCSU}.
+The parameter \pythonil{encoding}\pythonIdx{open!encoding} is set to~\pythonil{"UTF-8"}\pythonIdx{UTF-8}, which defines that the text should be translated to binary form when it is stored in the file via the usual \pgls{utf8}~encoding~\cite{RFC3629,ISOIEC106462020ITUCCSU}.
 This is of no importance here and we will discuss this eventually later in the book.
 
 Anyway, if opening the text file succeeds, we now have a variable~\pythonil{stream_out}, which is an instance of~\pythonilIdx{IO}.

text/main/controlFlow/exceptions/exceptions.tex

@@ -1,4 +1,5 @@
 \hsection{Cloning git Repositories}%
+\label{sec:gitClone}%
 %
 The most fundamental activity you will encounter is \emph{cloning} repositories.
 Under \git, this basically means to download the complete repository and its history to your machine.
@@ -12,5 +13,6 @@
 We here outline both approaches.%
 %
 \hinput{gitClonePycharm}{gitClonePycharm}%
+\hinput{gitCloneClient}{gitCloneClient}%
 %
 \endhsection%

text/main/ecosystem/git/gitClone/gitClone.tex

@@ -0,0 +1,98 @@
+\hsection{Cloning git Repositories with the git Client}%
+%
+\begin{figure}%
+\centering%
+%
+\subfloat[][%
+After opening the \ubuntu\ \linux\ \pgls{terminal} using \ubuntuTerminal, we enter the directory into which we want to download the repository. %
+We then type the command \bashil{git clone https://github.com/thomasWeise/databasesCode} and hit \keys{\enter}. %
+The option \bashil{--recurse-submodules} can be added just in case.%
+\label{fig:gitCloneClient1clone}%
+]{\includegraphics[width=0.78\linewidth]{\currentDir/gitCloneClient1clone}}%
+%
+\floatRowSep%
+%
+\subfloat[][%
+The process of cloning the repository begins.%
+\label{fig:gitCloneClient2cloning}%
+]{\includegraphics[width=0.78\linewidth]{\currentDir/gitCloneClient2cloning}}%
+%
+\floatRowSep%
+%
+\subfloat[][%
+Sometimes, there may be connectivity issues. %
+But do not fret if that happens\dots%
+\label{fig:gitCloneClient3error}%
+]{\includegraphics[width=0.78\linewidth]{\currentDir/gitCloneClient3error}}%
+%
+\floatRowSep%
+%
+\subfloat[][%
+{\dots}simply try again (and, if necessary, again and again). %
+Sometimes, it may make sense to switch the network, e.g., from using WLAN, instead connect your mobile phone to your computer using a USB cable and share the data connection of the mobile phone using USB tethering.%
+\label{fig:gitCloneClient4nextAttempt}%
+]{\includegraphics[width=0.78\linewidth]{\currentDir/gitCloneClient4nextAttempt}}%
+%
+\floatRowSep%
+%
+\subfloat[][%
+Eventually, it will work.%
+\label{fig:gitCloneClient5success}%
+]{\includegraphics[width=0.78\linewidth]{\currentDir/gitCloneClient5success}}%
+%
+\floatRowSep%
+%
+\subfloat[][%
+The repository has been downloaded and a new folder with the repository name (here:~\textil{databasesCode}) has appeared.%
+\label{fig:gitCloneClient6files}%
+]{\includegraphics[width=0.78\linewidth]{\currentDir/gitCloneClient6files}}%
+%
+\caption{Cloning a \git\ repository using the \git\ \pgls{client} application \bashil{git} in an \ubuntu\ \linux\ \pgls{terminal} and how to deal with connection errors.}%
+\label{fig:gitCloneClient}%
+%
+\end{figure}%
+%
+The most basic way to clone \git\ repositories is to use the \git\ \pgls{client} application.
+This is a command line tool that can be executed in a \pgls{terminal}.
+Here, we simply assume that you already have it installed the \git\ \pgls{client} program~\bashil{git}.
+
+In \cref{fig:gitCloneClient}, we illustrate how the \git\ \pgls{client} program is used under \ubuntu\ \linux.
+Under Microsoft \windows, it will work analogously.
+First, we need to open a \pgls{terminal} window.
+Under \ubuntu\ \linux, we therefore press \ubuntuTerminal.
+Under \windows, we instead \windowsTerminal.
+We then enter the directory into which we want to download the repository using~\bashil{cd}.
+Notice that if we download a repository with the name~\textil{abc}, this will create a new directory named~\textil{abc} inside that current working directory.
+
+We then type the command \bashil{git clone https://github.com/thomasWeise/databasesCode} and hit \keys{\enter}.
+Sometimes, repositories contain submodules.
+A submodules is basically a links to a specific state (commit) of \emph{another} repository.
+The files of the referenced commit of the other repository would then exist inside a directory of the repository that we want to clone.
+If we want to have a full copy of all the files, including the files referenced this way, we need to add the option \bashil{--recurse-submodules} to the \bashil{git} command.
+We do this in \cref{fig:gitCloneClient1clone} to be on the safe side for demonstration purpose (although the repository \textil{databasesCode} does \emph{not} have any submodule).
+
+After we hit \keys{\enter}, the process of cloning the repository begins in \cref{fig:gitCloneClient2cloning}.
+Sadly, when we clone repositories using \pgls{HTTPS} \pglspl{URL} from \github, sometimes, there may be connectivity issues.
+I noticed that using the \pgls{SSH} \pglspl{URL} is much more reliable.
+An example for such an error is shown in \cref{fig:gitCloneClient3error}.
+
+However, this is not a big problem.
+If such errors happen, you can simply try again after some time.
+I furthermore noticed that, often, changing your internet connection can solve the problem.
+Let's say that you are trying to clone the repository using your wired or wireless LAN and it does not work.
+Then it often helps to first switch of the network connection on your computer.
+On your mobile phone, you should also switch off wireless LAN and instead activate your mobile data connection.
+Then you can connect your mobile phone to your computer using a USB cable and select \emph{USB tethering} on your phone.
+This will share the mobile data connection with your computer.
+Then, simply try to clone the repository again, as shown in \cref{fig:gitCloneClient4nextAttempt}.
+The connection switching is just a quick work around.
+Often, \bashil{git clone} works at first attempt and, if not, works after you wait a minute or so.
+
+Eventually, it will work, as shown in \cref{fig:gitCloneClient5success}.
+After the \bashil{git} command completes, the repository has been downloaded and a new folder with the repository name (here:~\textil{databasesCode}) has appeared.
+The \bash\ command \bashil{ls} lists the files in a directory.
+We see that the new directory contains the downloaded files in \cref{fig:gitCloneClient6files}.
+Here, we will not deal with the issue of \pglspl{virtualEnvironment}, as we discussed them in the previous section about cloning repositories using \pycharm.%
+%
+\FloatBarrier%
+\endhsection%

text/main/ecosystem/git/gitClone/gitCloneClient/gitCloneClient.tex

@@ -14,14 +14,14 @@
 \floatRowSep%
 %
 \subfloat[][%
-We click on the button for copying the URL to the clipboard.%
+We click on the button for copying the \pgls{URL} to the clipboard.%
 \label{fig:gitClonePycharm02copyUrl}%
 ]{\tightbox{\includegraphics[width=0.48\linewidth]{\currentDir/gitClonePycharm02copyUrl}}}%
 %
 \floatSep%
 %
 \subfloat[][%
-Now the URL is copied to the clipboard and we can paste it wherever we like via~\keys{\ctrl+V}.%
+Now the \pgls{URL} is copied to the clipboard and we can paste it wherever we like via~\keys{\ctrl+V}.%
 \label{fig:gitClonePycharm03copiedUrl}%
 ]{\tightbox{\includegraphics[width=0.48\linewidth]{\currentDir/gitClonePycharm03copiedUrl}}}%
 %
@@ -55,8 +55,8 @@
 \floatSep%
 %
 \subfloat[][%
-Normally, we would write the URL of the repository that we want to clone into the \menu{URL:} field. %
-Here, we paste the repository URL that we copied from the \github\ page with \keys{\ctrl + V}. %
+Normally, we would write the \pgls{URL} of the repository that we want to clone into the \menu{URL:} field. %
+Here, we paste the repository \pgls{URL} that we copied from the \github\ page with \keys{\ctrl + V}. %
 We also enter a directory where the repository should be copied to into the \menu{Directory:} field. %
 Here, I simply selected a folder on my \linux\ temporary files partition (because I will delete the project once I am done with this example). %
 You would instead choose a more appropriate location. %
@@ -263,34 +263,38 @@
 
 As usual, we work through a topic based on an example.
 This time, our goal is to \emph{download and get to run code from a \github\ repository in \pycharm.}
-As example repository, we pick the companion code of our \citetitle{databases} book~\cite{databases} at \url{\databasesCodeRepo}.
+Matter of fact, we already exercised the whole process of cloning the \github\ repository in \pycharm\ with the examples of this book in \cref{sec:gettingExamples}.
+To complement the excursion from back then, we this time pick the companion code of our \citetitle{databases} book~\cite{databases} at \url{\databasesCodeRepo} as example.
+This repository comes with a file \textil{requirements.txt}, which allows us to present the workflow of cloning a \git\ repository with setting up a \pgls{virtualEnvironment} and installing required packages into one single example.
 
-In \cref{fig:gitClonePycharm01website}, we pretend that you came across this interesting repository on \github\ using your normal web browser
+Therefore, in \cref{fig:gitClonePycharm01website}, we pretend that you came across this interesting repository on \github\ using your normal web browser.
 If you visit \url{\databasesCodeRepo}, you can see the big drop down menu~\menu{Code}.
-If you click on it, it shows the HTTPS URL under which the project can be found in \cref{fig:gitClonePycharm02copyUrl}.
-If you work with \github, there are two ways to write a URL to a repository:%
+If you click on it, it shows the \pgls{HTTPS} \pgls{URL} under which the project can be found in \cref{fig:gitClonePycharm02copyUrl}.
+If you work with \github, there are two ways to write a \pgls{URL} to a repository:%
 %
 \begin{itemize}%
 %
-\item \url{https://github.com/user/repository} (or \url{https://github.com/user/repository.git}) use the HTTPS protocol to access the repository \textil{repository} of user \textil{user}. %
+\item \url{https://github.com/user/repository} (or \url{https://github.com/user/repository.git}) use \pgls{HTTPS} protocol to access the repository \textil{repository} of user \textil{user}. %
 This form is often and commonly used.%
 %
-\item \url{ssh://[email protected]/user/repository} (or \url{ssh://[email protected]/user/repository.git}) use SSH protocol to access the repository \textil{repository} of user \textil{user}. %
+\item \url{ssh://[email protected]/user/repository} (or \url{ssh://[email protected]/user/repository.git}) use \pgls{SSH} to access the repository \textil{repository} of user \textil{user}. %
 I find this form more reliable when working with \github\ from China.%
 %
 \end{itemize}%
 %
 Here, obviously, \textil{user} is \textil{thomasWeise}, which is my personal \github\ account, and \textil{repository} is \textil{databasesCode}.
-The URL that will be copied to the clipboard by clicking the button in \cref{fig:gitClonePycharm02copyUrl} is \url{https://github.com/thomasWeise/databasesCode.git}.
+The \pgls{URL} that will be copied to the clipboard by clicking the button in \cref{fig:gitClonePycharm02copyUrl} is \url{\databasesCodeRepo.git}.
+If you wanted to clone the repository with the example codes for this book instead, you would use \url{\programmingWithPythonCodeRepo.git}.
+
 It is important to understand, however, that creating projects by cloning \git\ repositories is by no means restricted to \github.
 As stated before, \git\ is a \pgls{client}-\pgls{server} application.
 You could work in an enterprise that runs its own \git\ \pgls{server}.
 You could work with other \git-based repository hosts like \pgls{gitee}.
-Regardless of what \git\ service you use, you could use the very same way to type in the corresponding repository URL and then clone the repository in the same way.
-Only the structure of the URLs may be different.
+Regardless of what \git\ service you use, you could use the very same way to type in the corresponding repository \pgls{URL} and then clone the repository in the same way.
+Only the structure of the \pglspl{URL} may be different.
 
-In \cref{fig:gitClonePycharm02copyUrl}, we click on the button for copying the URL to the clipboard.
-Now the URL is copied to the clipboard (\cref{fig:gitClonePycharm03copiedUrl}) and we can paste it wherever we like via~\keys{\ctrl+V}.
+In \cref{fig:gitClonePycharm02copyUrl}, we click on the button for copying the \pgls{URL} to the clipboard.
+Now the \pgls{URL} is copied to the clipboard (\cref{fig:gitClonePycharm03copiedUrl}) and we can paste it wherever we like via~\keys{\ctrl+V}.
 But where shall we paste it?
 
 We open \pycharm.
@@ -301,8 +305,8 @@
 In that case, we click through \menu{\pycharmMainMenu > File > Project from Version Control\dots}.
 
 Either way, the \inQuotes{Clone Repository} form appears in \cref{fig:gitClonePycharm05cloneRepositoryForm}.
-Normally, we would now write the URL of the repository that we want to clone into the \menu{URL:} field.
-Here, we paste the repository URL that we copied from the \github\ page with \keys{\ctrl + V}.
+Normally, we would now write the \pgls{URL} of the repository that we want to clone into the \menu{URL:} field.
+Here, we paste the repository \pgls{URL} that we copied from the \github\ page with \keys{\ctrl + V}.
 We also enter a directory where the repository should be copied to into the \menu{Directory:} field.
 This directory is where all the files will be downloaded to.
 You would normally select some appropriate place in your filesystem where you store your program codes.