GitFlyThrough < Training

---+ Git flythrough

---++ Version used in this document (at least)

<verbatim>
[dzu@pollux u-boot]$ git --version
git version 1.5.3.1
</verbatim>

---+ Technical introduction

---++ Underlying concepts

   * git is a very fast directory content manager
   * only one "data type" in the database with 4 sub-types
     blob, tree, commit, tag
   * every object is stored under its SHA1 hash (=content) <BRK>
     -> Immediate integrity check possible
   * objects are _never_ modified
   * blobs hold the actual data (without its name or mode!)
   * trees are mappings from (mode,name) tuples to objects
     (blobs or trees)
   * a commit refers to a tree and its parent commits
   * a tag refers to a commit optionally using a signature

   * Thus commits form a DAG (directed acyclic graph) forming the whole
     history.

   * A specific "version" (or state of the directory hierarchy) is thus
     fully identified by the SHA1 of a commit.

   * A full history can be signed by signing a single tag as there is no
     way to change history because all references are _to content_.

   * git repositories are fully symmetric, i.e. there is no master/slave
     but only a (light) "origin/clone" relation.

Programmatically git is a collection of small user space programs
exposing all the "bolts and nuts" in the typical unix fashion (called
"plumbing", e.g. git-cat-file).

[Sidenote: this allowed for very rapid prototyping in a script
 language and subsequently optimizing critical parts in C]

