path: root/application-devel/git/frm_git_basics.tex

% ----------------------------
\subsubsection{Git Basics}

% ----------------------------
\begin{frame}[fragile]{What is Git?}
\begin{itemize}
\item Version Control System (VCS)
\item Snapshot Store (no Diffs)
\item Fully Distributed
\item Full local History
\item Optimized for Non-linear Development
\item Measured Code Integrity (Merkle-Tree)
\end{itemize}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Components I}
\begin{itemize}
\item Working Tree
 \begin{itemize}
 \item All Files of a Snapshot
 \item Checkout of a Commit History (Branch, Tag, detached)
 \end{itemize}
\item Staging Area
 \begin{itemize}
 \item Preparation for Commit
 \item Workingtree -> Staging Area -> Commit
 \end{itemize}
\item Commit
 \begin{itemize}
 \item ID: Unique Identifier
 \item Changeset with Description
 \end{itemize}
\item Branch
 \begin{itemize}
 \item Local: Separate List of Commits
 \item Remote: Pointer to a Commit
 \end{itemize}
\end{itemize}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Components II}
\begin{itemize}
\item Tags
 \begin{itemize}
 \item Reference to a Commit ID
 \item annotated: with own description
 \end{itemize}
\item Objects
 \begin{itemize}
 \item Storage Containers
 \item Hashed Versions of Files
 \end{itemize}
\item HEAD
 \begin{itemize}
 \item Pointer to Top-Level Commit of Branch or Workingtree
 \end{itemize}
\item Stash
 \begin{itemize}
 \item Store for non-committed Changes
 \end{itemize}
\end{itemize}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Collaboration}
\begin{itemize}
\item Pull/Push Changes from/to other Repositories
\item between local User Repositories (file-system)
\item Web-server based Repositories (read-only)
\item User Access Control (e.g. with git or ssh)
\item Protocols
 \begin{itemize}
 \item \texttt{file://}
 \item \texttt{http://}
 \item \texttt{https://}
 \item \texttt{git://}
 \item \texttt{ssh://}
 \item etc.
 \end{itemize}
\end{itemize}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{File States in Workingtree}
\begin{figure}[h]
\centering
\includegraphics[width=8cm]{images/git_file_states.png}
\end{figure}
\end{frame}

% ----------------------------
\subsubsection{Best Practice}

% ----------------------------
\begin{frame}[fragile]{Best Practice}
\begin{itemize}
\item use Local Repositories (keep track also for small, local projects)
\item commit Functional Changes
\item Split Commits into separate, functional Entities
\item Separate Branch for Feature
\item Push frequently to Remote Repositories
\item Write significant Commit Messages
 \begin{itemize}
 \item Problem/Motivation
 \item Problem Context
 \item Fix/Feature Description
 \item use Commit ID to refer to other Commits
 \end{itemize}
\end{itemize}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Bad Commit Messages}
\begin{itemize}
\item Non-existing Commit Message
\item Mix Functional Changes
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Bad Example I}
\begin{scriptsize}
\begin{verbatim}
commit 009e0d048028f2265555aeb1575b495f0cb4da9c
Author: Holger Dengler <dengler@linutronix.de>
Date:   Mon Feb 26 13:00:00 2018 +0100

    fix
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\begin{beamerboxesrounded}[shadow=true]{Bad Example II}
\begin{scriptsize}
\begin{verbatim}
commit 8ca31a793d9805a12304f85ae0a063e4c7dac4b0
Author: root <root@build.local>
Date:   Fri Feb 23 16:00:00 2018 +0100

    Various fixes of this week, still work in progress. TGIF and
    have a nice weekend!

\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Better Commit Messages}
\begin{beamerboxesrounded}[shadow=true]{Bad Example}
\begin{scriptsize}
\begin{verbatim}
commit 03f5942e8d9ae7bad608a9bcda8067f2f40f7840 (HEAD -> master)
Author: Holger Dengler <dengler@linutronix.de>
Date:   Mon Feb 26 13:00:00 2018 +0100

    Initialize the XYZ Control Register with 0x15. This resolves the hang
    during boot on my device.
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\begin{beamerboxesrounded}[shadow=true]{Better Example}
\begin{scriptsize}
\begin{verbatim}
commit 7de69687544549cc2e077663a1e58f05b91d6990 (HEAD -> master)
Author: Holger Dengler <dengler@linutronix.de>
Date:   Mon Feb 26 13:00:00 2018 +0100

    imx: Initialize XYZ_CTRL during device probe

    After a warm reboot, the control register of the XYZ Component is not
    set to the correct reset values, as described in the Reference
    Manual. This causes non-deterministic race conditions during the probe
    of the device.

    Setting the control register to the power-on reset values triggers an
    internal reset of the component. The device can be probed in a proper
    way in all reboot cases (POR and warm reset).

    See: Reference Manual, Page 4711, XYZ Device Initialization and
    Control Register.

    Signed-off-by: Holger Dengler <dengler@linutronix.de>
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\subsubsection{Working with local Git Repositories}

% ----------------------------
\begin{frame}[fragile]{Create an empty Repository}
\begin{itemize}
\item Create a top-level Directory
\item Initialize the Repository Configuration and History
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Example: Create empty Repository}
\begin{scriptsize}
\begin{verbatim}
# Create top-level Directory of Repo
mkdir myrepo

# Initialize Repository
cd ./myrepo
git init

# opt.: Initialize Repository without Workingtree
git init --bare
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Git Configuration}
\begin{itemize}
\item System-wide Configuration (Scope of Distribution)
\item Global Configuration (Defaults for all Repositories of a User)
 \begin{itemize}
 \item Location: \texttt{\~{}/.gitconfig}
 \end{itemize}
