<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.01Starting}
\wikidoc{auth=mikerb@mit.edu}

\begin{labcover}
\labtitle{LabGit 01: Getting Started with Git}
\vspace{0.1in}
\labdate{Fall 2024}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Oscar Viquez, oviquezr@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 Ensure Git is Installed on Your Laptop
\item Download the MOOS-IvP Repository from GitHub Onto Your Laptop
\item Get Started with Command-line Git
\end{packed_itemize}
\end{labinfo}

\noindent
In this lab, the MOOS-IvP repository is the target initial repo to
obtain via git, mainly because it is the first required repo for the
MIT 2.680 course and other lab projects. Other than that, everything
else below applies generally even if some other repo besides MOOS-IvP
will be your initial repo to work with. For some readers, their entry
into git will be when they want to migrate a project, existing on a
local laptop not under version control, into Git. In this case,
starting with Lab 02 may be more appropriate.

%====================================================================
\section{Getting Started with Git on Your Laptop}
%====================================================================

Git is a version control software that allows users to develop source
code in a distributed manner, keeping track of changes, conflicts and
versions. You will be highly encouraged to use Git or a similarly
capable version control tool during the course. But for now, we focus
just on installing Git and knowing just enough to check out software
from the web to be used in the course.

%====================================================================
\subsection{How to tell if Git is Already Installed}

Your machine may already have a version of \cmd{git} installed. It is
typically preinstalled on macOS, and may be preinstalled in some Linux
distros as well. To check, try:

\vspace{0.15in}
\begin{consoleverb}
 $ which git
 /usr/bin/git   (or perhaps /bin/git on Linux)
\end{consoleverb}
\vspace{0.15in}

\noindent
If you get a response like the one above, you're all set. If \cmd{git}
is not installed you will get a response like the one below:

\vspace{0.15in}
\begin{consoleverb}
 $ which git
 git: command not found
\end{consoleverb}
\vspace{0.15in}

\noindent
Or no response at all:

\vspace{0.15in}
\begin{consoleverb}
 $ which git
 $ 
\end{consoleverb}
\vspace{0.15in}


\noindent
If the \cmd{which} command is telling you it cannot find
the \cmd{git} command, you probably just don't have \cmd{git}
installed. However it may be that you simply don't have the
directory containing the \cmd{git} executable in your shell path. To
rule this out, try the following (if using macOS, or GNU/Linux):

\vspace{0.15in}
\begin{consoleverb}
 $ cd /usr/bin
 $ which ./git
 ./git
\end{consoleverb}
\vspace{0.15in}

\noindent
To check if \cmd{git} is already installed via another method (i.e. MacPorts),
try:

\vspace{0.15in}
\begin{consoleverb}
 $ cd /opt/local/bin       (or /usr/local/bin)
 $ which ./git
 ./git
\end{consoleverb}
\vspace{0.15in}

\noindent 
If you see the above, it is simply a matter of adding directory
to your shell path. Do this now, or see the help topic on augmenting
your shell path:

