<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}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}
\wikidoc{file=LabGit.02Extend}
\wikidoc{auth=mikerb@mit.edu}

\begin{labcover}
\labtitle{LabGit 02: Creating Your Own Git Repo}
\vspace{0.1in}
\labdate{Fall 2024}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labline
\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}
%===================================================================

Goals for this lab:

\begin{labinfo}
%\labinfoheader{Topics:}
\begin{packed_itemize}[2]
\item Have your own GitHub Account (or similar)
\item Clone the moos-ivp-extend tree as your baseline code folder
\item Establish your own moos-ivp-user tree on GitHub (or similar)
\end{packed_itemize}
\end{labinfo}

\noindent
In this lab, if you have never used a Git hosting service like GitHub,
Gitlab or similar, you will be asked to establish a free account for
hosting your own tree using Git. You will be asked to convert a
software folder on your local laptop, not currently under Git version
control, to be under version control with Git using the service you
have chosen.

\vspace{0.1in}
\noindent
The particular folder you will establish under version control is the
\var{"moos-ivp-extend"} tree. This folder has a ready-made structure
for adding new MOOS apps and IvP behaviors, and MOOS-IvP missions.
It will be the starting point for MIT 2.680 student labs, and is a
good starting point for anyone wishing to extend MOOS-IvP with their
own code.

\vspace{0.1in}
\noindent
The last step, for students of MIT 2.680, will be to make the newly
created tree available to the MIT 2.680 TA staff. 


o Somewhere mention augmenting the shell path and IvPBehavior dir
o Run the Alder mission with a gif


%====================================================================
\section{Set Up Your GitHub Account}
%====================================================================

If you are already a user of GitHub, you can skip this section. If you
use another version control service such as Gitlab or the MIT GitHub,
may also skip ahead, but consider setting up a GitHub account anyway
if you don't have too much invested in whatever you may aleady be using.
In MIt 2.680 and in the Marine Autonomy Lab, members are steered to
GitHub. Working with the same toolset may make it easier to get help
and ultimately help others.

\vspace{0.1in}
\noindent
(Add bits later for walking a new user through the account setup)
%====================================================================
\section{Create Your New Git Repo}
%====================================================================

In this step we will make a Git repo from a specific folder, the
\var{moos-ivp-extend} folder. This folder is a starting template for
creating new MOOS apps, IvP Helm behaviors, and missions. It is nearly
empty to start with, but contains an example MOOS app, Helm behavior
and a mission. Starting with this folder it is easier to add new
components by following the examples.

\vspace{0.1in}
\noindent
In this section, the steps will be:

\begin{packed_itemize}
\item Obtain the \var{moos-ivp-extend} folder from GitHub.
\item Remove the Git meta data tying the folder from its origin.
\item Make a new repo on your GitHub account, for your own
  \var{moos-ivp-extend} folder.
\end{packed_itemize}


%====================================================================
\subsection{Getting the MOOS-IvP Extend Tree from GitHub}

The \var{moos-ivp-extend} folder/tree/repo is available from GitHub.
The first step is download/clone this tree onto your local machine.
The recommended location is to be in the same folder as your
\var{moos-ivp} tree, i.e., they should be side-by-side. To download:

\vspace{0.1in}
\begin{consoleverb}
 $ git clone https://github.com/pavlab-mit/moos-ivp-extend.git
\end{consoleverb}
\vspace{0.1in}

\noindent
The contents of the tree should look like:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-extend
 $ ls
 CMakeLists.txt  bin/            clean.sh*       scripts/
 README          build/          lib/            src/
 README.md       build.sh*       missions/
\end{consoleverb}
\vspace{0.1in}


%====================================================================
\subsection{Stripping the Git Info from the Local MOOS-IvP Extend Tree}

The \var{moos-ivp-extend} tree, immediately after downloading from Git,
is tied to the GitHub repo still. To verify this, try running:

\vspace{0.1in}
\begin{consoleverb}
$ git remote -v 
origin	https://github.com/pavlab-mit/moos-ivp-extend.git (fetch)
origin	https://github.com/pavlab-mit/moos-ivp-extend.git (push)
\end{consoleverb}
\vspace{0.1in}