Git also includes "porcelain" commands (e.g. git-show") to work with
the core plumbing programs. Other porcelains are possible of course.

---++ Basic interaction with the object database

   * one always works on an "unfolded" tree object (git-checkout)
   * only for efficiency this is cached in the index
   * Changes in the files can be checked very fast against
     the index
   * usually the index is fully transparent
   * make changes to the working tree and "import to the index"
    (git-add, git-remove)
   * finally commit the state to the database (git-commit)

---+ Working examples

Cf. http://www.kernel.org/pub/software/scm/git/docs/

---++ Check out master repository

---+++ Elegant ways top check out a repository:

---++++ Normal clone

<verbatim>
[dzu@pollux dzu]$ git clone /home/git/u-boot
Initialized empty Git repository in /tmp/dzu/u-boot/.git/
remote: Generating pack...
remote: Done counting 44005 objects.
remote: Deltifying 44005 objects...
remote:  100% (44005/44005) done
Indexing 44005 objects...
remote: Total 44005 (delta 35236), reused 42526 (delta 33832)
 100% (44005/44005) done
Resolving 35236 deltas...
 100% (35236/35236) done

[dzu@pollux dzu]$ du -hs u-boot/
74M  u-boot/
</verbatim>

---++++ Using alternates

<verbatim>
[dzu@pollux dzu]$ rm -rf u-boot/
[dzu@pollux dzu]$ git clone -s /home/git/u-boot
Initialized empty Git repository in /tmp/dzu/u-boot/.git/

[dzu@pollux dzu]$ du -hs u-boot.
53M u-boot/
[dzu@pollux dzu]$ 
</verbatim>

---++ Using remotes in an U-Boot example

<verbatim>
[dzu@pollux u-boot]$ git clone /home/git/u-boot
Initialized empty Git repository in /tmp/dzu/u-boot/u-boot/.git/
remote: Generating pack...
remote: Done counting 44005 objects.
remote: Deltifying 44005 objects...
remote:  100% (44005/44005) done
Indexing 44005 objects...
remote: Total 44005 (delta 35236), reused 42526 (delta 33832)
 100% (44005/44005) done
Resolving 35236 deltas...
 100% (35236/35236) done

[dzu@pollux u-boot]$ cd u-boot
[dzu@pollux u-boot]$ git remote add -f 4xx git://www.denx.de/git/u-boot-ppc4xx
remote: Generating pack...
remote: Done counting 0 objects.
remote: Total 0 (delta 0), reused 0 (delta 0)
Unpacking 0 objects...
...
[dzu@pollux u-boot]$ git remote add -f testing git://www.denx.de/git/u-boot-testing
...
[dzu@pollux u-boot]$ 
</verbatim>

---+ Powerful tools

---++ Introducing yourself to git

   * git config --global user.email dzu@denx.de
   * git config --global user.name "Detlev Zundel"

---++ Looking for whats there

   * git branch [-a]
   * git tag [-a] -l
   * git log

---++ "Seeking in time"

   1 Only for viewing/compiling: git checkout testing/master
   1 To work, crate a (temp.) branch: git checkout -b work U-Boot-1_2_0

---++ Inspecting state

   * git status
   * git diff [--stat]

---++ Resetting to "unfolded tree"

   * git reset --hard HEAD

---++ "Addressing" versions and inspecting "traces"

   * git show testing/master:Makefile
   * git show HEAD^

---++ Comparing trees and files

   * git diff --stat testing/master..origin/master
   * git diff testing/master:Makefile origin/master:Makefile

---++ Show history of files

   * git log -p Makefile
   * git blame Makefile
   * git log -p U-Boot-1_2_0.. board/amcc/taishan

---++ Commiting work

   1 git add <files>
   1 git commit -s

or

   * git commit -a -s

---++ Generating patches

Custodian:

<verbatim>
git checkout -b work U-Boot_1_2_0
   [edit, change, commit]
git format-patch -n `git-merge-base HEAD origin/master`
git send-email [--thread] 00*
</verbatim>

Maintainer:

<verbatim>
[Collect patches in standard mailbox file mbox]
git am mbox
</verbatim>

---++ Rebasing branches (and thus patches)

   * git checkout work
   * git rebase origin/master

---++ Pushing and pulling

Update master branch (fetching + merging):

   1 git checkout master
   1 git pull

Sync up to all remotes also (no merging done):

   * git fetch -a

Push changes through ssh:

   * git push ssh://[user@]host.xz[:port]/path/to/repo.git/

---++ Merging branches

   1 git checkout origin/master
   1 git merge testing/master

---++ Removing branches and cleaning up

   1 git branch -d work
   1 git gc

---+ Goodies

---++ Find tags:

   * git describe origin/master

---++ Generate pull requests automatically

   * git request-pull U-Boot-1_2_0 git://www.denx.de/git/u-boot-ppc4xx

---++ git-bisect

Checkout "bad" version.

   1 git bisect start
   1 git bad
   1 git good ...

Now a position "in the middle" is checked out for testing.  Tell the
system by

git-bisect good or git-bisect bad

Git tells you when the culprit was isolated.

<verbatim>
good - f5577aae4aa9f245c4c67308fe0f7b3cecf61c93
  (needs "fixup", e.g. touch examples/hello_world.{srec,bin})
bad - 8318fbf8cc30418b621ea9f39b84b4c1a08f003a

[dzu@pollux u-boot]$ git-bisect reset
[dzu@pollux u-boot]$ git-bisect start
[dzu@pollux u-boot]$ git-bisect good
f5577aae4aa9f245c4c67308fe0f7b3cecf61c93
[dzu@pollux u-boot]$ git-bisect bad
8318fbf8cc30418b621ea9f39b84b4c1a08f003a
Bisecting: 35 revisions left to test after this
[854bc8da75709f13dab4cfa6e9094c0cb49b5c5a] Add support for AMCC
Rainier PPX440GRx eval board
[dzu@pollux u-boot]$

... make ... bad 
... make ... bad
... make ... bad
... make ... good
... make ... good

[dzu@pollux u-boot]$ git-bisect bad
Bisecting: 0 revisions left to test after this
[d7c2a02dea550e8701d1151010a823df48ad5c98] Added simple_strtoul(),
getenv() and setenv() to the exported functions.
[dzu@pollux u-boot]$
</verbatim>

Further reading:

   * git bisect visualize
   * git bisect log
    (ignore suggestion, e.g. git-reset --hard HEAD~3)
   * git bisect start -- arch/ppc  include/asm-ppc (narrow down search)
   * git bisect run <script>


---++ [Experts only] Find first tag a board was supported in

   * git describe --contains `git-rev-list HEAD -- board/amcc/sequoia/Makefile | tail -1`


-- Main.DetlevZundel - 11 Sep 2007