path: root/using-git.texinfo

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

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

@set TEXI_5

@c @set HARD_COPY_EDITION
@c @smallbook
@ifset HARD_COPY_EDITION
@ifset TEXI_5
@cropmarks
@end ifset
@setchapternewpage odd
@end ifset
@finalout
@c %**end of header



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



@macro prelude
@center @titlefont{Prelude}
@iftex
@sp 1
@end iftex

@ifset TEXI_5
@ifnottex
@quotation
@end ifnottex
@end ifset

@noindent
This Git manual is intended to be
educational rather than a lookup
documentation. And it is written as a
tutorial, similarly to an educational
mathematics book, except it does not
include problems to solve or test.
Consequentially, it is designed to
be read chapter by chapter with
occasional look-backs. Because of
the scattered design of the content
layout, Git's online documentation,
accessible with @command{man git}
and @command{man git VERB}, is much
better for quick lookup of information,
such as how to use a command.

This manual will teach you the basics
for using Git with an early focus on
contributing to existing projects, and
iterates to increasingly more advanced
features that makes life with Git even
easier. But it will also teach you some
ideas behide Git's design. You will also
learn about side-issues such as how to
best make your own project installable
and navigateable by others without
excessive documentation and without having
to answer too many questions.

This manual is aimed at technical people.

@c @ifclear HARD_COPY_EDITION
@c If you prefer a hard copy edition, you can order one from
@c ...
@c @end ifclear

@ifset TEXI_5
@ifnottex
@end quotation
@end ifnottex
@end ifset

@end macro


@copying
Copyright @copyright{} 2013, 2014, 2015, 2016 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

@prelude
@end ifnottex

@titlepage
@title Using Git
@subtitle Educational manual for Git, the version control system.

@c @vskip 0pt plus 1filll
@c @c this way, it is centered exactly in pdf and approximently in dvi and ps
@c @c @center does not work for @image in dvi and ps
@c @multitable @columnfractions 0.15 0.7
@c @item @tab @center @image{obj/logo,200px}
@c @end multitable
@c @vskip 0pt plus 1filll

@author by Mattias Andrée (maandree)

@page
@center git: A silly, incompetent, stupid, annoying, or childish person.
@vskip 0pt plus 1filll
@insertcopying

@page
@prelude
@end titlepage

@contents



@menu
* Getting started::                       Getting started with Git
* Introduction::                          What is Git and why is it the best?
* Branching out::                         The flexibility of non-linearity
* Collaborating::                         Shared goals, shared development
* Basic commands::                        So happy hacking!
* I just don't know what went wrong::     Identifying when something broke and how to recover
* Version control::                       Time to release a new version?
* Commit squashing::                      Melding commits
* Interface::                             Git's interface design
* Features::                              Git's design and features
* Beyond Git::                            Just using Git is not enough
* GNU Free Documentation License::        Sharing is good, it does not make you a pirate
* Glossary::                              Lost in all the big words?
@end menu
@c TODO Masterful flow



@node Getting started
@chapter Getting started

@menu
* Identify yourself::                     Configure Git to identify you when you make commits
* Create a repository::                   Create your first repository
* Create an origin::                      Create a backup repository
* Gratis hosting::                        Get a hosting service for your superawesomazing projects
* Generate your key::                     Create an identification 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 config --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 named @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 included in the
repository, unless overruled with a forced staging.

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

@example
.*
# 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 created your @file{.gitignore} you
are ready to stage it and make your first commit:

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

It is a good idea to allow the directory @file{_}
to contain temporary file you do not want to stage.
You should not such rules to, @file{.gitignore},
but rather to @file{.git/info/exclude}.



@node Create an origin
@section Create an origin

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

You can use such repositories for allowing
collaboration with a common repository that all
collaborators can submit commits to and fetch
commits from.

This repository is customarly called `origin'.
And it is a bare repository, meaning that it
only holds the data in the @file{.git} directory
and cannot be used as the working directory, it
is missing what is in Git called `index'
@footnote{Or `cache', an obsolete term.} and
`working tree'.

@example
mkdir -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 branch 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 a hosting service --- if
you have a network filesystem anyone with access
to it can also have access your bare repository ---
but it is a great way for making your projects
available to the world.

Here is a list of gratis Git hosting services that
allow hosting of Free Software projects.

@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 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 users, 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/, Assembla}
Hosting limited to 2 GB with one free private
repository for three users.

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