\noindent
Note the URL above is the same URL you used for cloning the tree in
the previous step. This information is contained in a "hidden" folder,
\var{.git}. A hidden file and folder in Linux and MacOS is any file or
folder that begins with a \var{"."}. To see hidden files, try running
\cmd{ls} with the \cmd{-a} option:

\vspace{0.1in}
\begin{consoleverb}
./              CMakeLists.txt  bin/            clean.sh*       scripts/
../             README          build/          lib/            src/
.git/           README.md       build.sh*       missions/
\end{consoleverb}
\vspace{0.1in}

\noindent
Note the presence of the \var{.git/} folder. This is where all the Git
meta-data is contained. By simply removing this folder, the local
\cmd{moos-ivp-extend} tree will be detached from GitHub.

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp-extend
  $ rm -rf .git
\end{consoleverb}
\vspace{0.1in}

\noindent
You can confirm that the \var{moos-ivp-extend} folder has been detached:

\vspace{0.1in}
\begin{consoleverb}
$ git remote -v
fatal: not a git repository (or any of the parent directories): .git
\end{consoleverb}
\vspace{0.1in}

\noindent
At this point, your \var{moos-ivp-extend} folder is just a "regular"
folder on your hard drive. 

%====================================================================
\subsection{Preparing a Tree to Become a Repo}

To distinguish your tree from the baseline \var{moos-ivp-extend} tree,
rename the tree. For MIT 2.680 users, we strongly suggest using your
MIT Kerberos name. For example if you are \var{stanlee@mit.edu}, then
the suggested name for your \var{moos-ivp-extend} tree is
\var{moos-ivp-stanlee}. 

\vspace{0.15in}
\begin{consoleverb}
 $ mv moos-ivp-extend moos-ivp-stanlee
\end{consoleverb}
\vspace{0.15in}

\noindent
Now that the tree/folder is fully yours, the goal is to put it under
Git version control again, but this time using your own GitHub account.
The first step is to initialize Git within your folder:

\vspace{0.15in}
\begin{consoleverb}
 $ cd moos-ivp-stanlee
 $ git init
\end{consoleverb}
\vspace{0.15in}

\noindent
The above step essentially re-creates your hidden \var{.git}
folder. (You can run "ls -a" again to verify.) We can now run the
\cmd{git status} command to see how things look:

\vspace{0.15in}
\begin{consoleverb}
$ cd moos-ivp-stanlee
$ git status
On branch main

No commits yet

Untracked files:
  (use "git add &lt;file&gt;..." to include in what will be committed)
	CMakeLists.txt
	README
	README.md
	build.sh
	clean.sh
	missions/
	scripts/
	src/

nothing added to commit but untracked files present (use "git add" to track)
\end{consoleverb}
\vspace{0.15in}

\noindent 
At this point, the \var{moos-ivp-stanlee} tree is Git-enabled, but no
files have been explicitly added or identified to be under Git control.
We can add and commit all files with:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-stanlee
 $ git add * 
 ...
 $ git commit -m "initial message" *         (a message is mandatory)
 ...
 $ git status
 On branch main
 nothing to commit, working tree clean
\end{consoleverb}
\vspace{0.1in}

\noindent
At this point the \var{moos-ivp-stanlee} tree is legitimate Git repo,
fully capable of many of the version control features such as adding,
committing files, creating branches and reverting to older versions if
desired. However, the entire history is solely on your machine. If
your machine is lost, you lose everything. It is also hard to share
your code with collaborators. The next step is to upload your repo
to GitHub to address these issues. 

%====================================================================
\subsection{Preparing Your Repo on GitHub}

The goal of this section is to attach your newly created
\var{moos-ivp-stanlee} repo, local on your laptop, to a GitHub repo.
As discussed above, this will (a) create a durable backup to your
tree in case you lose your laptop, and (b) allow others to access your
code through GitHub. (This will also allow you to get your code onto
a robotic platform at some point.)

\vspace{0.1in}
\noindent
Log on to your GitHub page, and navigate to the "repositories" page,
look for the button to create a new repository:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/new_repo_button.png}
  \caption{{\bf Create a new repository:} Navigate to the window
    with this view and click on the green button.}
