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

\begin{labcover}
\labtitle{LabGit 03: Sharing/Collaborating with Git}
\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 Share your private GitHub tree with others for viewing
\item Share your private GitHub tree with other contributors with push access 
\item Enable your GitHub tree to accept pull requests
\end{packed_itemize}
\end{labinfo}

\noindent
While having a purely private GitHub tree to yourself does have value, allowing
others to view, directly edit, or submit requests for changes will allow
for levels of collaboration when desired. For MIT 2.680 students, one of the
first steps will be to provide read access to your \var{moos-ivp-extend} tree
to the class TAs. This enables the TAs provide remote help, and for some labs,
to verify completed work.

%====================================================================
\section{Invite Others to Collaborate on a Private GitHub Repo}
%====================================================================

Inviting collaborators to a GitHub hosted repository is done through the
GitHub web interface. Navigate to your newly created \var{moos-ivp-extend},
e.g., \var{moos-ivp-stanlee} repo, and click the \var{settings} button:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/mie_settingsB.png}
  \caption{Edit the settings on your repository.}
\label{fig_mie-settings}
\end{figure}

\vspace{0.1in}
\noindent
Then select \var{"Collaborators}

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.85\textwidth]{figures/mie_collabB.png}
  \caption{Select Collaborators to add collaborators.}
\label{fig_mie-collaborators}
\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{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}


\vspace{0.1in}
\noindent
The two steps are:

\begin{packed_itemize} 
\item Create the essentially empty \var{moos-ivp-stanlee} repo on
  your GitHub account. 
\item Attach your local \var{moos-ivp-stanlee} repo to the one on
  GitHub.
\end{packed_itemize}



\end{document}

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