git_cheat_sheet.tex

\documentclass[12pt]{article}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{fullpage}
\usepackage{fancyhdr}
\usepackage{url}
\usepackage{color}
\usepackage{textcomp}
\usepackage{geometry}
\usepackage{courier}
\geometry{
  top=1.0in,            % <-- you want to adjust this
  inner=0.5in,
  outer=0.5in,
  bottom=1.0in,
  headheight=4ex,       % <-- and this
  headsep=3ex,          % <-- and this
}

\renewcommand{\familydefault}{\sfdefault}

\addtolength{\parskip}{\baselineskip}  
\pdfpagewidth 8.5in
\pdfpageheight 11in
\pagestyle{fancy}
\newcommand{\urlwofont}[1]{\urlstyle{same}\url{#1}}

\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}
\lhead{\leftmark}
\chead{}
\rhead{\rightmark}
\lfoot{}
\cfoot{Page \thepage}
\rfoot{}
\hypersetup{
    colorlinks=false,
    linkcolor=blue,
    citecolor=black,
    filecolor=black,
    urlcolor=blue
}
\begin{document}
\section{git Introduction}
A Version Control System (VCS) manages the entire edit history of your code base (or ``repository''). It's helpful in a lot of ways: to go back to previous versions of your code, to revert bad changes, to make collaborating easier, to name a few.

git is a distributed VCS. git is nice because of its speed and its ability to efficiently handle merges and manage branches. We hope you share our opinions regarding this :)

\section{git commands}

\begin{enumerate}

\item{\texttt{help}}  
     \subitem{Show help for a git command.}
     \subitem{Example: \texttt{git help}; \texttt{git help push}; \texttt{git help help}}

\item{\texttt{init}}  
     \subitem{Create a new repo in the current folder.}
     \subitem{Example: \texttt{git init}}

\item{\texttt{clone}}
     \subitem{Copies the repository given, including all the commits and branches.}
     \subitem{Example: \texttt{git clone git@github.com:UP-MIT-GSL/angular-momentum.git}}

\item{\texttt{add}}
     \subitem{Add (``stage'') the changes for the next commit.}
     \subitem{Example: \texttt{git add edited/file.html}; \texttt{git add edited/folder/}}

\item{\texttt{status}}
     \subitem{Display status of your working tree (which files have changed, appeared, disappeared, etc.)}
     \subitem{Example: \texttt{git status}}

\item{\texttt{commit}}
     \subitem{Saves the staged changes (``commit'') to the current branch. See \texttt{git add} above and ``branches'' below.}
     \subitem{Usage: \texttt{-m} for adding a message to the commit, \texttt{-a} for adding all the modified files to the changes.}
     \subitem{Example: \texttt{git add index.html; git commit -m "added index.html"}}

\item{\texttt{merge}}
     \subitem{Combine your current branch with another branch.}
     \subitem{This command is intelligent; it will merge correctly automatically if there are no conflicts.}
     \subitem{e.g. in branch 1 line 256 of file A was changed, while in branch 2 line 512 of file A was changed. \texttt{git merge} detects no conflicts and merges the changes correctly.}
     \subitem{If there are conflicts, git will show in which files and lines the conflicts occurred. You need to manually resolve the conflicts and finish the merge commit yourself (see ``merge conflicts'' below).}
     \subitem{Usage: \texttt{git merge <branch\_to\_be\_merged\_with>}}
     \subitem{Example: \texttt{git checkout master; git merge fix-website-title}}

