<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_packages}
\input{../common_latex_lab_format}
\input{../common_latex_definitions}
%===================================================================
\setcounter{tocdepth}{2}
%===================================================================

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

%===================================================================
% Build the Cover Page in an environment style easy for wiki parsing
\begin{labcover}
\labtitle{Using Version Control in MIT 2.680 with git}
\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 8th, 2022}
\vspace{0.1in}
\labauth{Oscar Viquez, oviquezr@mit.edu}
\labauth{Michael Benjamin, mikerb@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

%===================================================================
% Begin the body of the text
%===================================================================
\section{Overview and Objectives}
\label{sec_overview}
%===================================================================

This pre-lab will help new users get ready to use version control,
before introducing MOOS in the upcoming lab proper. The goals of this
lab are to (a) create a user-owned copy of the \var{moos-ivp-extend}
repository, (b) introduce the Continuous Integration and Continuous
Delivery (CI/CD) pipeline, (c) introduce \cmd{git} as a tool to track
the user's software development progress (also known as version control).

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Cloning the \var{moos-ivp-extend} repository
\item Running the CI/CD pipeline
\item Displaying the pipeline status badge
\end{packed_itemize}
\end{labinfo}


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

This lab assumes you have a working MOOS-IvP tree checked out and
built on your computer. To verify this make sure that the following
executables are built and findable in your shell path:

\vspace{0.1in}

\begin{consoleverb}
 $ which MOOSDB
 /Users/you/moos-ivp/bin/MOOSDB
 $ which pHelmIvP
 /Users/you/moos-ivp/bin/pHelmIvP
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
If unsuccessful with the above, return to the steps in Lab 1:

\vspace{0.1in}
\noindent
\urlxx{https://oceanai.mit.edu/ivpman/labs/machine_setup}{Lab.ClassSetup}

\vspace{0.1in}
\noindent
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
\end{consoleverb}
\postverb


%=========================================================================
\subsection{Cloning the \var{moos-ivp-extend} repository}

We plan on using \urlx{GitLab.com} for the class. After signing up for a free
account, you can import a copy of the course original repository into your
account by following these steps:

\vspace{0.1in}

\begin{itemize}
\item Login to \urlx{GitLab.com}
\item Navigate to Menu - Projects - Create New Project
\item Click on Import Project
\item Select Repo by URL, with the following information:

  \begin{itemize}
    \item Git repository URL: \var{https://gitlab.com/moos-ivp/moos-ivp-extend.git}
    \item Project name: MOOS IvP $&lt;$kerberos$&gt;$
    \item Visibility: choose private
    \item Create project
  \end{itemize}
\end{itemize}

\vspace{0.1in}
\noindent
Note that, if GitLab says it can't find a repo in the given URL, you must
make sure you have the .git suffix.

\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.

%=======================================================================
\subsection{Granting the teaching staff access to your repository}

After you have created your own copy of the \var{moos-ivp-extend}
repository, you will have to grant the teaching staff access to your
codebase. Later in the term, we will have lab assignments submitted
by committing your changes to the repo, followed by a notification
to us via email, with the appropriate commit ID.

\vspace{0.1in}
\noindent
To add a teaching staff user to your  project, follow these steps:

\begin{enumerate}
  \item Go to your project and select Project information $&gt;$ Members.
  \item On the Invite member tab, under GitLab member or Email
    address, type the username or email address.
  \item Select a role with source code access (Developer or Maintainer).
  \item Select Invite.
\end{enumerate}

\vspace{0.1in}
\noindent
Once you've completed this step, the teaching staff should receive an
email from GitLab with a notification about the invite. In the interest
of ensuring all was done correctly, however, we ask that students also
email the teaching staff with the URL to their repository. This will
let us catch issues with the configuration early on, to help you get it
all sorted out.

% %======================================================================
% \newpage
% \section{A survival guide to git}
% \label{sec_git_survival}
% %======================================================================

% As with emacs, there are a ton of resources on the web to teach yourself
% git; and you will more likely than not need to use a bit of your web/search
% savvy at some point to learn more. This help topic covers my own "survival
% git" tips to get you started with the most common tasks and scenarios.


%=========================================================================
\subsection{Configure SSH access on your account}

The previous assignment above had you create a copy of the original
\var{moos-ivp-extend} repository into your own account by using the
web interface. However, to start developing your own code, you'll need
to clone the repository to your workstation. There are two main ways
of doing this: using the HTTPS approach or the SSH approach. The
preferred method is the latter, for which you will first need to
establish a set of public-private keys for your workstation.

\vspace{0.1in}

\begin{consoleverb}
 $ ssh-keygen -t ed25519 -C "your_email@example.com"
\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.

\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_algorithm): [Press enter]
 &gt; Enter passphrase (empty for no passphrase): [Type a passphrase]
 &gt; Enter same passphrase again: [Type passphrase again]
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
On MacOS, you will need to modify your \~/.ssh/config file to automatically
load keys into the ssh-agent and store passphrases in your keychain.

\begin{consoleverb}
 $ emacs ~/.ssh/config
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
In the \~/.ssh/config file, add the following:

\begin{consoleverb}
 Host *
   AddKeysToAgent yes
   UseKeychain yes
   IdentityFile ~/.ssh/id_ed25519
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
Once you've created the key and configured your preferences to use the keychain,
you'll need to add the key to your ssh-agent. First, start the agent using the
following command:

\begin{consoleverb}
 $ eval "$(ssh-agent -s)"
 &gt; Agent pid 59566
\end{consoleverb}
\postverb

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

\begin{consoleverb}
 $ ssh-add -K ~/.ssh/id_ed25519  # on macOS (specifies the keychain option)
 $ ssh-add ~/.ssh/id_ed25519     # on Linux
\end{consoleverb}
\postverb

\vspace{0.1in}
\noindent
The next step is to add the public key to your GitHub or GitLab account, so that
the server recognizes your workstation. First, copy 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 GitLab account:


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

% \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 descriptionof which computer this is for (such as ``2.680 laptop'')
    \item Click ``Add key''
  \end{enumerate}
% \end{itemize}


%==========================================================================
\subsection{Pulling code from the server}

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

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

\vspace{0.1in}
\noindent
This will pull a copy of your repository to your workstation. 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). As such,
the second command you'll need is one to pull updates that have been
pushed to the server either by other team members, or by yourself but
from a different computer than you are using at the moment â€“ this
includes any changes you might have saved while editing files directly
on the website. You can do this with:

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



%======================================================================
\newpage
\section{Bonus: getting started with Git}
\label{sec_git_started}
%======================================================================

%======================================================================   
\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
create a temporary, local checkpoint of your changes
if you make additional modifications to the file before calling git commit,
you can revert to the checkpoint created by git add. However, if you then
call git add once again, the checkpoint will be replaced to include the
additional changes.

\vspace{0.1in}
\noindent
The second command, 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 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.

\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 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.


%=========================================================================
\subsection{Showing the CI pipeline badge}
First we need to create a regristration token which will allow the code 
in your repository to buid on a remote server.  
\vspace{0.1in}
\begin{itemize}
\item On the sidebar menu, navigate to Settings $&gt;$ CI/CD
\item Click Expand on the ``Runners'' section
\item First switch the toggle to ``off'' to disable sharing runners 
for this project.  The toggle is in the right column under ``Shared runners''.
\item Next, in the left column under ``Specific runners'', copy your
registration token and email to Oscar at oviquezr@mit.edu so he can add it
to the server.
\item Once your token is added, you should see a new runner available
appear at the bottom of the left column.  (You may need to refresh the page.)
\end{itemize}


By default, the project will launch a simple pipeline to test building your
code each new commit pushed to the server. Additional rules can be added to
limit when and how builds happen, or to define additional steps the server
should take. This should start running when you update your README.md file.
On GitLab.com, you can also launch the pipeline manually:

\vspace{0.1in}
\begin{itemize}
\item On the sidebar menu, navigate to CI/CD $&gt;$ Pipelines
\item Click on Run Pipeline
\item Select the branch you want to work from; the default is main
\item Click on Run Pipeline
\end{itemize}

\vspace{0.1in}
\noindent
When the pipeline fails, such as when a new source file has not been committed
and is thus not available on the server during the test build, the system will
produce an error and email you. GitLab will also display a marker next to the
latest commit hash, shown at the top of the content list, whenever a pipeline
is executed. An optional pipeline badge can also be displayed at the top of
the repository information.

\vspace{0.1in}
\noindent
On GitLab, the optional status badge can be added with the following steps:

\begin{itemize}
\item On the sidebar menu, navigate to your project site
        (i.e. https://gitlab.com/$&lt;$username$&gt;$/moos-ivp-$&lt;$username$&gt;$)
\item Go to Settings $&gt;$ General
\item Expand the Badges section
\item Enter the following information:
  \begin{itemize}
    \item Name: Pipeline Status
    \item Link: https://gitlab.com/\%\{project\_path\}/-/commits/\%\{default\_branch\}
    \item Badge image URL: https://gitlab.com/\%\{project\_path\}/badges/\%\{default\_branch\}/pipeline.svg
  \end{itemize}
\end{itemize}

You can see the badge in the original GitLab repo
(\urlx{https://gitlab.com/moos-ivp/moos-ivp-extend)}, right under the
number of commits to the project.

% On GitHub.com, the badge can be added by inserting the following pointer
% in a new line at the top of the README.md file:

% \begin{consoleverb}
% ![workflow name - alt-text](https://github.com/&lt;OWNER&gt;/&lt;REPOSITORY&gt;/actions/workflows/\
% &lt;WORKFLOW_FILE&gt;/badge.svg)
% \end{consoleverb}
% \postverb

% The pipelines are defined using instruction sets specific to the server
% solution in use.
% Additional customizations may be added in the following files:

% \begin{itemize}
% \item GitLab.com : .gitlab-ci.yml
% % \item GitHub.com : .github/workflows/build\_extend.yml
% \end{itemize}


\end{document}
</pre></body></html>