path: root/using-git.texinfo

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename using-git.info
@settitle using git
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header



@dircategory Version Control
@direntry
* using git: (using git).             Using the Git source control management
@end direntry


@copying
Copyright @copyright{} 2013 Mattias Andrée

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@ifnottex
@node Top
@top Using Git
@insertcopying
@end ifnottex

@titlepage
@title Using Git
@author by Mattias Andrée (maandree)

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Getting started::
* Introduction::
* Branching out::
* Collaborating::
* Basic commands::
* I just don't know what went wrong::
* GNU Free Documentation License::
@end menu



@node Getting started
@chapter Getting started

@menu
* Identify yourself::
* Create a repository::
* Create an origin::
* Gratis hosting::
* Generate your key::
@end menu



@node Identify yourself
@section Identify yourself

The first thing you want to do right off the bat
is to identify yourself: add your name and e-mail
address to your Git configurations. This is
done with two simple commands:

@example
git config --global user.name 'YOUR NAME'
git config --global user.email 'YOUR_EMAIL_ADDRESS'
@end example

It is possible to sign your work with GPG. If you
are planning on doing this, and doing this with
another GPG key then your default key, you can
configure Git to using another key by default:

@example
git configre --global user.signingkey YOUR_GPG_KEY_ID
@end example



@node Create a repository
@section Create a repository

A repository is a directory under source control,
normally your project you are working on.

Create an empty directory and @command{cd} into it:

@example
mkdir MY_PROJECT
cd MY_PROJECT
@end example

When you are inside the directory for the repository
issus the git command to initialise the repository:

@example
git init
@end example

This command creates a directory namend @file{.git}
inside the directory with all data git requires to
operate on the repository.

The next thing you want to do is to create a
@file{.gitignore} file, it is used to keep track
of with files that should be be included in the
repository, unless overruled with a forced staging.

A good base @file{.gitignore} content you probably
always want to use is:

@example
_/
# It is a good idea to allow the directory _ to
# contain temporary file you do not whant to stage.

.*
# Generally you probably do not want to include
# hidden files.

!.git*
# But you do generally want to include files
starting with .git, such as .gitignore.

\#*\#
*~
*.bak
# And you do not want to include backup files.
@end example

