<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
% Include common packages, environments, counters etc
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_lab_format}
\input{common_latex/common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

\begin{document}
\wikidoc{file=Lab.ClassSkillsGit}
\wikidoc{auth=tpaine@mit.edu, mikerb@mit.edu}
\helplevelsubsec

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Lab 3A - Using Version Control with GitHub}
\vspace{0.1in}
\labcourse{2.680 Unmanned Marine Vehicle Autonomy, Sensing and Communications}
\vspace{0.25in}
\labpng{0.55}{figures/gitcover.png}
\vspace{0.25in}
\labdate{February 11th, 2025}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Tyler Paine, tpaine@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{footnotesize}
\end{labcover}

%===================================================================
% Add a blank page so first body page is on the right when doubleside
\blankpage

%===================================================================
\section{Overview and Objectives}
\label{sec_overview}
%===================================================================

This lab will help new users get ready to use version control, before
introducing MOOS in the upcoming labs. The goals of this lab are to
(a) create a user-owned copy of the {\em moos-ivp-extend} baseline
repository and (b) introduce {\em git} as a tool to track the user's
software development progress (also known as version control).

\vspace{0.1in}
\noindent
The \var{moos-ivp-extend} baseline repository is a folder with a common
structure for organizing and building the source code to be developed
in 2.680. By having a common structure across students, this allow
the 2.680 staff to pull student code into automated testing scripts. It
also makes it easier for TAs to help students by having a familiar
structure. 

%===================================================================
\subsection{Preliminaries}
\label{prelims}

This lab assumes you have a working MOOS-IvP tree checked out and
built on your computer.  You will also need to have \cmd{git}
installed. To verify this make sure that the following executable is
findable in your shell path:

\vspace{0.1in}
\begin{consoleverb}
 $ which git
 /usr/bin/git     (the typical location in MacOS)
 /bin/git         (the typical location in Linux)
\end{consoleverb}


\vspace{0.1in}
\noindent
You will need a Git hosting service in MIT 2.680. The recommended and
most common service is \var{github.com}. Please go to this website and
obtain an account. A soft suggestion: make things a bit easier if you
can by using your MIT email address and your MIT kerberos for a user
name when prompted.  If you have another Git hosting service you use
already, such as \var{gitlab.com}, feel free to continue using
that. We do not recommend using the MIT github service.  Presumably if
you use GitLab or similar, then you know how to map the below
instructions for GitHub into the similar steps in the hosting service
you currently used.

%=========================================================================
\section{Obtaining Your Own Version of the moos-ivp-extend Repo}
\label{sec_mie}
%=========================================================================

After signing up for a free \var{github.com} account, you can import a
copy of the 2.680 course baseline repository into your account by
following these steps:

%=========================================================================
\subsection{Create a New Repository by Importing an Existing Repository}

Once you are logged into your github.com account you should see a pull-down
menu option at the top of the page, similar to: 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.24\textwidth]{figures/import1.png}
\end{figure}
\vspace{0.1in}

\noindent
Select \var{Import repository}. This will bring you to a page where one of the
first steps is to enter the URL for the project to import. It should look
something like: 


\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.64\textwidth]{figures/import2.png}
\end{figure}
\vspace{0.1in}

\noindent
In this field enter: \var{https://github.com/pavlab-mit/moos-ivp-extend}. You can
ignore the next two fields: 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.64\textwidth]{figures/import3.png}
\end{figure}
\vspace{0.1in}

\noindent
Since the repository you are importing is public, you do not need to enter
a username or credentials information. Just leave this blank. The remaining
fields, shown below, do need to be filled in. In the example below, my MIT
kerberos name is \var{mikerb} and this is also my GitHub username. For the
name of your repository, we suggest you replace \var{"extend"} with your
MIT kerberos name, \var{moos-ivp-mikerb} in this example. 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.64\textwidth]{figures/import4.png}
\end{figure}
\vspace{0.1in}

\noindent
The URL \var{https://github.com/mikerb/moos-ivp-mikerb} is the goal for the name
of the newly created repo. In the dialog box at the bottom, select \var{Private}.
Then you are ready to hit the green button to \var{Begin Import}.

\vspace{0.1in}
\noindent
This may take a minute or two and you should see something like the below image
while the import request is being processed.

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.74\textwidth]{figures/import5.png}
\end{figure}
\vspace{0.1in}

\noindent
GitHub will send you an email when the import has completed.

%=========================================================================
\subsection{Finding your Newly Created Repository}

