<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Git File format — dulwich 0.10.0 documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.10.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="dulwich 0.10.0 documentation" href="../index.html" />
<link rel="up" title="Tutorial" href="index.html" />
<link rel="next" title="The repository" href="repo.html" />
<link rel="prev" title="Introduction" href="introduction.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="repo.html" title="The repository"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="introduction.html" title="Introduction"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">dulwich 0.10.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Tutorial</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="git-file-format">
<h1>Git File format<a class="headerlink" href="#git-file-format" title="Permalink to this headline">¶</a></h1>
<p>For a better understanding of Dulwich, we’ll start by explaining most of the
Git secrets.</p>
<p>Open the ”.git” folder of any Git-managed repository. You’ll find folders
like “branches”, “hooks”... We’re only interested in “objects” here. Open it.</p>
<p>You’ll mostly see 2 hex-digits folders. Git identifies content by its SHA-1
digest. The 2 hex-digits plus the 38 hex-digits of files inside these folders
form the 40 characters (or 20 bytes) id of Git objects you’ll manage in
Dulwich.</p>
<p>We’ll first study the three main objects:</p>
<ul class="simple">
<li>The Commit;</li>
<li>The Tree;</li>
<li>The Blob.</li>
</ul>
<div class="section" id="the-commit">
<h2>The Commit<a class="headerlink" href="#the-commit" title="Permalink to this headline">¶</a></h2>
<p>You’re used to generate commits using Git. You have set up your name and
e-mail, and you know how to see the history using <tt class="docutils literal"><span class="pre">git</span> <span class="pre">log</span></tt>.</p>
<p>A commit file looks like this:</p>
<div class="highlight-python"><pre>commit <content length><NUL>tree <tree sha>
parent <parent sha>
[parent <parent sha> if several parents from merges]
author <author name> <author e-mail> <timestamp> <timezone>
committer <author name> <author e-mail> <timestamp> <timezone>
<commit message></pre>
</div>
<p>But where are the changes you commited? The commit contains a reference to a
tree.</p>
</div>
<div class="section" id="the-tree">
<h2>The Tree<a class="headerlink" href="#the-tree" title="Permalink to this headline">¶</a></h2>
<p>A tree is a collection of file information, the state of a single directory at
a given point in time.</p>
<p>A tree file looks like this:</p>
<div class="highlight-python"><pre>tree <content length><NUL><file mode> <filename><NUL><item sha>...</pre>
</div>
<p>And repeats for every file in the tree.</p>
<p>Note that the SHA-1 digest is in binary form here.</p>
<p>The file mode is like the octal argument you could give to the <tt class="docutils literal"><span class="pre">chmod</span></tt>
command. Except it is in extended form to tell regular files from
directories and other types.</p>
<p>We now know how our files are referenced but we haven’t found their actual
content yet. That’s where the reference to a blob comes in.</p>
</div>
<div class="section" id="the-blob">
<h2>The Blob<a class="headerlink" href="#the-blob" title="Permalink to this headline">¶</a></h2>
<p>A blob is simply the content of files you are versionning.</p>
<p>A blob file looks like this:</p>
<div class="highlight-python"><pre>blob <content length><NUL><content></pre>
</div>
<p>If you change a single line, another blob will be generated by Git at commit
time. This is how Git can fastly checkout any version in time.</p>
<p>On the opposite, several identical files with different filenames generate
only one blob. That’s mostly how renames are so cheap and efficient in Git.</p>
</div>
<div class="section" id="dulwich-objects">
<h2>Dulwich Objects<a class="headerlink" href="#dulwich-objects" title="Permalink to this headline">¶</a></h2>
<p>Dulwich implements these three objects with an API to easily access the
information you need, while abstracting some more secrets Git is using to
accelerate operations and reduce space.</p>
</div>
<div class="section" id="more-about-git-formats">
<h2>More About Git formats<a class="headerlink" href="#more-about-git-formats" title="Permalink to this headline">¶</a></h2>
<p>These three objects make up most of the contents of a Git repository and are
used for the history. They can either appear as simple files on disk (one file
per object) or in a <tt class="docutils literal"><span class="pre">pack</span></tt> file, which is a container for a number of these
objects.</p>
<p>The is also an index of the current state of the working copy in the
repository as well as files to track the existing branches and tags.</p>
<p>For a more detailed explanation of object formats and SHA-1 digests, see:
<a class="reference external" href="http://www-cs-students.stanford.edu/~blynn/gitmagic/ch08.html">http://www-cs-students.stanford.edu/~blynn/gitmagic/ch08.html</a></p>
<p>Just note that recent versions of Git compress object files using zlib.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Git File format</a><ul>
<li><a class="reference internal" href="#the-commit">The Commit</a></li>
<li><a class="reference internal" href="#the-tree">The Tree</a></li>
<li><a class="reference internal" href="#the-blob">The Blob</a></li>
<li><a class="reference internal" href="#dulwich-objects">Dulwich Objects</a></li>
<li><a class="reference internal" href="#more-about-git-formats">More About Git formats</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="introduction.html"
title="previous chapter">Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="repo.html"
title="next chapter">The repository</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/tutorial/file-format.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="repo.html" title="The repository"
>next</a> |</li>
<li class="right" >
<a href="introduction.html" title="Introduction"
>previous</a> |</li>
<li><a href="../index.html">dulwich 0.10.0 documentation</a> »</li>
<li><a href="index.html" >Tutorial</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2011, Jelmer Vernooij.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