\label{fig_new_repo_button}
\end{figure}

\vspace{0.1in}
\noindent
In the top part of the page, select the options as shown in the Figure
\ref{fig_new_repo_stanlee} below. (a) select \var{No Template}, (b) select
the repo name equivalent to \var{moos-ivp-stanlee}, (c) Add a short description
similar to as shown, and (d) make this a Private repo for now. 

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.65\textwidth]{figures/new_repo_stanleeB.png}
  \caption{{\bf Configuring a new repository:} Select the options as shown
    or similar for your repo name.}
\label{fig_new_repo_stanlee}
\end{figure}

\vspace{0.1in}
\noindent
In the bottom part of the page, select the options as shown in the
Figure \ref{fig_new_repo_stanlee2} below. (a) the button to add a
\var{README} file, (b) For the \var{Add .gitignore} pull-down menu,
select the \var{.gitignore template: C++}, (c) select the GNU General
Public License v3.0, and finally click the green \var{Create
  repository} button.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.65\textwidth]{figures/new_repo_stanlee2B.png}
  \caption{{\bf Configuring a new repository:} Select the options as shown
    or similar for your repo name. Then hit the Create button.}
\label{fig_new_repo_stanlee2}
\end{figure}

\vspace{0.1in}
\noindent
At this point you now have two versions of your \var{moos-ivp-stanlee} repo.
The nearly empty one just created on GitHub. And the first version,
based on \var{moos-ivp-extend}, you created previously on your laptop.
The next step is to attach the two. 

%====================================================================
\subsection{Attaching your Local Repo to the GitHub Repo}

To attach your locally created \var{moos-ivp-stanlee} repo to the one
on GitHub, return to the command-line on your laptop and do the
following:

\vspace{0.15in}
\begin{consoleverb}
 $ cd moos-ivp-stanlee
 $ git branch -M main
 $ git remote add origin git@github.com:stanlee/moos-ivp-stanlee.git
 $ git push --set-upstream origin main
 $ git push
\end{consoleverb}
\vspace{0.15in}

\vspace{0.1in}
\noindent
The above assumes (a) your user account on GitHub is also \var{stanlee}.
If instead it was something like \var{stanlee873}, then the above line
would be instead: 

\vspace{0.15in}
\begin{consoleverb}
 $ git remote add origin git@github.com:stanlee873/moos-ivp-stanlee.git
\end{consoleverb}
\vspace{0.15in}

\vspace{0.1in}
\noindent
It also assumes that you have installed an ssh-key or other form of
credentialing on GitHub. Remember that the credentialing for pushing
content on GitHub is different than the user login password you may
use to log onto your GitHub page.

\vspace{0.15in}
\begin{consoleverb}
$ git remote -v 
origin	https://github.com/stanlee/moos-ivp-stanlee.git (fetch)
origin	https://github.com/stanlee/moos-ivp-stanlee.git (push)
\end{consoleverb}
\vspace{0.15in}

%====================================================================
\section{Build, Configure and Test your New Repo}
%====================================================================

Now that you have your own version of the \var{moos-ivp-extend} tree
on your laptop and under version control with Git, a few further steps
remain to ensure that things are ready to go:

\begin{packed_itemize}
\item Build the \var{moos-ivp-extend} tree
\item Modify the Bash shell path and IvP Helm behavior path
\item Confirm setup by running the \var{alder} mission.
\end{packed_itemize}

%====================================================================
\subsection{Build the New Repo}
%====================================================================

Build the new \var{moos-ivp-extend} repo, i.e., your \var{moos-ivp-stanlee}
folder. Note this assumes you have already downloaded and built the \var{moos-ivp}
folder alongside the \var{moos-ivp-extend} folder. In other words, these two
folders are in the same parent folder, typically the users home directory.
To build:

\vspace{0.1in}
\begin{consoleverb}
  $ cd moos-ivp-extend
  $ ./build.sh
\end{consoleverb}
\vspace{0.1in}

\noindent
You can confirm success by checking for the presence of the 


\end{document}

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