Once the repository is created, you can find it by using the pull-down
menu at the very uppermost rightmost corner of your GitHub page. It
may be a picture of you (if you uploaded one when you created your
account) or one of the auto-generated pixel art pieces auto-generated
by GitHub. In my case it looks like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.74\textwidth]{figures/import6.png}
\end{figure}
\vspace{0.1in}

\noindent
Click on the picture to get the pull-down menu, looking something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.35\textwidth]{figures/import7.png}
\end{figure}
\vspace{0.1in}

\noindent
Select the \var{Your repositories} option. This should bring you to your
account page where all (1 so far) repositories are listed. Using my name and repo
as an example, you should see something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.74\textwidth]{figures/import8.png}
\end{figure}
\vspace{0.1in}

%=========================================================================
\subsection{Provide TA Access (Adding a Collaborator)}

In the step, you are asked to provide access to your repository to the
2.680 staff. From the last step above, you should be in your GitHub account
page and see the newly created repository as a link that you can select.
Go ahead and select the link and this will take you to the repo main page,
looking something like:

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.74\textwidth]{figures/import9.png}
\end{figure}
\vspace{0.1in}

\noindent
In the upper right-hand corner, select the \var{Settings} pull-down menu, 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.74\textwidth]{figures/import10.png}
\end{figure}
\vspace{0.1in}

\noindent
This will open a new page with many options for modifying the settings
of your newly created repository. Lots to explore later here, but for
now, notice in the upper left corner, in the left-hand menu, there is
an item \var{Collaborators} in the \var{Access} section. Click the link
for collaborators.

\vspace{0.1in}
\noindent
Note: often when modifying important settings, GitHub may want to
confirm your identity before proceeding. It may prompt you at this
stage to confirm your identity, depending on how long it has been
since previously credentialing. Go ahead and confirm your identity
if needed. (this may be a good point to consider getting the GitHub
mobile app on your phone to facilitate credentialing with GitHub).
The next page should look something like: 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.99\textwidth]{figures/import11.png}
\end{figure}
\vspace{0.1in}

\noindent
Click on the green button that says \var{Add People}. In the dialog
box, enter \var{mikerb} and then select \var{mikerb} and the click the
green button to \var{Add mikerb}. Do the same for \pvar{painetyler}
(Tyler Paine) and \pvar{herocc} (Conlan Cesar).