\item{\texttt{fetch}}
     \subitem{Get all commits/branches from a remote repository (see ``remotes'' below).}
     \subitem{Doesn't merge it yet with your branches.}
     \subitem{Usage: \texttt{--all} fetch from all remotes you are tracking.}
     \subitem{Example: \texttt{git fetch origin}; \texttt{git fetch --all}}

\item{\texttt{pull}}
     \subitem{A \texttt{fetch} followed by a \texttt{merge} (essentially).}
     \subitem{Usage: \texttt{git pull <repository> <branch>}}
     \subitem{Example: \texttt{git pull}; \texttt{git pull upstream master}}

\item{\texttt{rm}}
     \subitem{Remove files in the next commit.}
     \subitem{Usage: \texttt{-r} recursive}
     \subitem{Example: \texttt{git rm file/to/be/removed.html}; \texttt{git rm folder/to/be/removed/}}

\item{\texttt{push}}
     \subitem{Push all commits in the current branch to a remote branch (see ``remotes'' below.)}
     \subitem{Sometimes, when pushing, you may encounter errors. It's better to follow the rule of thumb: pull (or fetch+merge) first before push.}
     \subitem{Usage: \texttt{git push <repository> <branch>}}
     \subitem{Example: \texttt{git push}; \texttt{git push origin master}}

\item{\texttt{branch}}
     \subitem{Display all branches, create/delete a branch.}
     \subitem{Usage: \texttt{git branch} displays all branches, \texttt{git branch <branch\_name>} creates a new branch, \texttt{git branch -d <branch\_name>} deletes a branch (use \texttt{-D} to force delete)}
     \subitem{Example: \texttt{git branch}; \texttt{git branch new-branch}}

\item{\texttt{checkout}}
     \subitem{1. Go to a branch}
     \subitem{Usage: \texttt{git checkout <branch>}, \texttt{-b} to create new branch at the same time}
     \subitem{Example: \texttt{git checkout my-branch}; \texttt{git checkout -b new-branch}}
     \subitem{2. Undo changes to a file (sort of)}
     \subitem{Usage: \texttt{git checkout <file/folder>}}
     \subitem{Example: \texttt{git checkout file/with/bad/edits.html};}
     \subitem{\texttt{git checkout folder/with/bad/edits/}}

\item{\texttt{log}}
     \subitem{Display the last few commits in your branch/repository.}
     \subitem{Usage: \texttt{--all} to display all branches, \texttt{--graph} to display a (directed acyclic) graph of your commits, \texttt{oneline} to view each commit log in one line}
     \subitem{Example: \texttt{git log}; \texttt{git log --graph --oneline}}

\item{\texttt{diff}}
     \subitem{Compare two branches.}
     \subitem{Example: \texttt{git diff branch-1 branch-2}; \texttt{git diff head\textasciicircum1 head}}

\item{\texttt{blame}}
     \subitem{Display who created/edited each line of a file, and when (i.e. in which commit).}
     \subitem{Useful for tracking down which commit a line was created.}
     \subitem{Also useful for blaming other people for problems caused.}
     \subitem{Example: \texttt{git blame frontend/src/index.jade}}

\item{\texttt{remote}}
     \subitem{View remotes, add/modify/delete a remote (see ``remotes'' below).}
     \subitem{Usage:}
        \subsubitem{\texttt{git remote} - view remotes}
        \subsubitem{\texttt{git remote -v} - view remotes (verbose)}
        \subsubitem{\texttt{git remote add <remote-name> <url>} - add a new remote}
        \subsubitem{\texttt{git remote set-url <remote-name> <url>} - modify remote}
        \subsubitem{\texttt{git remote rename <remote-name> <new-name>} - rename remote}
        \subsubitem{\texttt{git remote rm <remote-name>} - remove remote}
     \subitem{Example: \texttt{git remote -v};}
     \subitem{\texttt{git remote add upstream git@github.com:UP-MIT-GSL/angular-momentum.git}}

\item{\texttt{stash}}
     \subitem{Save your current changes temporarily (in a Last-in-first-out stack).}
     \subitem{Useful if you want to switch to a branch temporarily, for example to read a file from a different branch.}
     \subitem{Usage: \texttt{git stash} to push current changes to the stack, \texttt{git stash pop} to revert saved changes}

\item{\texttt{reset}}
     \subitem{Reset changes and move to a specified branch.}
     \subitem{Usage: \texttt{--soft} move current branch to specified commit, but current changes are retained; \texttt{--hard} move current branch to specified commit and lose current changes.}
     \subitem{If commit is not specified, defaults to \texttt{HEAD}.}
     \subitem{Example: \texttt{git reset --hard} (resets all current changes); \texttt{git reset --soft a8baa8c9}}

\end{enumerate}

\section{git 101}

\subsection{Merge conflicts}
Probably the most important skill to master while using a version-control system (VCS) is to learn how to resolve merge conflicts properly.

Say you pulled changes from a repo with \texttt{git pull} or \texttt{git merge}. Usually it will either succeed silently, or ask you for a commit message for the merge, and . But the following message came up:

\texttt{Auto-merging myfile.html\\
CONFLICT (content): Merge conflict in myfile.html\\
Automatic merge failed; fix conflicts and then commit the result.\\
Auto-merging myfile2.html\\
CONFLICT (content): Merge conflict in myfile2.html\\
Automatic merge failed; fix conflicts and then commit the result.
}

This means a merge conflict occurred (you and someone else edited the same lines of the same file). You must resolve the conflict manually, by opening the files \texttt{myfile.html} and \texttt{myfile2.html}. You will see that git has marked the places where conflict occurred, and waits for a human to merge the changes correctly. Please be careful not to override the other's changes, and don't forget to remove the markers (\texttt{<<<<<<<}, \texttt{=======}, \texttt{>>>>>>>})!

After resolving, run \texttt{git status} to see if there are more conflicts. If all conflicts are resolved, complete the merge by running \texttt{git commit -a [-m "Merge message"]}.

\subsection{Branches}
One of the more powerful features of git is its ability to do branching well. Unlike other VCSs, branches in git are lightweight, so it's ok to make lots of branches and throw them away later.

A branch is basically a pointer to a commit. When you make a commit, the branch you are currently on updates its pointer to the newly-created commit.

Since a branch is basically a pointer, creating a new one doesn't take up a lot of memory. You can create, delete, switch branches, etc., using the commands \texttt{git branch} and \texttt{git checkout}. When you switch branches, the files in your current directory are magically updated!

To see your branches and the commits they point to, run \texttt{git log --graph --oneline --decorate} (\texttt{HEAD} points to the commit/branch you're currently at.)

Usually a repository has a main branch, and it's usually called \texttt{master} (this name is not a special name in git, it's just the default)

\subsection{Remotes}
A remote is basically a pointer to a repository somewhere else (e.g. a repository in github, or in someone else's computer).

To specify a remote, you give it a name, and a URL pointing to the repository (for example, \url{git@github.com:UP-MIT-GSL/angular-momentum.git}).

When you clone a repository, git automatically sets up a remote named \texttt{origin}, which points to the repository you cloned from (\texttt{origin} is not a special name in git, it's just the default). Commands such as \texttt{git push} and \texttt{git pull} default to \texttt{origin} when remote is not specified.

Since remotes are separate repositories, they may have their own branches/commits apart from yours. For example, if a remote named \texttt{alvin} has a branch called \texttt{my-branch}, you refer to that branch as \texttt{alvin/my-branch}.

We use the \texttt{git remote} command to manage remotes.

\subsection{.gitignore}
Sometimes there are files you don't want to include in your version control system. Specify these files by adding a file called \texttt{.gitignore} inside your repository. Add lines of file/folder names/patterns there, one in each line, and git will ignore those files.

Here's an example (from Angular Momentum).

\texttt{\\
.vagrant\\
.DS\_Store\\
/backend/database.json\\
/backend/build/\\
*.pyc\\
*.swp\\
/frontend/node\_modules/\\
/frontend/vendor/\\
/frontend/build/
}

\subsection{github.com}
\url{github.com} is a website that hosts git repositories. Angular Momentum (and many other projects such as Linux) is hosted there.

\subsubsection{forking a repo}
To fork a repo in github, go to the repository page, and click the ``Fork'' button in the top-right corner. This will make a copy of that repo, under your account, which is totally yours to edit.

\subsubsection{making a pull request}
If you forked a repo, made some changes, and eventually you want to push those changes to the original repository, you do so by making a ``pull request''.

Usually you won't have write access to such a repository, so you request its owners to check out your edits and let them decide if your changes are good. This is how open-source contribution usually works.

To make a pull request, visit your repository, and visit the branch you would like to merge, and click ``pull request'' in the top-right corner. This means you have to put your changes in a separate branch for every feature (which is good practice).

\subsection{Config files}
Within your repository, there's a file called \texttt{.git/config} which contains configuration options for your repository (\texttt{.git} is a directory which contains all the data git uses to manage the repository: history, branches, etc.).

Global files are located in \texttt{\urlwofont{~}/.gitconfig}, which is your ``global'' config file (settings here affect all repositories).

You can edit your config files manually, or you can use the command \texttt{git config} (explained below).

\section{Advanced git}

\subsection{More commands}
If you are brave enough to go to this section, you must realize that \texttt{git help <command>} will give more details about the command.

\begin{enumerate}

\item{\texttt{mv}}
     \subitem{Move or rename a file (useful for certain merge conflicts e.g. when someone else modified the moved/renamed file)}

\item{\texttt{config}}
     \subitem{Modify config file}
     \subitem{Usage: \texttt{git config <name> <value>} \texttt{--global} Add to global config file instead}
     \subitem{Example: \texttt{git config merge.conflictstyle diff3};}
     \subitem{\texttt{git config --global user.name "Cloud Strife"}}

\item{\texttt{cherry-pick}}
     \subitem{Get changes of a particular commit and apply those changes to current branch, creating a new commit.}

\item{\texttt{rebase}}
     \subitem{Modify the commit history, e.g. by compressing a group of commits into a single one.}
     \subitem{Warning: Potentially dangerous operation}

\item{\texttt{bisect}}
     \subitem{Find by binary search the change that introduced a bug.}

\item{\texttt{grep}}
     \subitem{\texttt{grep} your repository!}

\item{\texttt{tag}}
     \subitem{Add tags to commits.}

\end{enumerate}

\subsection{Aliases}
A git alias is a way to avoid typing long common commands over and over again. For example, if you find yourself typing the command \texttt{git log --graph --oneline} over and over again, you can make an alias by editing your \texttt{.gitconfig} file and adding:

\texttt{[alias]\\
graph = log --graph --online
}

You can now use \texttt{git graph}, which is now identical to \texttt{git log --graph --oneline} ! 

You can use this for abbreviation, e.g. \texttt{git cmt} instead of \texttt{git commit}, etc. You can still pass flags/arguments. You can also use the underlying shell!

\texttt{[alias]\\
hi = !echo "Hello world!"
}

So \texttt{git hi} will print ``Hello world!''


\subsubsection{Useful aliases}
Some aliases that are very nice (that I got from the internet)

\texttt{[alias]\\
lol = log --graph --decorate --oneline --abbrev-commit\\
lola = log --graph --decorate --oneline --abbrev-commit --all\\
}

You can now use \texttt{git lol} or \texttt{git lola} for very nice graphs of your commits!

\subsubsection{Other aliases}
Visit \url{https://git.wiki.kernel.org/index.php/Aliases} for more cool aliases.
\subsection{Useful \texttt{.gitconfig} options}

\subsubsection{Text editor}
If you're not yet familiar with the text editor \texttt{vim} and would like to use another one for writing commit messages, add the following to your \texttt{.gitconfig} file (to use the \texttt{nano} text editor).

\texttt{[core]\\
editor = nano }

Note, press \texttt{Ctrl+X} to exit \texttt{nano}

\subsubsection{Merge Conflict Style}
If, while resolving merge conflicts, you'd like to see the original version, in addition to your edited version and their edited version, add the following to your \texttt{.gitconfig} file (this is very helpful in my opinion):

\texttt{[merge]\\
conflictstyle = diff3 }

\subsubsection{Coloring}
Add the following to your \texttt{.gitconfig} file to add coloring to git outputs such as \texttt{git log} or \texttt{git status}.

\texttt{[color]\\
  branch = auto\\
  diff = auto\\
  interactive = auto\\
  status = auto }

\section{Online interactive lesson}
If you want to learn interactively, go to \url{http://pcottle.github.io/learnGitBranching/} . Have fun :)

\end{document} 


​