git-usage-howto
2005-04-07

This describes 'git' usage (mostly the 'git' "filesystem" or
plumbing, mostly omitting the git tools layer of programs and
scripts from Pasky and others... [which might be called
Cogito or tig] to be added later).

The examples come from using git on the git, sparse, and
kernel 'git' archives that are available at:
  http://www.kernel.org/pub/linux/kernel/people/torvalds/
(Note:  the "git-tools.git" files are tools that Linus
uses to merge PATCH emails into a source tree.)


__________________________________________________
Introduction/Background

'git' is a collection of file management tools that was created
by Linus Torvalds.  Its goal is to provide basic tools (the
plumbing) to do more interesting things at a layer above it
(the ease-of-use programs and scripts).  See its README file
for more descriptions.

__________________________________________________
"gits"

'git' operates on objects of types 'commit', 'tree', and
'blob'.  These objects are stored in the ".git" subdirectory
of the working repository.  'blob' objects can be anything.
They are typically source files (with some binary header
data), but they could also be binary blobs of anything.

"gits" (the collection of objects) are shared on the
internet, typically by using rsync.  E.g.:

$ rsync -avz -e ssh --progress \
  rsync://rsync.kernel.org/pub/linux/kernel/people/torvalds/git.git/ \
  git.git/

__________________________________________________
Objects

The .git subdirectory for a repository contains an 'index'
file which is local to your source tree (not normally
shared with other users, local or remote).  [The 'index'
file is in host-endian byte order.]  This represents the
list of source files in the tree.  The 'HEAD' file, which
is shared whenever the 'git' is shared, represents the
latest committed branch of the tree.  The 'objects'
subdirectory contains all of the tree's objects (tree,
commit, and blob) in SHA1 filename format with one
subdirectory level of indirection.  I.e., all objects
are SHA1-hashed into a 40-hex-character filename, and then
stored in objects/xy/z{38} by splitting the SHA1 hash
into 2 characters + 38 characters.  E.g., 'HEAD' contains
  2f1a7596e4cf445102e89b8323c7857fc8b1fd89
and this object is stored in
  objects/2f/1a7596e4cf445102e89b8323c7857fc8b1fd89

Note:  Whenever an object (e.g., a source file) is
modified and updated, the complete new version of the
file is stored as a git object.  There is no delta or
diff file storage in git.

__________________________________________________
Example:  get git

You have to have 'git' before you can use it, so begin
by getting the latest version which contains checked-out
files (to bootstrap to the current version):
  download git-0.04.tar.{gz,bz2} from
  http://www.kernel.org/pub/linux/kernel/people/torvalds/
and build this:
	$ tar x{zj}f git-0.04.tar.*
	$ cd git-0.04
	$ make
	$ make install	# to ~/bin


Now you can use this version of 'git' to get updated
versions, so do that now:

Download the current git.git cache by using the rsync command
above.  E.g.:

	$ cd ~		# or wherever you want to do this
	$ mkdir git.repo
	$ cd git.repo
	$ rsync (... as above ...)
	$ mv git.git .git

Now use the git-0.04 executables to get the current git 'objects':

Oops, git-0.04 expects the objects cache to live in the
.dircache subdirectory.  This was later changed to be the
.git subdirectory.  For now, just make a symlink:

	$ ln -s .git .dircache

Here are the steps to see what is in the git.  You can skip
some of these after you know what you are doing.

Get the current HEAD of the commit tree:

	$ cat .git/HEAD
	bb95843a5a0f397270819462812735ee29796fb4

It should be a 'commit' object.  Verify this by testing
(-t) the object:

	$ cat-file -t `cat .git/HEAD`
	commit

Get the HEAD commit description:

	$ cat-file commit `cat .git/HEAD`
	tree 1756b578489f93999ded68ae347bef7d6063101c
	parent 9f02d4d233223462d3f6217b5837b786e6286ba4
	author Linus Torvalds <torvalds@ppc970.osdl.org> Thu Apr 14 00:37:23 2005
	committer Linus Torvalds <torvalds@ppc970.osdl.org> Thu Apr 14 00:37:23 2005

	Add "merge-tree" helper program. Maybe it's retarded, maybe it's helpful.

	It only works one directory level at a time, so lookout..

Populate the index (or cache) for that tree:

	$ read-tree 1756b578489f93999ded68ae347bef7d6063101c

Read the current index files:

	$ checkout-cache -a
	$ ls		# lists about 20 files

Now build and install the current version of git:
	$ make && make install

Now you can move on to larger gits, like linux-kernel or
sparse....

TBD:  using kernel-git....

__________________________________________________
git Command Reference
__________________________________________________

Check current directory cache
	show-diff


If there are file differences listed, you can refresh
the cache with
	update-cache <filenames>


Manual checkin
	<modify one or more files>
	write-tree	# prints a 'tree' object


Commit tree updates
	commit-tree <tree-sha> [-p <parent-sha>]*
	with changelog from stdin or from prompt;
	parent-sha is often `cat .dircache/HEAD`
	# prints a 'commit' object, which should be
	written as the new value of .dircache/HEAD

###