@item @bullet{} @url{https://www.codeplex.com/, CodePlex}
Allows only Free Software licenses, but is very restrictive
the which licenses it allows. Questionable security.
Cannot be use for projects with complex license
structures or for example GNU AGPL (GNU GPL is accepted.)

@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@footnote{Or
whatever you are using.} distribution's
package repository. If not, you can download
it at @url{http://www.openssh.com}.

Before creating 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 to 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?::                          So exactly what is Git?
* It is distributed::                     The power of non-centralisation
* Integrity::                             How you know that noone is messing with your project
* Online documentation::                  Git comes with online documentation
@end menu



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

Git is a version control system known for
its lightning speed@footnote{Especially
under POSIX-compatible systems.} 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 which
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 down onto the mainline when stable
or implemented to an acceptable degree.

Another important feature of version
control that it can be used to tag releases
of the code. If you have released 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 contributors pushed and
pulled from. Git is distributed. This
means that contributors clone the
respository and works 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 and 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. It is 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 clone her
blessed repository and sends submissons
to her. Larger projects may have multiple
maintainers that helps with accepting
submissons. A common model like this,
that you often see on GitHub, is the
integeration manager workflow, where the
maintainer is an integeration manager
than accepts pull requests from developers
that have public repositories, often
called forks (which should not be confused
with a project fork where the forker
is taking the project in another direction
and does not intend requests pulls.)

Even larger project will usally work
with a dictator and lieutenants workflow
where developers clone 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; changing 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 committer
is who she says she is.



@node Online documentation
@section Online documentation

As with most software packages, Git
includes online documentation, accessible
in several ways. The simplest way --- this
will working on all systems --- is by adding
@option{--help} to the command @command{git}
or @command{git VERB}.

Git is a project started by Linus Torvalds,
the creator of the Linux kernel, so naturally
it has manpages, but not any official
@command{info} manual. Since @command{info}
supports manpages you can use @command{info}
in place of @command{man}.

Git includes several manpages, one manpage
for every Git command: @command{man git VERB}
or alternatively @command{man git-VERB}, and
manpages on special topic:

@itemize
@item @command{man git}
@item @command{man gitattributes}
@item @command{man gitcli}
@item @command{man gitcore-tutorial}
@item @command{man gitcredentials}
@item @command{man gitdiffcore}
@item @command{man gitglossary}
@item @command{man githooks}
@item @command{man gitignore}
@item @command{man gitmodules}
@item @command{man gitnamespaces}
@item @command{man gitrepository-layout}
@item @command{man gitrevisions}
@item @command{man gittutorial}
@item @command{man gittutorial-2}
@item @command{man gitworkflows}
@end itemize



@node Branching out
@chapter Branching out

@menu
* Workflow::                              Why should I branch?
* Creating branches::                     How do I branch?
* Merging branches::                      How do I merge my branches?
@end menu



@node Workflow
@section Workflow

Git encourage you to create multiple local
branches of your 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 on big
new features.

Your 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
and create topic branches, and 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. To 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
pushes should go to.@footnote{It actually
also tells to not push anything else.}

To switch branch use the checkout command:

@example
git checkout BRANCH_NAME
@end example



@node Merging branches
@section Merging branches

To 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 shorthand for a fetch and merge:

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

If the two branches cannot be automatically
merged, you will get a merge conflict. A case
where you will get merge conflicts is when
one of the branches has made a modification
where the other has change the indention,
so keep to a coding style from the start;
or both have 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 has 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::                  Start your collaboration
* Submitting patches::                    Submit your work upstream
* Accepting patches::                     Accepting received commits
* Making pull requests::                  Request integration
@end menu



@node Cloning a repository
@section Cloning a repository

The first thing you need to do in order
to begin collaboration is to 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'
instead of `origin'.

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 will create a patch for each
commit whose names 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 this is that
it can easily be submitted to a mailing list,
which is the common way for large projects for
accepting patches.

The created patch file is formatted 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]' instead
and `[PATCH v3]' on the second update.
If the patch, however it not ready 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 with,
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
sender, by adding an option:

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

When using an envelop sender you also need to
specify the commiter with both name and e-mail:

@example
--from='NAME <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

You do not need to use @option{--smtp-pass}.
But if you are inclined to it is good to know
that if you start the command line with
whitespace in GNU Bash, GNU Bash will not
store the command in the command history.
Be aware that other users on the system
will be able to see the passphrase in the
process list if you use @option{--smtp-pass}.

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

You should configure these settings@footnote{Except
for the passphrase of course.} in @file{~/.gitconfig}.
These settings are stored in the @code{[sendemail]}
section. The key names are the same as the
command line options, except in camel case
instead of hyphens.

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 reply
to. This done by 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 a text editor --- and look for:

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

As indicated here, it is surrended by less than
and greater 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 list 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.@footnote{Assuming
your e-mail client supports field specification
and is associated with @code{mailto:}, usally
this is not a problem, if it is, claws-mail will
do the job.}



@node Accepting patches
@section Accepting patches

To apply a patch, use the @command{git am}
@footnote{`am' stands for `apply mailbox',
but it works 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}.

If you are unable to apply a patch with
@command{git am} because of the patch's
formatting, test @command{git apply}
instead.



@node Making pull requests
@section Making pull requests

A less feature rich alternative to
patches are pull request, but they are
easier to use because you do not 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
that 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::                      How history in Git is structured
* File operations::                       Working with files in Git
* Go back in time::                       Virtual time travel
@end menu



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

Git has four trees your should know about
to better understand how Git works.
The first tree you encounter is the
working directory, called the working
tree in Git. The tree begins in the
parent of the 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
@footnote{Previously called the cache.},
and is separate from the working
tree, 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 the index 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 prepend @code{git}:

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

If a directory becomes empty
in the working directory it is
automatically removed from working
directory. Directories are not
tracked by Git, 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.

Git trackes file renames implicitly,
so @command{git mv} is same thing as:

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

This approach is flexible, but
it has some caveats. GNU Arch
keeps track files by giving
them unique identifier, this
solves the problem were you in
Git can get an evil merge if
the pulled branch does not have
any common commits.@footnote{Identified
with commit ID, not snapshots,
which reflects on more than the
file content.} For example,
the pull patch was not made from
a clone repository or did not
contain commit history. Other
systems tracks renames explicitly
when a rename command is made,
that is worst because that means
that you need to use the rename
commit, and evil merges are even
more probable. A problem with
merging when there is a rename
is that the changes are automerged
instead of creating a conflict,
you can get evil merges where
the content of the resulting file
refers to the files old name,
naturally this is still a problem
if another file depending on
the renamed file is edited in
parallel.

If you want to 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 can
access, which has commit messages,
so you know when something has
happend or what has happen lately.
To read the log type @command{git log}.
If you want to know which files
have changed, 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
@command{git diff COMMIT_ID}, or
@command{git diff COMMIT_ID FILE}
for a specific file.

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,
this way they 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 great 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, let's 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::                           Last resort recovery
* Using the stash::                       Stash changes
* Commit amendment::                      Correcting an unpushed commit
* Bisection::                             Identifing when something broke
@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 do 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 great 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 because
the commit ID changes because it is
SHA-1 hashsum of all information.

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 type, 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 tell 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 run 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 Version control
@chapter Version control

@menu
* Tagging versions::                      Releasing your new version
* Cherry-picking::                        Backporting and selective proposed update merge
* Examine the log::                       Utilising Git's commit log
@end menu



@node Tagging versions
@section Tagging versions

Generally, programs have different release
version. When you release a new version,
you tag the last commit makes it into
that version. To do this, create an
annotated tag object and push it to your
origin:

@example
git tag -a 'RELEASE_VERSION'
git push origin 'RELEASE_VERSION'
@end example

The created tag can be refered to as
any commit or branch.

If you want to remove a tag, you
just tell Git to delete it and push
the deletion of its reference to
your origin:

@example
git tag -d 'RELEASE_VERSION'
git push origin :refs/tags/'RELEASE_VERSION'
@end example

@file{refs/tags/RELEASE_VERSION} is a
file in the @file{.git} directory.
Using a @code{:} tells Git that you
want to push the local file before the
@code{:} to the remote file after the
@code{:}. If the local file is not
specified, in order words, the argument
begins with @code{:}, you are telling
Git to remove the remote file.
This only work with references, that is,
files inside @file{.git/refs}.



@node Cherry-picking
@section Cherry-picking

Cherry-picking is the action of applying
changes made in another commit. It is a
create tool both for apply changes made
to another branch or to backport features.

Cherry-picking works just merging branches,
except, instead of choosing a branch to pull
and apply all it changes you choose
individual commits, and commits ranges:

@example
git cherry-pick COMMIT_ID
@end example



@node Examine the log
@section Examine the log

So how are you going to cherry-pick commits
if you do not know their commit ID:s? Simple,
you use Git's log tool to find their ID:s.

The log will only show earlier commits in
the branch then the currently checked out
commit. Typing @command{git log} will show
you the commit's ID, author, date, and
commit message. You can limit the commits
to a commits where specify files has been
changed by appending those files to the
command.



@node Commit squashing
@chapter Commit squashing

@menu
* Squash'em::                             Merging commits into one
* Think about the children::              Repairing the history of child branches
* Commit splitting::                      Splitting after squashing
@end menu



@node Squash'em
@section Squash'em

Assume that you made a commit, but you
find a typo or an other error and make
subsequent commit. These two commits are
the part of the same logical step,
normally you would want to make the
second commit an amendment of the first
commit rather than a separate commit,
but if you did not you can squash them
together. Normally this does not matter,
but you may want to keep your commit
history clean or you may be requested to
if you submit a patch or pull request.

Squashing commits is a bit more
complicated than one may want to,
but it is simple rather than complex.
If you have a branch that you want
to squash and merge with another branch
it is easy:

@example
git merge --squash mergee
@end example

The merger and the mergee now have
different history. You can either
delete the mergee with
@command{git branch -D mergee}
or rename it do indicate the that
its history is different:

@example
git branch -m mergee unsquashed-mergee
@end example

But the complicated part is when you
want to squash a set of commits without
merging them into another branch.
To do this you need to create a temporary
branch and merge into it. Assume that
you have then branches @code{squashthis}
and @code{squashbase}; @code{squashthis}
is a branch that should be squash from
@code{squashbase}.

@example
git checkout squashthis
git checkout -b unsquashed-squashthis    # Save the unsquashed commits
git push -u origin/unsquashed-squashthis # and (optionally) push them
git checkout squashbase
git checkout -b squashed-squashthis
git merge --squash squashthis
@end example

Now you have make a backup of
@code{squashthis}, named
@code{unsquashed-squashthis}, before
it was squashed; and created
a squashed duplicated of
@code{squashthis} named
@code{squashed-squashthis}.
But you should also turn
@code{squashthis} into
@code{squashed-squashthis} and
push the update preferable without
ever deleting @code{squashthis}
on the remote repository so that
an collaboration service when a
pull request is made does not get
confused.

@example
# We are still in squashed-squashthis
git branch -M squashed-squashthis squashthis
# The local squashthis has been deleted and replaced with
# squashed-squashthis, and we are now in squashthis, the
# new name of squashed-squashthis.
git push --force
@end example

@option{--force} is needed to remove
the old commits that have be squashed
and update the new commit. Without
@option{--force} the push will be rejected.

Try to avoid commit squashing
were the squash top is not the tip
of a commit chain. It will probably
lead to merge conflicts and you will
have interate the process for subsequent
commits. Additionally, it is a bad idea
to squash branches other as working,
this includes you default branch
(usually called @code{master}). You
should always assume that others are
working on public branches that feature
branches.



@node Think about the children
@section Think about the children

If @code{squashthis} in @ref{Squash'em},
is not the tip of a branch, it will
atleast have one child branch. That
child (all children) will have a
broken history and be a child of
@code{squashbase} instead of
@code{squashthis}. To repair this,
the child needs to be rebased:

@example
git checkout squashchild
git rebase squashthis
@end example 

This is an except to the rule that
you should not run @command{git rebase}.
In this case it is prefered because
you are repairing rewritten history
rather than rewriting history.

The consequence if this rebase is
that the commit of @code{squashthis}
is inserted between @code{squashbase}
and @code{unsquash-squashthis} before
@code{squashchild}. The commits of
@code{unsquash-} @code{squashthis} have
no effect and should be removed. To do
this you need to squash togather the
commits of @code{unsquash-squashthis}
and (at least) the first proper commit
of @code{squashchild}.



@node Commit splitting
@section Commit splitting

You way want to split a commit, after
you have squashed commits, to make a
set of commits each representing a
logical step.

If the commit you want to split is
named @code{squashed}, you can checkout
the commit before it and cherry-pick it
into a new branch:

@example
git checkout squashed^
git checkout -b splitted-squashed
git cherry-pick squashed
@end example

Then you reset to make so that the
changes are not staged:

@example
git reset HEAD^
@end example

Now you can include the changes you
want in to first commit and start over
from the @command{git cherry-pick}
step and include the changes for the
second commit and so on until everything
is included.

When you can created the final commit
you can save @code{squashed}:

@example
git checkout squashed
git checkout -b unsplitted-squashed
git push -u origin unsplitted-squashed
@end example

And then update @code{squashed} with
the commit split:

@example
git checkout splitted-squashed
git branch -M splitted-squashed squashed
git push --force
@end example



@node Interface
@chapter Interface

@menu
* First things first::                    Order matters! (Especially with find)
* Wildcards::                             Beware of wildcards
@end menu
@c TODO man gitrevisions



@node First things first
@section First things first

Many Git commands take both revisions
and paths as their arguments. First come
the revisions, then the files. If you
have files that can be misunderstood for
a revision, place a @option{--} between
the revisions and the files, anything
after a @option{--} is interpreted as
a file. It is a good practice to do this
in scripts that takes random user-input.



@node Wildcards
@section Wildcards

Many Git commands allow wildcards in
paths. These commands will expand
wildcards in the arguments just a
the shell. To avoid problems, never
use characters in paths that are
used in the shell for wildcards
and expansions… yeah, I know, it
is annoying.



@node Features
@chapter Features

@menu
* Git and permissions::                   File permission tracking in Git
* Git and timestamps::                    File timestamp tracking in Git
* Git and custom merge tools::            Merge tool customisability in Git
* Git and shared build caches::           Shared build caches do not belong in source control
* Git and keyword expansion::             Keyword expansion is evil and do not belong in source control
* Git and links::                         Symlink and hardlink tracking in Git
* Git and filenames::                     Filename tracking in Git
* Git and merge tracking::                Merge commit tracking in Git
* Git and empty directories::             Nontracking of empty directories in Git
* Git and file renames::                  File rename tracking in Git
* Git and encoding convertions::          Encoding convertions in Git
* Git and atomic commits::                Atomic commits and source control
@end menu



@node Git and permissions
@section Git and permissions

Filesystems lets you set permissions
for users on files. Permissions, such
as whether the owner, a specific user
group, or others, can read, write or
execute the file as well as whether
the permissions of the owner if the
file is granted the execute instance
of the program for further permissions
that are mission critical.

Tracking permissions in version control
system makes no sense since source code
should always be readable and writable
by the owner and it is local configuration
whether you want to extend those
permissions to other users on your
computer.

However there are source code that is
executable, scripts, such as Bash, Perl
and Python. This is may Git does however
track the execution bits. The set-user-ID
bit and the set-group-ID bit is however
not tracked, nor should they, those
should only be set when the program is
being installed.

Git does not track directories, so permissions
no directories are also ignored.

Be aware that some systems sets the execution
bit willy-nilly when a file is created.

This is a shortcoming of Git, but only
in comparision to darcs. Since files are
only executable if they are compiled or
have a shebang, it would make more sense
to set it on and only on the files with a
shebang or otherwise tagged to have a specific
permission.

Additionally Git does not track file ownership
--- that would not only be stupid, that would
be outright dumb, even moronic, --- access
control lists, extended attributes nor forks.



@node Git and timestamps
@section Git and timestamps

One of Git's features is that it does
not have the feature@footnote{Yes, that
it does not have it. Do not be confused,
not having features are often greater features.}
of perserving timestamps.

Perserving modification time on files is
considered harmful. Consider if Git were
to perserve the modification time. If you
have compiled the program, and then checkout
an earlier commit, perhaps another branch,
and you build it again, now your compiled
files from the other branch has a newer
timestamp then the source in the current branch
and the files will not build unless you
force them to build, which you more than
likely will forget. So you may observe a
behaviour of your program that is not defined
by the checked out source code.

This is way Git sets the timestamp to the
current time on every file it modifies, but
only those. Files that have not changes will
not change timestamp so the build system
will not rebuild them unless there is some
other reason it needs to.



@node Git and custom merge tools
@section Git and custom merge tools

Git lets you use custom automatic merge tools.
This can be used, for example, to merge binary
file formats. It is possible to use a merge
tool to required human interaction, however,
this is discouraged because than the commit
history will have no indication that there
was a merge conflict. You can use a merge tool
that tries to merge and marks all conflicts,
and then manually use a tool the lets you
see the conflicts and resolve.



@node Git and shared build caches
@section Git and shared build caches

A few set source controls systems have shared
build cache of derived objects. Git does not.
Build cache, private or public, is none of
source control systems' concern and should
be handled with tools made specifically for
just that.



@node Git and keyword expansion
@section Git and keyword expansion

About half of all source control systems
supports keyword expansion. As a feature,
Git does not. Keyword expansion causes
strange problems and is not really useful.
Nor it is a true task for source control
systems to implement, If can as successfully
be implemented with external tools, where
it belongs.



@node Git and links
@section Git and links

A Git repository will not grow larger if
you hard link a huge file over and over
again, not that you would ever want to…
However Git does not actually track hard
links.

Git supports symbolic links, and stores
the exact reference stored in the symlink,
it is not resolved or otherwise rewritten,
so make short you use relative references
in your symlinks.



@node Git and filenames
@section Git and filenames

Git treats filenames as byte sequences,
meaning that if it supports all characters
supported by your file system, including
one developers operativing systems uses
UTF-8 and the other's uses UTF-16, or
only ASCII, there will be problems. Will
it is true that systems really should use
UTF-8, be case sensitive and support
the entire Unicode, even characters that
are not yet defined with use of all 31
bits@footnote{Yes Unicode supports only  @c It is a shortcoming of English that this
up to 31 bits, so negative ordinals can  @c footnote cannot be expressed more clarily
be considered process private use.}      @c without significant length increase.
except the NUL control character, you
may consider just using lower case ASCII
and be friendly to other systems on use
a very restricted set of punctuation
and no control characters.



@node Git and merge tracking
@section Git and merge tracking

Git takes history seriously, therefore
when a merge is made, even if it can
be automatically fully merged, a commit
it created. This is very useful is
keep track of changes and identifing
and resolving evil merges. If you are
inclined to shoot your self in the
foot you can always rebase your
repository so that merges are not
created.



@node Git and empty directories
@section Git and empty directories

Git does not track empty directories,
it even removes them for you when
it remove all files in a directory.
Basically there is not reason to track
directories, ever, but if you are so
inclined you can add a @file{.gitignore}
file inside it.



@node Git and file renames
@section Git and file renames

The authors of Git believe that tracking
file names implicitly provide a more flexible
way to track how your tree is changing,
and less painful merging of patches.



@node Git and encoding convertions
@section Git and encoding convertions

Git can keep track of encoding for
commit metadata. Git does however not
convert file content, if your are indeed
inclined to want to shoot yourself in
the foot a filtering mechanism can be
used.



@node Git and atomic commits
@section Git and atomic commits

This might seem obvious, but CVS,
ClearCase and Visual SourceSafe
does not implement this; atomic
commits. Atomic commits refers to
a guarantee that an action cannot
be interrupted and leave in a
partially complete state but be
marked at complete, either all
changes are made or none at all.

Basically this means that first
you backup the reference to the
current commit, mark a file as a
commit is being saved, store
the new commit, update the reference
to the current commit to point at
the new commit and then mark that
no commit is being saved. If the
mark is then detected to say that
not commit is being save but instead
absolutely anything else, restore
the state in the same manner.



@node Beyond Git
@chapter Beyond Git

@menu
* Additional tools::                      Programs that you can use together with Git
* The binary problem::                    Binary files are evil agaist source control
* Writing commit messages::               How to write good commit messages
* Standard files::                        People have expections, and they should have
* Keeping the repository clean::          Good housekeeping is important
* A friendly build system::               Build systems makes the it easier for you and others
@end menu



@node Additional tools
@section Additional tools

Git is used for source control, for
a complete, possibily collaborative,
development environment you need
additional tools.

Everything Git can do, you can do in
the command line, but some repetitive
gets cumbersome in the command line
because you will need to run the same
command in unpredictable variations.
For this the package and command
@command{tig} may be just want you need
if you live in the terminal.

@command{bugseverywhere} is a great tool
for keeping track of issues in Git repositories.
Issues are commited to the current branch
you are working on, meaning that you can
have separate issues in separate branches.
So if you have separate branches for separate
features that are being implemented you can
create separate issues inside those branches.
And when a branch get merged with your develop
branch the unresolved issues is merged into
the develop branch.

If you are working on a large project with
multiple collaborator and contributors, and
you have dedicated hosting serve, you can
install Internet services that can assist
collaboration and especially contributors.
@itemize
@item
Flyspray is a web-based project management
and issue tracking system used by many projects.
@item
GNU Mailman is a projcet for managing electronic
mailing lists which can be very useful for
accepting patches.
@item
newsd is standalone NNTP server for centralised
newsgroup forum serving on a single server, which
can be very discussions.
@end itemize

All of these programs, as well as Git, are
released under the GNU General Public License,
except Flyspray which is released under the GNU
Lesser General Public License@footnote{Yeah, it
is a weird license for anything that is not
a library, but that is what it is what it is
released under.}.



@node The binary problem
@section The binary problem

Source control does not work well with binary
files. Consider that two persons are edition
the same file which cannot be interpreted by
a human using a text editor. If there is a
conflict, Git may not realise it depending on
the binary format, or may not be able to merge
the changes. If Git cannot merge the and you
cannot open it in a text editor, you will
not a file you can open and se the conflicts in
so you must open both's versions and manual
inspect and merge them.

Perhaps you plan to work alone and never ever
get another developer on your project and are
not convinced that merge conflicts reason
enough to work text based formats. Than consider
that you need to know the exact changes of
commits; the Git log will not be able to help
you if you are using binary formats.

Luckily most type of files formats have an
text based alternative.

@table @asis
@item Raster images
Portable Pixmap (.ppm, .pgm, .pbm, .pnm) is
a text based@footnote{Optionally partially
binary.} image format that is supported by
The GNU Image Manipulation Program (GIMP).
If you want transparency in your images,
Portable Arbitrary Map (.pam) is the best
well established format, however, it is
not widely supported --- but ImageMagick
and GraphicsMagick can be used to conversion
to Portable Network Graphics (.png) or almost
any other format, --- and only the headers
are in plain text.

@item Vector images
Scalable Vector@footnote{Yes it is redudant,
but that is really what it is called.} Graphics
(SVG) is the most popular vector image format,
and in fact it is text based, more precisely
it is XML based.
While you may not be able to view an SVG file
with merge conflicts, you are still able to
open it in a text editor and fix the conficts.
However it may not be the simplest thing to
resolve in a text editor it helps you to identify
where the conflicts are located in the graphics.

@item Documentation
Texinfo and @TeX{} are two very popular alternatives
to word editors such as LibreOffice.

Texinfo is designed for manuals and books, and
can be compiled to virtually any publish format,
including @command{info} manuals, Hypertext
Markup Language, Portable Document Format and
PostScript.

@TeX{} is more general purpose@footnote{Texinfo is
actually a macro set for @TeX{}.} has extensible and
redefinable syntax and is written to guarantee
that one source will always and everywhere produce
the exact same binaries, in terms of hows that
look when viewed. Its macro set @LaTeX{} is the
prefered office system in academia.
@end table



@node Writing commit messages
@section Writing commit messages

Commits are accompanied by messages. This
both helps yourself and other developers to
identify a specific commit of interest, as
well as giving information about what is
happening in the development process, so
every developer can keep up to speed.

Commit messages can also be used to create
changelogs, where you create a change log
from the commit history and filter out
unimportant changes.

Change logs and commit massages are generally
written on the same style. A short message
written in imperfect, optionally with additional
larges paragraphs that goes more in depth.

Even if your project is not in English it
is preferable to keep your commit message
as well as much as possible of your project
(that is not visible to the user) in English.
Assume your project is in Swedish, everyone
that understands Swedish will be able to
translate it to any other language. So far
it would be okay to write anything in Swedish,
but once it has been translated, for example
to English, additional translators that do
not understand Swedish can contribute with
additional translations. Now it is perferable
with English, while the translators can
understand everything that are should translate
they do not understand anything else.
When translating a program it useful to be
able to understand what the program does and
not just want it prints so you can do more
accurate translations, and sometimes just
one translation is not enough to have en
unambiguous understanding.

It is preferable to commit as often as
possible, however this interrupts your
mind flow, so committing should take
as short time as possible@footnote{Git is
very friendly in this respect as create
a commit is lightning fast, and photon
fast in comparsing to other old school
source control systems.}. Because of this
you may need to compromise your messages
--- which is not too bad because they are
accompanied by code, but never do it when
submitting patches or pull requests ---
one thing you can do is to not describe
a fix bug if it should be obvious for
the changeset@footnote{Can only be obvious
from small changes.}, after all if you
do not understand a change you can always
ask someone. Another thing you can do is
to use some standard shorthands.

@table @asis
@item m
Minor change.
@item doc
Add or change documentation.
@item typo
Fix a typo (a typing error.)
@item spello
Fix a spello (a spelling error.)
@item stylo
Fix a stylo (a literate style error.)
@item grammaro
Fix a grammaro (a grammatical error.)
@item style
Fix a coding style error or mistake.
@item ref
Abbreviation for `reference'.
@item dir
Abbreviation for `directory'.
@footnote{`Catalogue' and, for Windows folk, `folder' are synonyms for `directory'.}
@item conf
Abbreviation for `configuration' or `configure'.
@item misc
Abbreviation for `miscellaneous'.
@item +
As well as, another logical change
in the same commit.
@end table

If you want shorten the time it takes to
create a commit, I personally recommend
to have a short shell function for opening
your text editor and stage the openned
files when the editor exits. And create a
shell function the runs
@command{git commit -m "$*"}.



@node Standard files
@section Standard files

All projects should have a set of files:

@table @asis
@item @file{README} @i{(optional)}
You should have a readme file at the root
of your project. It should describe the
project and how the program is used.

@item @file{DEPENDENCIES} @i{(optional)}
If your program has other dependencies
than a compiler, linker, interpreter,
@command{libc}, @command{coreutils} and
similar standard packages, and make tools
such as @command{make} and @command{automake}.
You should have a file that list all
dependency: runtime dependencies, optional
runtime dependencies, build dependencies,
opt-out build dependencies, opt-in build
dependencies. Try to specify version range
and what the package is used for, especially
for optional dependecies.

@item @file{INSTALLING} @i{(optional)}
For more advanced build systems you should
have a file that specified how to configure
the building process.

@item @file{CONTRIBUTING} @i{(optional)}
If your have rules on how to submit patches,
code style guildlines, or other information
for contributors, you should have files
with all such information in the top of
your repository.

@item @file{HACKING} @i{(optional)}
For complex projects you can have a file
named @file{HACKING} with information
about how to modify the code.

@item @file{COPYING}
When you make your project available
it is not longer private software and
you need to give it a license compatible
with its dependencies. If you do not
have a license it defaults to being
proprietary. The copying file includes
the license summary or the complete
license text if it is short, and at
the top, the project name, short
description, years of active development,
and copyright holder name and e-mail
address. It is the same text as the
copyright information you put at the
top of source code files.

@item @file{LICENSE}
If the projects license is large, you
put the fill license plain text in the
file named @file{LICENSE} in the top
if your repository.
@end table



@node Keeping the repository clean
@section Keeping the repository clean

Keeping repositories clean is instrumental
in making it easy to maintains and simple
for new contributors to get started. Do
not commit binaries to repository, it should
only contain source files, this means that
you do not commit the program precompiled,
libraries the project is using and integrated
development environment (IDE) files.
You can however make exceptions for precompiled
non-programs that are compiled by your build
system if you think it is useful enough for
users to be available precompiled. For example
you can have a manual precompiled.

Your project can include directories such as:

@table @file
@item bin
This directory should not be committed, rather
it should be ignored and be created when
compiling the program, it should include linked
files such as commands, .so-files and .jar-file.

@item obj
This directory should not be committed, rather
it should be ignored and be created when
compiling the program, it should include
compiled but not linked files such as .o-files
and .class-file.

@item src
Put your source code it this directory.

@item dev
Auxiliary files and scripts used by developers,
such as code self tests, bisection commands,
and resource file inspection scripts.

@item contrib
Personally, I do not like this, but you
can use it for additional source that is not
required for the core of the package.

@item dist
If you are maintain package distribution
if your package of an operativing system
distribution, you can have directories
named @file{dist/DISTRIBUTION} for each
distribition. You may want to do this
this way because than other users can
look at it and start maintaining package
distribution of your package of the
operativing system distribution they
are using.

@item share
If you have of the following directories,
you can put all of them this directories
instead of in the root.

@item completion
All commands such have shell tab-completion,
if you are writing them individually for
each shell you can place them in this
directory.

@item manuals
If you write manuals in multiple formats
you can place them in this directory.

@item info
Every project should be well documented,
if you are this with texinfo, you can
put you texinfo files in this directory.

@item man
If your project have manpages, you can
place them in this directory.

@item po
Programs that used @command{gettext} for
translations can place the translations
in this directory.

@item *
Resource files can be places in a
directory named after their category.
@end table



@node A friendly build system
@section A friendly build system

`So I should not include project metafiles
use by my integrated development environment?'
No when you are doing that you are binding
everyone to your environment and you do not
provide everyone with a way to build your
package. Every package should be buildable
with a small set of commands that do not
require human interaction beyond type them
in a simple predictable manner in the command
line, ther is very important for package
distribution. To make possible for everyone
to build your program you can use GNU Autotools
or just a simple handwritten make file.

Additionally such a build system lets you
provide means to configure and customise the
build process as well as installing and
uninstalling (without using package management)
the program. Further, it allows you to compile
individual files and clean the directory
from all compiled files.



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



@node Glossary
@appendix Glossary

@table @asis
@item alternate object database
A repository can inherit part of its object
database from another object database, which
is called ``alternate''.

@item bare repositry
A bare repository is a repository without an
index tree or working tree. It just contains
the commits. Because it just contains the
commits it does not have a @file{.git} directory,
but instread directly contains the content
you would find in a @file{.git} directory.
If is normally named with @file{.git} is a
suffix.

@item blob object
Untyped object, for example, the contents of
a file.

@item branch
Alternative parallel development line, normally
indended the be merged with the branch it forked
out of.

@item cache
Obsolete, replaced by ‘index’.

@item chain
List of objects where each object has a reference
to the next object, its successor.

@item checkout
The action of changing branch.

@item cherry-picking
Creating a new commit from a subset of commits.

@item clean
A working tree is clean if has no changes
relative to the current @code{HEAD}

@item commit (noun)
A single point in the development history
stored in Git. The entire history of a project
is represented as a set of interrelated commits.

Alternatives to Git may use the terms `revision'
or `version' instead of `commit'. `Commit' is
also used as a short and for `commit object'.

@item commit (verb)
The action of storing a new snapshot of the
project's state. The state of the index is
stored and @code{HEAD} is advanced to the
new commit.

@item commit object
A Git internal object which contains the
information about a particalur revision.
It contains informations such as author,
commiter, date, files and parents.

@item core Git
The fundamental tools of source code management.

@item dangling object
An object that is not reachable, even from other
unreachable objects; there are not references to
it.

@item detached @code{HEAD}
@code{HEAD} that does not store the name of a
branch. Git allows you to checkout arbitrary
commmits, when you checkout a commit that is
not the tip of any branch, the @code{HEAD} is
``detached''.

To store changes make in a detached @code{HEAD}
you must first create a new branch from it.

@item directory
You may also know it as `catalogue' or even
`folder'. It can contain files and other
directories, which you can list with the
command @command{ls} and you can change directory
with the command @command{cd}.

@item dirty
The working tree is dirty if it contains uncommited
modifications.

@item evil merge
A merge that introduces changes that do not
appear in any parent. Variable name conflicts
can be a cause of evil merges. This is why you
do not rebase your commits. 

@item fast forward
The action of doing a fast-forward merge,
a pull for updates when Git branch is just
behind, not diverged.

@item fast-forward
A special type of merge that will often be
the case when you pull updates from a remote
repository. A fast-forward merge is a merge
where you have made no changes but there
are changes on the remote-tracking branch
that can be pulled without any merge logic.

@item fetch
When you fetch a branch's head ref from a
remote repository, you download, to a local
database, objects that have not yet been
downloaded.

@item gitfile
A plain file named @file{.git} located in
the root fo the working tree, that points
the to real repository.
The is a create idea to use this if you
do not want a backup repostory as it prevents
you from accidentally remove anything but
the working tree.

@item grafts
Two different development lines can be
join together by recoding facke ancestry
information. This is configured via the
@file{.git/info/grafts} file.

@item hash
Especially if cryptographic, almost unique,
indefeasibly reverable, fixed size, scrambling
of content. In Git's context, synonym for
object name.

@item head
A named reference to the commit at the tip
if a branch.

@item @code{HEAD}
The head of the currently checked out branch,
or the currently checkout commit in which case
the @code{HEAD} is ``detached''.

@item head ref
@itemx head reference
Synonym for `head'.

@item hook
Several Git commands make callouts to user
definable scripts. This allows developers to
add functionally or checkout, and commands
can be verified and aborted.

@file{.git/hooks} are filled with sample
scripts that can be enabled by removing their
@file{.sample} suffix.

@item index
Snapshot of the working tree intended to
be promoted to a commit.

@item index entry
The information regarding a particular file
that is stored in the index

@item master
Unless set otherwise, the default branch in
a repository. It is created with the first
commit in the project.

@item merge (verb)
The action of integrating the commits for
another development branch.

@item merge (noun)
A commit the is created when merging a
branch into another.

@item object
The unit of storage in Git. It is
identified by the SHA-1 hash of its
content.

@item object database
Stores a set of Git objects.

@item object identifier
Unique 40 character hexadecimal identifer of
an object, derived from the objects content,
by hashing with SHA-1.

@item object name
Synonym for object identifier.

@item object type
`Commit', `tree', `tag' or `blob'.

@item octopus
The action of mergin more than two branches.

@item origin
The default repository to push to, the one
you cloned.

@item pack
A set of objects that have been compressed.

@item pack index
A list of metadata for objects in a pack,
to speed up access time of individual
objects.

@c TODO @item pathspec
@c @item path specification

@item parent
Logical predecessor. The commit from which
a new commit is made is called the new commit's
parent. A merge have two or more parents, and
the first commit, or the first commit in an
orphaned branch, has no parents.

@c TODO @item pickaxe

@item plumbing
The fundamental tools of source code management.
Low-level commands.

@item porcelain
High-level commands.

@item pull
The action of integrate new commits from another
branch, often a remote-tracking branch.

@item push
The action of sending updates to a remote
repository.

@item reachable
All ancestors of a given commit are reachable
from that commit. This can be generallised to
chained objects.

@item rebase
The action of rewriting history by pretending
that you pulled updates before committing.

@item ref
@itemx reference
SHA-1 hash or name of a particular object.

@item reflog
@itemx reference log
Local history of a reference.

@item refspec
@itemx reference specification
Description of the mapping between ref and
local ref. Used by fetch and push.

@item remote-tracking branch
A reference to a brnach that is used to
follow changes in another repository.

@item repo.
@itemx repository
Database of development history.

@item resolve
The action of manually merging the parts
the tool could not automatically merge.

@item revision
A commit.

@item rewind
The action of throwing away part of the
development.

@item SHA-1
Secure Hash Algorithm 1, a cryptographic hash
function used by Git for object names. It is
the fastest secure hash algorithm around, bit
is is also quite old.

@item shallow repository
A repository with an incomplete commit history.

@item symref
@itemx symbolic reference
A reference that does not point to a SHA-1 ID,
but rather to another reference.

@c TODO @item tag
@c TODO @item tag object
@c TODO @item topic branch
@c TODO @item tree
@c TODO @item tree object
@c TODO @item tree-ish
@c TODO @item unmerged index
@c TODO @item unreachable object
@c TODO @item upstream branch
@c TODO @item working tree
@end table

@bye


TODO:

.git/config
man gitrepository-layout
man gitignore
man gitmodules


TODO: (late in the manual)

mirrors, but they are not safe!
man gitattributes
man githooks
man gitdiffcore
man gitcredentials
man gitnamespaces
man gitcore-tutorial