Git parses @file{.gitignore} with wildcards,
@code{#} for comments and @code{!} for inclusion
rather than exclusion, latter entires override
earlier entries.

When you have create you @file{.gitignore} you
are ready to stage it and make your first commit:

@example
git add .gitignore
git commit -m 'first commit'
@end example



@node Create an origin
@section Create an origin

It is a good idea to create a backup repostory,
so you do not lose your work on a disc failure,
filesystem corruption accidental removal.

You can such repostory for allowing collaboration
with a command repository that the collaborators
can all submit and fetch commits from.

This repository is customarly called `origin'.
And it is a bare repository, meaning that it
only hold the data in the @file{.git} directory
and cannot be used as the working directory.

@example
mkcd -p /srv/git/MY_REPOSITORY.git
cd /srv/git/MY_REPOSITORY.git
git init --bare

cd -  # Go back to your project respository
git remote add origin file:///srv/git/MY_REPOSITORY.git
git push -u orgin master  # master is the bransh you are working in
@end example

It is standard to append @file{.git} to the
end of the repository name when it is bare.

To submit your changes to origin you can now
use the command @command{git push}. To fetch
updates others have made, use the command
@command{git pull}.



@node Gratis hosting
@section Gratis hosting

As seen you do not need host, but it is a grate
way for making your projects available to the world.

Here is a lost of gratis git hosting services that
hosts Free Software.

@table @asis
@item @bullet{} @url{https://savannah.nongnu.org/, Savannah}
Hosts Free Software only, and projects are audited
for licensing issues upon registration. So it can
take a short time before it is accepted, but you your
project will not use non-Free Software and no license
information will be missing. Savannah runs on only
Free Software.

@item @bullet{} @url{https://gna.org, Gna!}
For Free Software projects only. Gna! runs on only
Free Software.

@item @bullet{} @url{https://bitbucket.org, BitBucket}
Gratis for 5 uses, with unlimied number of private
repositories for 5 collaborators.

@item @bullet{} @url{https://github.com/, GitHub}
5 private repositories for students, for two yours
and reactivatable when expired. Teachers and student
organisations can get private repositories, as many
as required, for an organisation.

@item @bullet{} @url{https://www.assembla.com/catalog/51-free-private-git-repository-package?type=private&ad=git-wiki, Assembla}
Hosting limited to 2 GB with one free private
repository for three users.

@item @bullet{} @url{https://www.cloudforge.com/pricing, CloudForge}
Hosting limited to 2 GB.

@end table

You should note that there are, other, git hosting
services that does not allow Free Software. Some
of them will allow Open Source, some will allow
Free Software, but not gratis.



@node Generate your key
@section Generate your key

Many Git servers authenticate using public
SSH keys. If you do not already have SSH
installed, install it, it is probably named
@code{openssh} in your GNU/Linux distributions'
package repository.

Before create an SSH key, check if you already
have one. You are looking for a pair of
@file{id_rsa.pub} and @file{id_rsa}, in
@file{~/.ssh}. @file{id_rsa} is your private
key and should not be shared or made public.
@file{id_rsa.pub} is you public key and is
the file you want to upload you your Git
hosting server.

If you do not already have a key, you can
create it with:

@example
ssh-keygen -t rsa -C 'YOUR_EMAIL_ADDRESS'
@end example



@node Introduction
@chapter Introduction

@menu
* What is Git?::
* It is distributed::
* Integrity::
@end menu



@node What is Git?
@section What is Git?

Git is a version control system know for
its lightning speed and being distributed.
A version control system is a system for
storing changes in a history tree and allow
for multiple people to work on the same
project without the risk of the code being
too new to accept a submitted patch.

When you are working it is important to keep
track of changes so that you can find when
edit step broke the system. But version
control also lets you create branches, these
are different versions of the same project
being developed concurrently which lets your
team implement features in parallel and
merge them in into the mainline when stable.

And other important feature of version
control that can be used to tag releases
of the code. If you have release a program
and is sent a bug report you may want to
test it one both the current version and
the version the user used.



@node It is distributed
@section It is distributed

Traditionally, version control systems
were centralised. Every project has one
repository all contributers pushed and
pulled from. Git is distributed, this
means that contributers clone the
respositor and words on that clone
instead of ``checking out'' the current
tip of the source code. This actually
means that there are multiple backups
of the respository is recovering a
crash or corruption will be a breeze.

It is a popular misconception that
distributed systems are not suited for
projects that requires an official
central repository. This is far from
true; projects have a central blessed
repository, possibly with mirrors.

A blessed repository, refered to as
the upstream, is the projects official
respository. Its maintained by a select
few with input from submitted updates.
But the upstream can also be a shared
repository, this is the classical
Subversion-style workflow, where everyone
pulls from and pushes to. Git does not
allow you to push before you have pulled
to latest commit so this workflow works
fine.

Small projects will usally have one
maintainer and contributors clones her
blessed repository and sends submissons
to her. Larger projects may have multiple
maintainers that helps with excepting
submissons. A common model like this,
that you often se on GitHub, is the
integeration manager workflow, where the
maintainer is an integeration manager
than excepts pull requests from developers
that have public repositores, often
called forks (which should not be confused
with a project fork where the forker
is taked the project in another direction
is does not requests pulls.)

Even larger project will usablly work
with a dictator and lieutenants workflow
where developers clones the blessed
repository and submits patches to the
lieutenants who in turn submits the the
dictator that finally pushes the changes
to the blessed repository.



@node Integrity
@section Integrity

Git cryptographically hashes all data
associated with a commit, including the
prior commit. This makes it unfeasible
to modify a commit without changing the
commit ID; change the commit ID brakes
the commit history and would therefore
get noticed as the develops cannot work
against a broken commit history.

Additionally commits can be signed with
GPG, so you can be sure that the commit
is how is says he is.



@node Branching out
@chapter Branching out

@menu
* Workflow::
* Creating branches::
* Merging branches::
@end menu



@node Workflow
@section Workflow

Git encourage you to create multiple local
branches of you repository. A branch is a
fork of your commit history, it allows you
to implement features in parallel. The most
important part with this is that you can
fix bugs meanwhile you are working one big
new features.

You main branch is by default called `master',
from it, it is recommended to have a branch
called `develop'. The develop branch is the
branch you work on, and when it is stable,
you merge it with the master branch.

From the develop branch you can branch out
an create topic branches, an disposable
experiments.



@node Creating branches
@section Creating branches

The quickest way to create a new branch and
start working on it is to issue a checkout
command that create a new branch:

@example
git checkout -b BRANCH_NAME
@end example

After issuing this command you are located
in a new branch. The create it in the origin,
make a push:

@example
git push -u origin BRANCH_NAME
@end example

From this point on you can push without
parameters:

@example
git push
@end example

The @option{-u origin BRANCH_NAME} is just
to initially tell which remote repository
a pushes should go to.

To switch branch use the checkout command:

@example
git checkout BRANCH_NAME
@end example



@node Merging branches
@section Merging branches

The merge a branch into another, switch
to one of them and pull the other:

@example
git checkout MERGER
git pull . MERGEE
@end example

In the default mode, @command{git pull . MERGEE}
is a short and fore a fetch and merge:

@example
git fetch MERGEE &&
git merge MERGEE
@end example

If you two cannot be automatically merged,
you will you get a merge conflict. A case
where you will get merge conflicts is when
one of the branches as made a modification
where the other has change the indention,
so keep to a coding style from the start;
or both has edited the same lines.

If you get a merge conflict, git will tell
you so, in which files there are conflicts,
and exit with the return code 1 to indicated
that the merge was not successful and human
intervention is required. If the merger
branch as a file with the line
@code{Hello world} and the mergee branch
as the line @code{hello world!}, the
file will contain:

@example
<<<<<<< HEAD
Hello world
=======
hello world!
>>>>>>> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@end example

Where
@code{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
is the lower case hexadecimnal represention of
the commit ID at the tip of the mergee branch,
which is a SHA-1 hash sum of the commit.

After a merge conflict you will need to stage
the files and make a new commit.



@node Collaborating
@chapter Collaborating

@menu
* Cloning a repository::
* Submitting patches::
* Accepting patches::
* Making pull requests::
@end menu



@node Cloning a repository
@section Cloning a repository

The first thing you need to do in order
to begin collaboration is the clone the
repository:

@example
git clone REPOSITORY -o upstream
@end example

By including @option{-o upstream}, git
sets up the cloned repository as a
remote repository named `upstream'.

If you want to access a branch in the
upstream repository, use
@code{upstream/BRANCH} as the branch name.



@node Submitting patches
@section Submitting patches

The best way to create a patch is with Git's
@command{format-patch} command. Assuming
you began from @code{upstream/master}:

@example
git format-patch upstream/master
@end example

This command with create a patch whose name
will be printed by @command{git format-patch}.

Creating a patch this way will keep track
of the commit messages, and the individual
commits. Another advantage with it is that
it can easily be submitted to a mailing list,
which the common way for large projects for
accepting patches.

The created patch file is formated as an
e-mail, with `[PATCH]' in the beginning of
the subject line. If you update the patch
it is customary to use `[PATCH v2]' instread
and `[PATCH v3]' on the second update.
If the patch, however it not readly for
being included, but is rather for discussion,
use `PATCH/RFC'@footnote{RFC is an abbreviation
for `Request for comments'} instead of `PATCH'.

To send the patch, use @command{git send-email}:

@example
git send-email --to=EMAIL_ADDRESS_TO_SEND_TO PATCH_FILE
@end example

If you have registered to the mailing list,
or for some other reason, want to send under
a different e-mail address then you made the
commits with, you need to specify an envelop
send, by adding an option:

@example
--envelope-sender=SENDER_EMAIL_ADDRESS
@end example

You will also need the specify which SMTP
server to use, authorisation and configurations:

@example
--smtp-server=DOMAIN    # it usally is prefixed with smtp.
--smtp-server-port=PORT
--smtp-encryption=ssl   # or tls
--smtp-user=ACCOUNT     # usally just the username without domain
--smtp-pass=PASSPHRASE
@end example

If you are using a forwarding e-mail, such
as @@member.fsf.org, you send from using your
normal e-mail, but use the forwarding e-mail
address as the envelop-sender, most e-mail
server should accept this.

If you are replying to a message in the mailing
list, perhaps with an updated patch, you should
specify the message ID of the message to replay
to. This done my adding the option:

@example
--in-reply-to=MESSAGE_ID
@end example

To get the message ID, open the message in your
e-mail client and choose to see all headers ---
if not possible: download the it as an mbox file
and open it in an text editor --- a look for:

@example
Message-ID: <MESSAGE_ID>
@end example

As indicated here, it is surrended by less than
and grater than-signs. You should, if you have
subscribed to the mailing list, have gotten it
send to your e-mail. If you do not have it, go
the the mailing lit and click that you want to
reply, it will open your e-mail client in compose
mode and the in-reply-to address will have been
set to the proper message ID.



@node Accepting patches
@section Accepting patches

To apply a patch, use the @command{git am}
@footnote{`am' stands for `apply mailbox',
but it words on regular patch files}
command:

@example
git am PATCH_FILE
@end example

Is good practice to sign off commits to
help establish a chain to trace submissions,
and some projects will require it. To
sign off with @command{git am}, just add
@command{--signoff}.



@node Making pull requests
@section Making pull requests

A less feature rich alternative than
patches are pull request, but they are
easier to just because you do know need
to know anything to make a pull request
and to accept them you just need to
know how to pull from other repositories.

Git does however provide a command
the produces a clean standard message
than can be posted on a mailing list.
To do this just type:

@example
git request pull FORKING_POINT_COMMIT YOUR_URL
@end example

Additionally you can add a commit that
the pull requests stops at, if you have
another commit than @code{HEAD} --- the
current commit you are working at --- in
mind. You can also add @option{-p} if
you want to see the changes.



@node Basic commands
@chapter Basic commands

@menu
* The trees of Git::
* File operations::
* Go back in time::
@end menu



@node The trees of Git
@section The trees of Git

Git has four trees should know about
to better understand how Git works.

The first tree you encounter is the
working directory. The tree begins
in the parent so called git directory;
the directory you executed
@command{git init} in, and contains
the directory @file{.git}.

When you are using @command{git add}
to stage files you encounter the next
tree. This tree is called the index,
and is separate from the working
directory, when you stage a file,
you stage an edit, if you edit the
file further those changes does not
make it into the index until you
restage the file.

When you have done some work ---
just a small logical step is recommended
--- and want to save your changes you
commit then with @command{git commit}.
This is when you encounter the third
tree, the @code{HEAD}. @code{HEAD} is
the file tree of the last commit, and
it is updated when make a commit.

The fourth tree is not a file tree,
it is the commit tree. The important
thing with Git is that this tree is
not linear, it is a directed acyclic
graph, so it is not really a tree,
but you can think of it as one because
you are normally only interested
in the leaves, your branches.



@node File operations
@section File operations

Their are four basic options you can
do on files: add, update, remove and
rename, adding and update is done
with the same command:

@example
git add FILE
@end example

To remove a file or rename a file,
just do as you normally would without
git, but prepand @code{git}:

@example
git rm FILE           # Remove FILE
git mv FILE NEW_NAME  # Rename FILE to NEW_NAME
@end example

If an directory in becomes empty
in the working directory it is
automatically removed from working
directory. And directories are never
tracked by Git, so you cannot have
an empty directory in a commit.

You can also use @command{git add -u}
@footnote{@option{-u} is the short
option for @option{--update}.} to
stage an edit in an already tracked
file or stage the removal of it
if it as been removed from the
working directory.

A caveat with @command{git mv} is
that is that is that same thing as
typing:

@example
cp FILE NEW_NAME
git rm FILE
git add NEW_NAME
@end example

In other words, the history for
the file is reset and if you do
this at the same time someone
edits the file you will get a
merge conflict.

This is not a problem with GNU
Arch because it keeps track of
which file is which by giving
it an unique identifier, and you
may think that would have been
a good think. But if the content
of the file depends on the file's
name, or the other way around,
and a line with such dependency
is added, the file's content
would become bad. Well it is
debatable since the case could
be that another file depends on
the renamed files name, and
someone could make a change in
that file. But fixing a merge
conflict when you have only
renamed the file is not too hard
and it eliminates a potatial
maintenance miss.

If you want do know the file
staging difference between the
index and working directory
type @command{git status}.



@node Go back in time
@section Go back in time

Because git keeps track of what
has changed it has a log you
access, which has commit messages,
so you know when something has
happend or what has happen lately.
To read the log type:

@example
git log
@end example

If you want to know which files
have changes, you can use
@command{git whatchanged} instead.

If you want to take a closer look
a commit an see the state of the
project at the commit type:

@example
git stash               # Only if you have uncommited changes, this
                        # saves you changes outside the tree in a stack.
git checkout COMMIT_ID  # Take a look around!
git checkout -          # Checking out - means that you checkout the
                        # commit you were on before the last checkout.
                        # Kind of like `cd -'.
git stash pop           # Only if you have uncommited changes, this
                        # reapplies the changes you saved with `git stash'
                        # and removes it from that stack.
@end example

If you instead what to see all
changes from that point of time type:

@example
git diff COMMIT_ID
@end example

Or for a specific file:

@example
git diff COMMIT_ID FILE
@end example

If you decide that you want to go back
permanently to this state you type:

@example
git revert THE_COMMIT_ID_OF_THE_COMMIT_AFTER_THAT_COMMIT..HEAD
@end example

If you have not push the commits you
want to revert you can do a reset instead,
thay way the are irreverable removed
instead of a new commit being made:

@example
git reset --hard COMMIT_ID
@end example

But you should think of that as running
as root:

@cartouche
@noindent
Chris: root is the number zero user,
it is main user in your system, it
can do everything, it can literally
delete the filesystem while your
operating system is running.

@noindent
Bryan: Yeah, it is a grate user in
that regard.

@noindent
Chris: Yeah. Yeah.

@noindent
Bryan: Here is the thing, so people
always say `do not run as root.'
@emph{I always} run as root.

@noindent
Chris: Do you really always run as
root?

@noindent
Bryan: Hell yes. Do you know why I
always run as root?

@noindent
Chris: Why?

@noindent
Bryan: Awesome.

@noindent
Chris: Here, I... <interrupted>

@noindent
Bryan: I live on the edge. I'm like
Mad Max. <Saying something but Chris
is louder.>

@noindent
Chris: Do you really always run as
root for real?

@noindent
Bryan: No, I do not run as root.
Are you kidding me, that is asinine!
I would love to think that I am so
hardcore that I just always ran as
root. I just, caution to the wind,
screw it, lets just thunderdome this
bitch and... you know, see what
happens. But no, never run as root,
never ever do that. The only time
you run as root is when you run as
root temporarly, you sudo.

@noindent
Chris: You need to do something.
@end cartouche

Only use @command{reset} if you
are absolutely sure and know exactly
what you are doing.



@node I just don't know what went wrong
@chapter I just don't know what went wrong

@menu
* Naïve reset::
* Using the stash::
* Commit amendment::
* Bisection::
@end menu



@node Naïve reset
@section Naïve reset

If something went horribly, horribly,
horribly, horribly wrong and you do
not know how to get back to a clean
state, you can always doing this naïvely
by clone the repository:

@example
git clone REPOSITORY REPOSITORY.new
cp REPOSITORY/.git/config REPOSITORY.new/.git/config
yes | rm -r REPOSITORY
mv REPOSITORY.new REPOSITORY
@end example



@node Using the stash
@section Using the stash

The stash is a grate utility for storing
changes. If you have made changes in
the working directory or the index, you
can store them in the stash and both
the working directory and the index will
be restored to the @code{HEAD}. Keep
in mind the the naïve reset will discard
the stash because the stash is local.
Changes stored to the stash can be applied
to any branch and any later state of the
@code{HEAD}, that is what the stash is
made for.

The basic stash operations include:

@table @command
@item git stash
Store the changes made to the index and
working directory.

@item git stash drop
Discard the object at the top of the
stash stack.

@item git stash apply
Apply changes stored as the object at the
top of the stash stack.

@item git stash pop
Synonym for
@command{git stash apply && git stash drop}.

@item git stash clear
Discard all stored stash objects.
@end table



@node Commit amendment
@section Commit amendment

If you have not yet pushed your latest
commit you can amend it. If you have
pushed it, you cannot amend it cause
the commit ID changes because it is
SHA-1 hashsum of all imformation.

To amend your commit run
@command{git commit --amend}.
It will launch your text editor so
you can edit the commit message,
additionally all staged changes are
included in the amendment.



@node Bisection
@section Bisection

Bisection is the process of identifying
when a bug was introduced.

To start a bisection you first need
to tell git to start bisection and
specify the commit range. If the current
commit is bad you type:

@example
git bisect start
git bisect bad
git bisect good LAST_KNOWN_GOOD_COMMIT
@end example

After this you either of, depending if
the commit Git checks out is good or bad:

@example
git bisect good
git bisect bad
@end example

Git will tell you when it has found the
the first bad or possible first bad commit.
To then checkout the commit that was
checked out before the bisection started
type:

@example
git bisect reset
@end example

If you in the process of the bisection
landed on a commit you need to skip because
it has some other problem, you can use

@example
git reset --hard HEAD~N
@end example

Where @code{N} is the number of revisions
before the checked out, you want to jump to.
You can also use @command{git bisect skip}
to Git which revision that cannot be tested
so they are excluded from the bisection
process.

Instead of manually telling Git if a commit
is good or bad, you can use:

@example
git bisect TEST_SCRIPT [ARGUMENTS...]
@end example

The test script should exit with 0, if and
only if the commit is good, 125 to skip the
commit, and anything else between 1 and
127, inclusively, if the commmit is bad.
Other values (128–255) will abort the
bisection.



@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo

@bye