docs/tutorial/0-introduction.txt

   1 ================
   2 Dulwich Tutorial
   3 ================
   4
   5 Introduction
   6 ============
   7
   8 Git repository format
   9 ---------------------
  10
  11 For a better understanding of Dulwich, we'll start by explaining most of the
  12 Git secrets.
  13
  14 Open the ".git" folder of any Git-managed repository. You'll find folders
  15 like "branches", "hooks"... We're only interested in "objects" here. Open it.
  16
  17 You'll mostly see 2 hex-digits folders. Git identifies content by its SHA-1
  18 digest. The 2 hex-digits plus the 38 hex-digits of files inside these folders
  19 form the 40 characters (or 20 bytes) id of Git objects you'll manage in
  20 Dulwich.
  21
  22 We'll first study the three main objects:
  23
  24 - The Commit;
  25
  26 - The Tree;
  27
  28 - The Blob.
  29
  30 The Commit
  31 ----------
  32
  33 You're used to generate commits using Git. You have set up your name and
  34 e-mail, and you know how to see the history using "git log".
  35
  36 A commit file looks like this::
  37
  38   commit <content length><NUL>tree <tree sha>
  39   parent <parent sha>
  40   [parent <parent sha> if several parents from merges]
  41   author <author name> <author e-mail> <timestamp> <timezone>
  42   committer <author name> <author e-mail> <timestamp> <timezone>
  43
  44   <commit message>
  45
  46 But where are the changes you commited? The commit contains a reference to a
  47 tree.
  48
  49 The Tree
  50 --------
  51
  52 A tree is a collection of file information, the state of your working copy at
  53 a given point in time.
  54
  55 A tree file looks like this::
  56
  57   tree <content length><NUL><file mode> <filename><NUL><blob sha>...
  58
  59 And repeats for every file in the tree. A real example from Dulwich itself::
  60
  61 Note that for a unknown reason, the SHA-1 digest is in binary form here.
  62
  63 The file mode is like the octal argument you could give to the "chmod"
  64 command.  Except it is in extended form to tell regular files from
  65 directories and other types.
  66
  67 We now know how our files are referenced but we haven't found their actual
  68 content yet. That's where the reference to a blob comes in.
  69
  70 The Blob
  71 --------
  72
  73 A blob is simply the content of files you are versionning.
  74
  75 A blob file looks like this::
  76
  77   blob <content length><NUL><content>
  78
  79 If you change a single line, another blob will be generated by Git at commit
  80 time. This is how Git can fastly checkout any version in time.
  81
  82 On the opposite, several identical files with different filenames generate
  83 only one blob. That's mostly how renames are so cheap and efficient in Git.
  84
  85 Dulwich Objects
  86 ---------------
  87
  88 Dulwich implements these three objects with an API to easily access the
  89 information you need, while abstracting some more secrets Git is using to
  90 accelerate operations and reduce space.
  91
  92 More About Git formats
  93 ----------------------
  94
  95 These three objects make 90 % of a Git repository. The rest is branch
  96 information and optimizations.
  97
  98 For instance there is an index of the current state of the working copy.
  99 There are also pack files to group several small objects in a single indexed
 100 file.
 101
 102 You'll find more detailled explanations and examples here:
 103 http://www-cs-students.stanford.edu/~blynn/gitmagic/ch08.html
 104
 105 Just note that recent versions of Git compress object files using zlib.