\subchapter{Git}{Objective: Get familiar with git by contributing to the Linux kernel}

After this lab, you will be able to:

\begin{itemize}
\item Clone a Git repository
\item Explore the history of a Git repository
\item Create a branch and use it to make improvements to the Linux kernel sources
\item Make your first contribution to the official Linux kernel sources
\item Rework and reorganize the commits done in your branch
\item Work with a remote tree 
\end{itemize}

\section{Setup}

Go to \code{/home/<user>/felabs/linux/git/}

This lab assumes that you already installed git software and cloned
the Linus Torvalds' git tree. See our {\em Kernel source code} lab for
details (\url{http://free-electrons.com/doc/training/linux-kernel/}).

\section{Configuring Git}

Configure your name and email address in git with \code{git config}.

\section{Clone a repository}

We already cloned Linus Torvalds' git tree, but it is useful to remember
how to do it again. Go to \url{http://git.kernel.org} and make sure you know
how to find the \code{git://} URL of his Linux tree.

Cloning downloaded quite a lot of data, but then at the end, we have
the full history of the Linux kernel (since the kernel developers
started to use Git, around kernel 2.6.12). We can access and explore
this history offline.

\section{Exploring the history}

With \code{git log}, look at the list of changes that have been made on the scheduler
(in \code{kernel/sched/}).

With \code{git log}, look at the list of changes and their associated
patches, that have been made on the ATMEL serial driver
(\code{drivers/tty/serial/atmel_serial.c}) between the versions 3.0
and 3.1 of the kernel.

With \code{git diff}, look at the differences between \code{fs/jffs2/}
(which contains the JFFS2 filesystem driver) in 3.0 and 3.1.

With \code{gitk}, look at the full history of the UBIFS filesystem (in
\code{fs/ubifs/}).

On the {\em gitweb} interface of Linus Torvalds tree, available at
\url{http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git},
search all commits that have been done by Free Electrons (hint: use
the search engine by author).

\section{Modify the Linux kernel sources}

Find something to modify in the Linux kernel sources. Here are ideas:

\begin{itemize}
\item Choose an ARM defconfig file, apply it, run \code{make} and fix compile warnings
\item Implement changes recommended in the Kernel Janitors page: \url{http://kernelnewbies.org/KernelJanitors/Todo}
\item Run the \code{scripts/check_patch.pl} command on a subdirectory of the Linux tree.
      You can do that with \url{http://free-electrons.com/labs/run-checkpatch}
\item Remove deprecated features. For example, \code{IRQF_DISABLED} no longer does anything,
      but is still in use in many drivers. Find drivers that use this symbol, and fix them.
\item Look for spelling mistakes in documentation, or classical mistakes like "the the", "a a"...
\end{itemize}

Before making changes, create a new branch and move into it.

Now, implement your changes, and commit them, following instructions 
in the slides for contributing to the Linux kernel.

\section{Share your changes}

Generate the patch series corresponding to your two changes using
\code{git format-patch}.

Then, to send your patches, you will need to use your own SMTP server, either your company's
if it is accessible from where you are, or the SMTP server available for a personal e-mail 
accounts (Google Mail for example, which has the advantage that your e-mail can be read
from anywhere). 

Configure git to tell it about your SMTP settings (user, password, port...).

Once this is done, send the patches to yourself using \code{git send-email}.

\section{Check your changes}

Before a final submission to the Linux kernel maintainers and community, you 
should run the below checks:

\begin{itemize}
\item Run \code{scripts/check_patch.pl} on each of your patches.
      Fix the errors and warnings that you get, and commit them.
\item Make sure that your modified code compiles with no warning,
      and if possible, that it also executes well.
\item Make sure that the commit titles and messages are appropriate
      (see our guidelines in the slides)
\end{itemize}

If you made any change, use \code{git rebase --interactive master} to
reorder, group, and edit your changes when needed. 

Don't hesitate to ask your instructor for help. The instructor will also 
be happy to have a final look at your changes before you send them for real.

\section{Send your patches to the community}

Find who to send the patches to, and send them for real.

Don't be afraid to do this. The Linux kernel already includes changes
performed during previous Free Electrons kernel sessions!

Unless you have done this before, you made your first contribution 
to the Linux kernel sources! We hope that our explanations and the power 
of git will incite you to make more contributions by yourself.

\section{Tracking another tree}

Say you want to work on the realtime Linux tree, so we'll add this
tree to the trees you're tracking:

\small
\begin{verbatim}
git remote add realtime \
  git://git.kernel.org/pub/scm/linux/kernel/git/rt/linux-stable-rt.git
\end{verbatim}
\normalsize

A \code{git fetch} will fetch the data for this tree. Of course, Git
will optimize the storage, and will no store everything that's common
between the two trees. This is the big advantage of having a single
local repository to track multiple remote trees, instead of having
multiple local repositories.

We can then switch to the master branch of the realtime tree:

\begin{verbatim}
git checkout realtime/master
\end{verbatim}

Or look at the difference between the scheduler code in the official
tree and in the realtime tree:

\begin{verbatim}
git diff master..realtime/master kernel/sched/
\end{verbatim}