\vspace{0.1in}
\noindent
\urlxx{http://oceanai.mit.edu/ivpman/help/help_cmd_shellpath}

%====================================================================
\subsection{Getting Git in GNU/Linux}

If you're running GNU/Linux you probably have access to a package
manager such as \cmd{apt} and already know how to use it to some
degree. To install packages like Git, you need root privileges.
Assuming your user account has root privileges, do the following,
and enter your normal login password if prompted:

\vspace{0.15in}
\begin{consoleverb}
 $ sudo apt install git
\end{consoleverb}
\vspace{0.15in}

\noindent
See the discussion above on how to confirm whether \cmd{git} has been
successfully installed, and adjust your shell path if need be.

%====================================================================
\subsection{Getting Git in macOS}

If you're running on a Mac (macOS) you can use MacPorts or Homebrew
to install Git. If you haven't installed either of these package managers,
see the separate help topic on this.  To install packages like Git,
you may need root (admin) privileges. Assuming your user account has the
necessary privileges, do the following, and enter your normal login password
when or if prompted:

\vspace{0.15in}
\begin{consoleverb}
 $ sudo brew install git (if using HomeBrew)
\end{consoleverb}
\vspace{0.15in}

\vspace{0.1in}
\noindent
Or if you are using MacPorts as a package manager:

\vspace{0.15in}
\begin{consoleverb}
 $ sudo port install git   (if using MacPorts)
\end{consoleverb}
\vspace{0.15in}

\noindent
See the discussion above on how to confirm whether \cmd{git} has been
successfully installed, and adjust your shell path if need be.

%====================================================================
\section{Using Git to clone an Existing Repository}
%====================================================================

The Git executable is \cmd{git} and takes a number of arguments
on the command line for interacting with a software repository. The
most essential is the command to \cmd{clone}, i.e., download, a
repository from a server.

\vspace{0.15in}
\begin{consoleverb}
 $ git clone &lt;url&gt; [&lt;destination&gt;]
\end{consoleverb}
\vspace{0.15in}

\noindent
In this section the \cmd{git clone} command will be used for obtaining
the MOOS-IvP repository. It is a publicly available repo, with no password
required, and is essential for classwork in MIT 2.680 and generally in
the MIT Marine Autonomy Lab. 

%====================================================================
\subsection{Cloning the MOOS-IvP Repository from GitHub}

The MOOS-IvP project is on GitHub and can be downloaded/cloned/pulled
onto your local machine, essentially as a read-only copy.
Below is the \cmd{git} command for checking out
the MOOS-IvP software repository:

\vspace{0.15in}
\begin{consoleverb}
 $ git clone https://github.com/moos-ivp/moos-ivp.git
  ...
 $ ls
 moos-ivp/ 
\end{consoleverb}
\vspace{0.15in}

\noindent
A clone essentially results in the download of a directory from a
server.  Once the directory/folder/tree is on your machine you can of
course modify anything in the tree on your machine, but you will not
be able to apply those changes to the GitHub version.

\vspace{0.1in}
\noindent
Note the [&lt;destination&gt;] part of the \cmd{git clone} command is optional. If
ommitted as above, the name of the folder will be the basename of URL, e.g.,
the \var{moos-ivp} part of \var{moos-ivp.git}.



o Build the tree

o Build the alpha mission

%====================================================================
\subsection{Build the MOOS-IvP Source Code and Run It}

Once the tree is downloaded, you should be able to build the code and
run the Alpha mission.

\begin{packed_enumerate}
\item Look inside the README file in the \var{moos-ivp} folder and follow
  the instructions for downloading/installing dependencies. They vary
  depending on whether you are on a Mac or Linux machine. 
\item Build the code.

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

\item Run the alpha mission
  
\vspace{0.1in}
\begin{consoleverb}
$ cd moos-ivp/ivp/missions/s1_alpha
$ ./launch.sh 10                        (10 is the time warp)
\end{consoleverb}
\vspace{0.1in}

\end{packed_enumerate}

\noindent
It should look something like: 

\vspace{0.1in}
\begin{figure}[H]
  \centering
  \includegraphics[width=0.75\textwidth]{figures/s1_alpha.png}
  \caption{A screen shot of the Alpha example mission shortly after launch.}
  \label{fig_s1_alpha}
  \gif{figures/s1_alpha.gif}
\end{figure}

%====================================================================
\subsection{Getting Info on a Repo's Origin}

After a repo has been cloned, you may find yourself later wanting to
remember where it was cloned from. You can try the following:

\vspace{0.1in}
\begin{consoleverb}
 $ cd ~/moos-ivp
 $ git remote show origin
 * remote origin
   Fetch URL: https://github.com/moos-ivp/moos-ivp.git
   Push  URL: https://github.com/moos-ivp/moos-ivp.git
   HEAD branch: main
   Remote branches:
     moos-ivp-22.8               tracked
     moos-ivp-22.8.1             tracked
     moos-ivp-24.8               tracked
   Local branch configured for 'git pull':
     main merges with remote main
   Local ref configured for 'git push':
     main pushes to main (up to date)
\end{consoleverb}

\vspace{0.1in}
\noindent
Here you can see the github URL \var{"https://github.com/moos-ivp/moos-ivp.git"}.
This can be used anywhere to clone the repo from github as shown
earlier:

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

%====================================================================
\subsection{Looking at Recent Commit Log}

Git has a history of commits and revisions, and it's all stored in the
\var{.git} folder in the top level of the repo. The log can be viewed
with the below command. In this case only the most two recent entries
are shown, due to the \var{-n 2} arguments. 

\vspace{0.15in}
\begin{consoleverb}
 $ cd ~/moos-ivp
 $ git log -n 2 --pretty=short
 commit ed377ae7d8ab8f2ec9ce5c77aded8df91a0f73fc (HEAD -&gt; main, origin/main, origin/HEAD)
 Author: Mike Benjamin &lt;mikerb@csail.mit.edu&gt;

    moved from sprintf to snprintf for utils in MBUtils

 commit b00b505ec7b533cce19b9bddf9eef48d99c2c763
 Author: Mike Benjamin &lt;mikerb@csail.mit.edu&gt;

    minor mods to LegRun OpReg and Waypoint bhvs
\end{consoleverb}
\vspace{0.15in}

\noindent
Notice the full hash of the most recent commit:

\vspace{0.1in}
\noindent
\var{ed377ae7d8ab8f2ec9ce5c77aded8df91a0f73fc}

%====================================================================
\subsection{Looking at Recent Commit Hash}

Each git commit has a unique hash value. A full has is 40
characters. The short vesion of the hash is first group of characters
of the full hash, typically nine characters. The hash of the most
recent commit can be obtained with: 

\vspace{0.15in}
\begin{consoleverb}
 $ git rev-parse HEAD
 ed377ae7d8ab8f2ec9ce5c77aded8df91a0f73fc
\end{consoleverb}
\vspace{0.15in}

\noindent
Or the just the short part of the hash:

\vspace{0.15in}
\begin{consoleverb}
 $ git rev-parse --short HEAD
 ed377ae7d
\end{consoleverb}
\vspace{0.15in}

%====================================================================
\section{Configure 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

Alternatively, you can remove the \var{--global} argument to set repo-specific
defaults; the default behavior is equivalent to setting the \var{--local}
argument explicitly. This is useful when you mange both personal and work
repositories, and you want to ensure the system employs the correct email
address for each case.

To check the local and global configurations, you can use the following
commands:

\vspace{0.1in}
\begin{consoleverb}
 $ git config --local --list     #(invoked within a checked out tree)
 $ git config --global --list    #(can be invoked anywhere; reads ~/.gitconfig)
\end{consoleverb}
\postverb

\noindent
More can be learned about Git online. There are numerous help
pages, cheat sheets, and the official Git book is even free online.
On this course website we do have a few help pages of our own you can
check out:

\vspace{0.05in}
\begin{packed_itemize}[2]
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_log_cmd}
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_update_cmd}
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_status_cmd}
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_add_remove_cmds}
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_mv_cmd}
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_commit_cmd}
\item \urlx{http://oceanai.mit.edu/ivpman/help/git_setup_your_own_repo}
\end{packed_itemize}


\end{document}

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