\item Local Configuration (Repository-local)
 \begin{itemize}
 \item Location: \texttt{<repo-dir>/.git/config}
 \end{itemize}
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Example: Configure Git}
\begin{scriptsize}
\begin{verbatim}
# Set Name and E-Mails address of the User
git config --global --add user.name "Jo Developer"
git config --global --add user.email "devel@acme.com"
git config --global --add core.editor "pluma"

# Other E-Mail address for some Repositories
cd <repo-dir>
git config --local --add user.email "devel@private-mail.eu"
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Add/Change Files}
\begin{itemize}
\item Create (or edit) Files
\item Check Changes
\item Stage Changes
\item Commit Changes
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Example: Add File to Repository}
\begin{scriptsize}
\begin{verbatim}
# Add or Edit Files
echo "hello world" > myfile

# Check unstaged Changes
git status
git diff

# Stage Changes
git add myfile

# Check staged Changes
git status
git diff --cached

# Commit staged Changes (opens editor for the commit message)
git commit -s
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Cleanup}
\begin{itemize}
\item Clean untracked Files
\item Reset unstaged Changes (reset to Repository Version)
\item Remove Files from Stage Area (reset to unstaged State)
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Examples: Cleanup}
\begin{scriptsize}
\begin{verbatim}
# Delete untracked Files
git clean

# Rollback File Changes
git checkout -- path/to/file

# Remove File from Stage Area
git reset HEAD path/to/file
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Exclude Files from Version Tracking}
\begin{itemize}
\item List of ignored Files (~/.gitignore)
\item specific List for each Directory possible
\item allow Wildcards
\item Wildcard Exceptions starts with "!"
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Example: Ignore List}
\begin{scriptsize}
\begin{verbatim}
# Fill Ignore List
cat > .gitignore << EOF
.*
!.gitignore
*.o
*.exe
EOF

# Check Status
git status

# Commit intial Ignore List
git add .gitignore
gitcommit -s -m "Initial Repository Ignore List"
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Branches}
\begin{itemize}
\item Create new Branch from:
 \begin{itemize}
 \item Commit (ID)
 \item Tag
 \item existing Branch
 \end{itemize}
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Example: Branches}
\begin{scriptsize}
\begin{verbatim}
# Create a new Branch (no changes to Workingtree)
git branch <branch-name> [<commit/branch/tag>]

# Create a new Branch and checkout to Workingtree
git checkout -b <new-branch> [<commit/branch/tag>]
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\subsubsection{Working with Remote Git Repositories}

% ----------------------------
\begin{frame}[fragile]{Clone Repository}
\begin{itemize}
\item Clone a Remote Repository
\item Creates a local Clone (Copy) of another Repository (with complete
History)
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Example: Clone Repository}
\begin{scriptsize}
\begin{verbatim}
# Clone Linux Kernel Repository from Github
git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

# check content
cd linux
ls -l
git log

# Clone Linux Kernel Repository from Github without Workingtree
git clone --bare https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

# no Checkouts, but History is available
cd linux.git
ls -l
git log
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Add Remote Repositories}
\begin{itemize}
\item multiple Remotes possible
\item e.g.: Pull from Development- and push to Release-Repository
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Examples: Remote}
\begin{scriptsize}
\begin{verbatim}
# Check all Remotes (with URL)
git remote -v

# Add a new Remote
git remote add linus https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Synchronize/Get Changes from Remote}
\begin{itemize}
\item Fetch: update Repository History
\item Pull: update Repository and Workingtree
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Examples: Fetch/Pull}
\begin{scriptsize}
\begin{verbatim}
# update History from Maniline Repository
git fetch linus

# Update History of all Remote Repositories
git fetch --all

# Synchronize the local master Workingtree with master Branch
# of Remote "linus"
git checkout master
git pull linus master
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\begin{frame}[fragile]{Synchronize/Put Changes to Remote}
\begin{itemize}
\item Push Changes to another Repository
\item Requires Write-Access
\end{itemize}
\begin{beamerboxesrounded}[shadow=true]{Examples: Push}
\begin{scriptsize}
\begin{verbatim}
# Prepare the Push-Branch
git checkout -b release-v1.0 master

# Pull from Development Repository
git pull devel-repo prepare_master-v1.0

# Push Release Branch to Release Repository
# (creates new Branch in Remote Repository)
git push release-repo release-v1.0 master
\end{verbatim}
\end{scriptsize}
\end{beamerboxesrounded}
\end{frame}

% ----------------------------
\subsubsection*{References}

% ----------------------------
\begin{frame}[fragile]{References}
\begin{itemize}
\item Git Webpage (\url{https://git-scm.com/})
\item ProGit (\url{https://git-scm.com/book/en/v2})
\end{itemize}
\end{frame}