\vspace{0.1in}
\noindent
The steps above will create an independent copy of the source
repository, preserving the history of the original project up to that
point. Unlike a fork (another method for creating a copy of a
project's repository), it will detach from the original repository
going forward. Forking a repository would enable you to make changes
and then submit upstream merge requests (pull requests, PRs, in
GitHub), for the consideration of the original project team.

%=========================================================================
\section{Cloning your New Repo onto Your Local Computer}
%=========================================================================

Once your new repository has been created in the \var{github.com} web
interface, you can view the code through the browser. To further
develop and modify your code, a copy must be made onto your local
computer, and then you will use the tools of \cmd{git} to keep the two
versions sychronized. Unlike tools like DrobBox, OneDrive, or other
cloud services, the synchronization does not happen
automatically. Only for the files you specify and upon your command,
will files be synchronized in either direction.

%=========================================================================
\subsection{Cloning Code onto Your Computer}

Recall in Section \ref{sec_mie} that you created your own private new
repository from the public \var{moos-ivp-extedn} repo. Because the latter
is public, it can be cloned onto your computer without being prompted for
credentials, with the following:

\vspace{0.1in}
\noindent
Not that you would want/need to do this, but you {\em could} get a
copy of the public \var{moos-ivp-extend} repo with the following:

\vspace{0.1in}
\begin{consoleverb}
$ git clone https://github.com/pavlab-mit/moos-ivp-extend.git
Cloning into 'moos-ivp-extend'...
remote: Enumerating objects: 44, done.
remote: Counting objects: 100% (44/44), done.
remote: Compressing objects: 100% (31/31), done.
remote: Total 44 (delta 10), reused 43 (delta 9), pack-reused 0 (from 0)
Receiving objects: 100% (44/44), 18.19 KiB | 3.03 MiB/s, done.
Resolving deltas: 100% (10/10), done.
$ cd moos-ivp-extend
$ ls
CMakeLists.txt  bin/            lib/            src/
README          build.sh*       missions/       trying123.txt
README.md       clean.sh*       scripts/
\end{consoleverb}
\vspace{0.1in}

\noindent
But if you tried to do this with a {\em private} repo like the one you
created for yourself in Section \ref{sec_mie}, you would prompted for
credentials.

\vspace{0.1in}
\noindent
To get a copy of your private repo onto your laptop, with the ability
to later push changes to GitHub, you will need to create and and
install an SSH key pair. One half of the pair remains on your machine,
and the other half is loaded onto GitHub. This is described next.

%=========================================================================
\subsection{Configuring an SSH Key Pair}

To set up credentialing with GitHub, to both access a private repo like the
one you just created, and to be able to push changes back to GitHub, we will
use SSH key pairs, as described below.

\vspace{0.1in}
\noindent
A key pair is created with a public and private half. The public half
is uploaded to GitHub, and the private half remains on your
computer. The private half normally has a pass-phrase, one of your choosing
when the key pair is generated.

\vspace{0.1in}
\noindent
Three steps are described here:

\begin{packed_itemize}
\item Generate an ssh-key pair
\item Put each half where the need to be (one local, one on GitHub)
\item Test that you can can clone your private repo onto your laptop.
\end{packed_itemize}

%-------------------------------------------------------------------------
\subsubsection{Create an SSH-Key Pair}

On both MacOS and Linux machines, there should already installed a command
called \cmd{ssh-keygen}. You can check:

\vspace{0.1in}
\begin{consoleverb}
  $ which ssh-keygen
  $ /usr/bin/ssh-keygen   (the typical location in MacOS)
  $ /bin/ssh-keygen       (the typical location in Linux)
\end{consoleverb}
\vspace{0.1in}

\noindent
To create a ssh-key pair:
\vspace{0.1in}

\begin{consoleverb}
 $ ssh-keygen -t ed25519 -C "janedoe@github"
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
This command will generate a key pair for you. When prompted for the file
where you want to save the key, press enter to accept the default. You can
also secure the use of your key by setting a password. The argument \var{-C}
above is just a comment, for the future when you may have multiple ssh-keys,
it helps you remember which one was for what.

\vspace{0.1in}
\begin{consoleverb}
 &gt; Generating public/private algorithm key pair.
 &gt; Enter a file in which to save the key (/Users/you/.ssh/id_ed25519): [Press enter]
 &gt; Enter passphrase (empty for no passphrase): [Type a passphrase]
 &gt; Enter same passphrase again: [Type passphrase again]
\end{consoleverb}
\postverb

\noindent
Note the existence of the folder \var{.ssh} in your home directory. As
a hidden folder remember you need to run \var{ls -a} to see it. At
this point you should have the two halves of the ssh-key pair in this
folder, in the files named:

\vspace{0.1in}
\begin{consoleverb}
  $ ls -a ~/.ssh
  id_ed25519   id_ed25519.pub
\end{consoleverb}
\vspace{0.1in}

\noindent
The one with the \var{.pub} suffix needs to be uploaded to \var{github.com}
in your account. This is described next. 

%-------------------------------------------------------------------------
\subsubsection{Uploading the Public SSK-Key in Your GitHub Account}

The next step is to add the public key to your GitHub account, so that
the server recognizes your local computer. If you are an existing
GitLab user, we presume you know how to do these steps already for
GitLab.

\vspace{0.1in}
\noindent
First, copy (as in "copy/paste") the public key:

\vspace{0.1in}
\begin{consoleverb}
 $ cat ~/.ssh/id_ed25519.pub
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
Note: on macOS, you can copy to the system clipboard from terminal using the
\cmd{pbcopy} utility:

\vspace{0.1in}
\begin{consoleverb}
 $ cat ~/.ssh/id_ed25519.pub | pbcopy
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
Please make sure you include the \*.pub suffix! Your private key will
have the same base name but no suffix, and should remain secret for
security reasons. Next, follow these instructions to add the key to
your GitHub account:

\begin{packed_itemize}
\item Sign in to GitHub.com
\item Click on your profile photo (upper right corner), then click
  Settings
\item On the sidebar, click on \var{"SSH and GPG keys}
\item Click \var{"New SSH key"} or \var{"Add SSH key"}
\item In the Title field, add a brief descriptionof which computer
  this is for (such as \var{"2.680 laptop"})
\item In the Key field, paste the contents of your public key file
\item Click \var{"Add SSH key"}
\end{packed_itemize}


% \item GitLab:
%  \begin{enumerate}
%    \item Sign in to GitLab.com
%    \item Click on your profile photo (upper right corner), then click Preferences
%    \item On the sidebar, click on ``SSH keys''
%    \item In the Key field, paste the contents of your public key file
%    \item In the Title field, add a brief description of which computer this is for (such as ``2.680 laptop'')
%    \item Click ``Add key''
%  \end{enumerate}
% \end{itemize}

%-------------------------------------------------------------------------
\subsubsection{Loading your Private Key}

The key can be added to your agent using the following command:

\begin{consoleverb}
 $ ssh-add -t 432000 ~/.ssh/id_ed25519 
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
The \var{-t 432000} part is optional. This specifies the amount of
time, in seconds (5 days in this example), before needing to add the
key again.

\vspace{0.1in}
\noindent
Once it is loaded you can confirm with: 

\vspace{0.1in}
\begin{consoleverb}
$ ssh-add -l          (-l for "list")
256 SHA256:wBe5h8kK7PZ8h7yPQ6+dRFLNDeCgiyK47U1Q+/nmdG1 janedoe@github (ED25519)
\end{consoleverb}
\vspace{0.1in}

\noindent
Note the \var{"janedoe@github"} part is whatever was specified with the \var{-C}
comment option when the ssh-key was created, as described earlier.

\vspace{0.1in}
\noindent
If for some reason you would like to un-load your ssh-key:

\vspace{0.1in}
\begin{consoleverb}
$ ssh-add -D          (-D for "Delete all Keys")
$ ssh-add -l          (note now there are none listed)
\end{consoleverb}
  
%--------------------------------------------------------------------------
\subsubsection{Pulling code from the server}

Once you've added your SSH key to your account, you can clone your
repository using the following commands:

\vspace{0.1in}
\begin{consoleverb}
 $ git clone git@github.com:&lt;user&gt;/moos-ivp-&lt;kerberos&gt;
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
This will clone a copy of your repository to your local machine. As
this is where you will be developing your new software, this is called
a working copy.

\vspace{0.1in}
\noindent
Git is designed to facilitate development across multi-member
teams. Even for single-member development, you may work from multiple
computers, such as a robot's computer and your own laptop.

\vspace{0.1in}
\noindent
Along with this lab, you will need to get familiar with how to make
local modifications and push those changes to GitHub. If new changes
have been pushed to GitHub that are not yet on your local machine,
you can pull these changes with:

\vspace{0.1in}
\begin{consoleverb}
 $ git pull
\end{consoleverb}


%===================================================================
\section{More Git: Configuring and Using Git}
\label{sec_more_git}


%======================================================================
\subsection{Configuring your Git environment}

When committing changes to a repository, Git creates an attribution record
so the author can be identified. You can tell Git what name and email
address you want associated with your commits by setting the global
defaults:

\vspace{0.1in}
\begin{consoleverb}
 $ git config --global user.email "your_email@example.com"
 $ git config --global user.name  "Your Name"
\end{consoleverb}
\postverb


%======================================================================   
\subsection{Saving your changes}

When you've changed files in your working copy and you want to save your
progress, you will need to execute the following sequence of commands:

\vspace{0.1in}
\begin{consoleverb}
 $ git add &lt;file(s) or path(s)&gt;
 $ git commit -m "a comment about what changed"
 $ git push
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
The first command, \cmd{git add}, will create a temporary, local checkpoint
of your changes. If you make additional modifications to the file before
calling \cmd{git commit}, you can revert to the checkpoint created by
\cmd{git add}. However, if you then call \cmd{git add} once again, the
checkpoint will be replaced to include the additional changes.

\vspace{0.1in}
\noindent
The second command, \cmd{git commit}, essentially confirms that you want this
checkpoint to become a permanent point in the version control history. The
comment is intended as a brief reminder of what changes were made, in case
you need to look back through the version history later on.

\vspace{0.1in}
\noindent
The checkpoint created by \cmd{git commit} will be only available on your
current workstation until you share it with the server, which you can do
with the third command in the series: \cmd{git push}.

\vspace{0.1in}
\noindent
To get started with Git, update the README.md file in your local copy
(located in the top directory) to indicate that this is your personal
repository. An update suggestion is to add a block at the top of the
file, listing your name and kerberos, along with an indication that
you are taking the class during Spring 2022.

\vspace{0.1in}
\noindent
Once you've modified the file locally using your preferred text editor,
commit and push your changes using the following sequence:

\vspace{0.1in}
\begin{consoleverb}
 $ git status            # (to see what files have changed in the repo)
 $ git add README.md
 $ git commit -m "updating README.md to reflect ownership by &lt;kerberos&gt; "
 $ git push
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
You should be able to verify the changes to the README.md file by going to your
repository's URL using a web browser.

\end{document}

</pre></body></html>