diff options
Diffstat (limited to '.html/git/theory-and-practice')
| -rw-r--r-- | .html/git/theory-and-practice/_list.html | 96 | ||||
| -rw-r--r-- | .html/git/theory-and-practice/index.html | 126 | ||||
| -rw-r--r-- | .html/git/theory-and-practice/objects.html | 202 | ||||
| -rw-r--r-- | .html/git/theory-and-practice/refs-and-names.html | 199 |
4 files changed, 623 insertions, 0 deletions
diff --git a/.html/git/theory-and-practice/_list.html b/.html/git/theory-and-practice/_list.html new file mode 100644 index 0000000..feae190 --- /dev/null +++ b/.html/git/theory-and-practice/_list.html @@ -0,0 +1,96 @@ +<!DOCTYPE html> +<html> +<head> + <title> + The Codex » + ls /git/theory-and-practice + </title> + + <link + rel='stylesheet' + type='text/css' + href='http://fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/reset.css"> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/grimoire.css"> +</head> +<body> + +<div id="shell"> + + <ol id="breadcrumbs"> + + <li class="crumb-0 not-last"> + + <a href="../../">index</a> + + </li> + + <li class="crumb-1 not-last"> + + <a href="../">git</a> + + </li> + + <li class="crumb-2 not-last"> + + <a href="./">theory-and-practice</a> + + </li> + + <li class="crumb-3 last"> + + <span class="list-crumb">list</span> + + </li> + + </ol> + + + + <div id="listing"> + <h1><code>ls /git/theory-and-practice</code></h1> + + + + + <div id="pages"> + <h2>Pages</h2> + <ul> + + <li><a href="objects">Objects</a></li> + + <li><a href="refs-and-names">Refs and Names</a></li> + + </ul> + </div> + + + + </div> + + + + + + + <div id="footer"> + <p> + + The Codex — + + Powered by <a href="http://markdoc.org/">Markdoc</a>. + +<a href="https://bitbucket.org/ojacobson/grimoire.ca/src/master/wiki/git/theory-and-practice">See this directory on Bitbucket</a>. + + </p> + </div> + +</div> +</body> +</html>
\ No newline at end of file diff --git a/.html/git/theory-and-practice/index.html b/.html/git/theory-and-practice/index.html new file mode 100644 index 0000000..297cbd9 --- /dev/null +++ b/.html/git/theory-and-practice/index.html @@ -0,0 +1,126 @@ +<!DOCTYPE html> +<html> +<head> + <title> + The Codex » + Git Internals 101 + </title> + + <link + rel='stylesheet' + type='text/css' + href='http://fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/reset.css"> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/grimoire.css"> +</head> +<body> + +<div id="shell"> + + <ol id="breadcrumbs"> + + <li class="crumb-0 not-last"> + + <a href="../../">index</a> + + </li> + + <li class="crumb-1 not-last"> + + <a href="../">git</a> + + </li> + + <li class="crumb-2 last"> + + theory-and-practice + + </li> + + </ol> + + + + <div id="article"> + <h1 id="git-internals-101">Git Internals 101</h1> +<p>Yeah, yeah, another article about “how Git works.” There are tons of these +already. Personally, I'm fond of Sitaram Chamarty's <a href="http://gitolite.com/master-toc.html">fantastic series of +articles</a> explaining Git from both ends, +and of <a href="http://eagain.net/articles/git-for-computer-scientists/">Git for Computer +Scientists</a>. Maybe +you'd rather read those.</p> +<p>This page was inspired by very specific, recurring issues I've run into while +helping people use Git. I think Git's “porcelain” layer -- its user interface +-- is terrible, and does a bad job of insulating non-expert users from Git's +internals. While I'd love to fix that (and I do contribute to discussions on +that front, too), we still have the <code>git(1)</code> UI right now and people still get +into trouble with it right now.</p> +<p>Git follows the New Jersey approach laid out in Richard Gabriel's <a href="http://www.dreamsongs.com/RiseOfWorseIsBetter.html">The Rise of +“Worse is Better”</a>: given +the choice between a simple implementation and a simple interface, Git chooses +the simple implementation almost everywhere. This internal simplicity can give +users the leverage to fix the problems that its horrible user interface leads +them into, so these pages will focus on explaining the simple parts and giving +users the tools to examine them.</p> +<p>Throughout these articles, I've written “Git does X” a lot. Git is +<em>incredibly</em> configurable; read that as “Git does X <em>by default</em>.” I'll try to +call out relevant configuration options as I go, where it doesn't interrupt +the flow of knowledge.</p> +<ul> +<li><a href="objects">Objects</a></li> +<li><a href="refs-and-names">Refs and Names</a></li> +</ul> +<p>By the way, if you think you're just going to follow the +<a href="http://git-scm.com/documentation">many</a> +<a href="http://www.atlassian.com/git/tutorial">excellent</a> +<a href="http://try.github.io/levels/1/challenges/1">git</a> +<a href="https://www.kernel.org/pub/software/scm/git/docs/gittutorial.html">tutorials</a> +out there and that you won't need this knowledge, well, you will. You can +either learn it during a quiet time, when you can think and experiment, or you +can learn it when something's gone wrong, and everyone's shouting at each +other. Git's high-level interface doesn't do much to keep you on the sensible +path, and you will eventually need to fix something.</p> + </div> + + + +<div id="comments"> +<div id="disqus_thread"></div> +<script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'grimoire'; // required: replace example with your forum shortname + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); +</script> +<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript> +<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a> +</div> + + + + <div id="footer"> + <p> + + The Codex — + + Powered by <a href="http://markdoc.org/">Markdoc</a>. + +<a href="https://bitbucket.org/ojacobson/grimoire.ca/src/master/wiki/git/theory-and-practice/index.md">See this page on Bitbucket</a> (<a href="https://bitbucket.org/ojacobson/grimoire.ca/history-node/master/wiki/git/theory-and-practice/index.md">history</a>). + + </p> + </div> + +</div> +</body> +</html>
\ No newline at end of file diff --git a/.html/git/theory-and-practice/objects.html b/.html/git/theory-and-practice/objects.html new file mode 100644 index 0000000..ff6c53b --- /dev/null +++ b/.html/git/theory-and-practice/objects.html @@ -0,0 +1,202 @@ +<!DOCTYPE html> +<html> +<head> + <title> + The Codex » + Objects + </title> + + <link + rel='stylesheet' + type='text/css' + href='http://fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/reset.css"> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/grimoire.css"> +</head> +<body> + +<div id="shell"> + + <ol id="breadcrumbs"> + + <li class="crumb-0 not-last"> + + <a href="../../">index</a> + + </li> + + <li class="crumb-1 not-last"> + + <a href="../">git</a> + + </li> + + <li class="crumb-2 not-last"> + + <a href="./">theory-and-practice</a> + + </li> + + <li class="crumb-3 last"> + + objects + + </li> + + </ol> + + + + <div id="article"> + <h1 id="objects">Objects</h1> +<p>Git's basest level is a storage and naming system for things Git calls +“objects.” These objects hold the bulk of the data about files and projects +tracked by Git: file contents, directory trees, commits, and so on. Every +object is identified by a SHA-1 hash, which is derived from its contents.</p> +<p>SHA-1 hashes are obnoxiously long, so Git allows you to substitue any unique +prefix of a SHA-1 hash, so long as it's at least four characters long. If the +hash <code>0b43b9e3e64793f5a222a644ed5ab074d8fa1024</code> is present in your repository, +then Git commands will understand <code>0b43</code>, <code>0b43b9</code>, and other patterns to all +refer to the same object, so long as no other object has the same SHA-1 +prefix.</p> +<h2 id="blobs">Blobs</h2> +<p>The contents of every file that's ever been stored in a Git repository are +stored as <code>blob</code> objects. These objects are very simple: they contain the file +contents, byte for byte.</p> +<h2 id="trees">Trees</h2> +<p>File contents (and trees, and Other Things we'll get to later) are tied +together into a directory structure by <code>tree</code> objects. These objects contain a +list of records, with one child per record. Each record contains a permissions +field corresponding to the POSIX permissions mask of the object, a type, a +SHA-1 for another object, and a name.</p> +<p>A directory containing only files might be represented as the tree</p> +<pre><code>100644 blob 511542ad6c97b28d720c697f7535897195de3318 config.md +100644 blob 801ddd5ae10d6282bbf36ccefdd0b052972aa8e2 integrate.md +100644 blob 61d28155862607c3d5d049e18c5a6903dba1f85e scratch.md +100644 blob d7a79c144c22775239600b332bfa120775bab341 survival.md +</code></pre> +<p>while a directory with subdirectories would also have some <code>tree</code> children:</p> +<pre><code>040000 tree f57ef2457a551b193779e21a50fb380880574f43 12factor +040000 tree 844697ce99e1ef962657ce7132460ad7a38b7584 authnz +100644 blob 54795f9b774547d554f5068985bbc6df7b128832 cool-urls-can-change.md +040000 tree fc3f39eb5d1a655374385870b8be56b202be7dd8 dev +040000 tree 22cbfb2c1d7b07432ea7706c36b0d6295563c69c devops +040000 tree 0b3e63b4f32c0c3acfbcf6ba28d54af4c2f0d594 git +040000 tree 5914fdcbd34e00e23e52ba8e8bdeba0902941d3f java +040000 tree 346f71a637a4f8933dc754fef02515a8809369c4 mysql +100644 blob b70520badbb8de6a74b84788a7fefe64a432c56d packaging-ideas.md +040000 tree 73ed6572345a368d20271ec5a3ffc2464ac8d270 people +</code></pre> +<h2 id="commits">Commits</h2> +<p>Blobs and trees are sufficient to store arbitrary directory trees in Git, and +you could use them that way, but Git is mostly used as a revision-tracking +system. Revisions and their history are represented by <code>commit</code> objects, which contain:</p> +<pre><code>* The SHA-1 hash of the root `tree` object of the commit, +* Zero or more SHA-1 hashes for parent commits, +* The name and email address of the commit's “author,” +* The name and email address of the commit's “committer,” +* Timestamps representing when the commit was authored and committed, and +* A commit message. +</code></pre> +<p>Commit objects' parent references form a directed acyclic graph; the subgraph +reachable from a specific commit is that commit's <em>history</em>.</p> +<p>When working with Git's user interface, commit parents are given in a +predictable order determined by the <code>git checkout</code> and <code>git merge</code> commands.</p> +<h2 id="tags">Tags</h2> +<p>Git's revision-tracking system supports “tags,” which are stable names for +specific configurations. It also, uniquely, supports a concept called an +“annotated tag,” represented by the <code>tag</code> object type. These annotated tag +objects contain</p> +<pre><code>* The type and SHA-1 hash of another object, +* The name and email address of the person who created the tag, +* A timestamp representing the moment the tag was created, and +* A tag message. +</code></pre> +<h2 id="anonymity">Anonymity</h2> +<p>There's a general theme to Git's object types: no object knows its own name. +Every object only has a name in the context of some containing object, or in +the context of <a href="refs-and-names">Git's refs mechanism</a>, which I'll get to +shortly. This means that the same <code>blob</code> object can be reused for multiple +files (or, more probably, the same file in multiple commits), if they happen +to have the same contents.</p> +<p>This also applies to tag objects, even though their role is part of a system +for providing stable, meaningful names for commits.</p> +<h2 id="examining-objects">Examining objects</h2> +<ul> +<li> +<p><code>git cat-file <type> <sha1></code>: decodes the object <code><sha1></code> and prints its + contents to stdout. This prints the object's contents in their raw form, + which is less than useful for <code>tree</code> objects.</p> +</li> +<li> +<p><code>git cat-file -p <sha1></code>: decodes the object <code><sha1></code> and pretty-prints it. + This pretty-printing stays close to the underlying disk format; it's most + useful for decoding <code>tree</code> objects.</p> +</li> +<li> +<p><code>git show <sha1></code>: decodes the object <code><sha1></code> and formats its contents to + stdout. For blobs, this is identical to what <code>git cat-file blob</code> would do, + but for trees, commits, and tags, the output is reformated to be more + readable.</p> +</li> +</ul> +<h2 id="storage">Storage</h2> +<p>Objects are stored in two places in Git: as “loose objects,” and in “pack +files.” Newly-created objects are initially loose objects, for ease of +manipulation; transferring objects to another repository or running certain +administrative commands can cause them to be placed in pack files for faster +transfer and for smaller storage.</p> +<p>Loose objects are stored directly on the filesystem, in the Git repository's +<code>objects</code> directory. Git takes a two-character prefix off of each object's +SHA-1 hash, and uses that to pick a subdirectory of <code>objects</code> to store the +object in. The remainder of the hash forms the filename. Loose objects are +compressed with zlib, to conserve space, but the resulting directory tree can +still be quite large.</p> +<p>Packed objects are stored together in packed files, which live in the +repository's <code>objects/pack</code> directory. These packed files are both compressed +and delta-encoded, allowing groups of similar objects to be stored very +compactly.</p> + </div> + + + +<div id="comments"> +<div id="disqus_thread"></div> +<script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'grimoire'; // required: replace example with your forum shortname + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); +</script> +<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript> +<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a> +</div> + + + + <div id="footer"> + <p> + + The Codex — + + Powered by <a href="http://markdoc.org/">Markdoc</a>. + +<a href="https://bitbucket.org/ojacobson/grimoire.ca/src/master/wiki/git/theory-and-practice/objects.md">See this page on Bitbucket</a> (<a href="https://bitbucket.org/ojacobson/grimoire.ca/history-node/master/wiki/git/theory-and-practice/objects.md">history</a>). + + </p> + </div> + +</div> +</body> +</html>
\ No newline at end of file diff --git a/.html/git/theory-and-practice/refs-and-names.html b/.html/git/theory-and-practice/refs-and-names.html new file mode 100644 index 0000000..fdc56a4 --- /dev/null +++ b/.html/git/theory-and-practice/refs-and-names.html @@ -0,0 +1,199 @@ +<!DOCTYPE html> +<html> +<head> + <title> + The Codex » + Refs and Names + </title> + + <link + rel='stylesheet' + type='text/css' + href='http://fonts.googleapis.com/css?family=Buenard:400,700&subset=latin,latin-ext'> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/reset.css"> + <link + rel="stylesheet" + type="text/css" + href="../../media/css/grimoire.css"> +</head> +<body> + +<div id="shell"> + + <ol id="breadcrumbs"> + + <li class="crumb-0 not-last"> + + <a href="../../">index</a> + + </li> + + <li class="crumb-1 not-last"> + + <a href="../">git</a> + + </li> + + <li class="crumb-2 not-last"> + + <a href="./">theory-and-practice</a> + + </li> + + <li class="crumb-3 last"> + + refs-and-names + + </li> + + </ol> + + + + <div id="article"> + <h1 id="refs-and-names">Refs and Names</h1> +<p>Git's <a href="objects">object system</a> stores most of the data for projects tracked in +Git, but only provides SHA-1 hashes. This is basically useless if you want to +make practical use of Git, so Git also has a naming mechanism called “refs” +that provide human-meaningful names for objects.</p> +<p>There are two kinds of refs:</p> +<ul> +<li> +<p>“Normal” refs, which are names that resolve directly to SHA-1 hashes. These + are the vast majority of refs in most repositories.</p> +</li> +<li> +<p>“Symbolic” refs, which are names that resolve to other refs. In most + repositories, only a few of these appear. (Circular references are possible + with symbolic refs. Git will refuse to resolve these.)</p> +</li> +</ul> +<p>Anywhere you could use a SHA-1, you can use a ref instead. Git interprets them +identically, after resolving the ref down to the SHA-1.</p> +<h2 id="namespaces">Namespaces</h2> +<p>Every operation in Git that uses a name of some sort, including branching +(branch names), tagging (tag names), fetching (remote-tracking branch names), +and pushing (many kinds of name), expands those names to refs, using a +namespace convention. The following namespaces are common:</p> +<ul> +<li> +<p><code>refs/heads/NAME</code>: branches. The branch name is the ref name with + <code>refs/heads/</code> removed. Names generally point to commits.</p> +</li> +<li> +<p><code>refs/remotes/REMOTE/NAME</code>: “remote-tracking” branches. These are maintained + in tandem by <code>git remote</code> and <code>git fetch</code>, to cache the state of other + repositories. Names generally point to commits.</p> +</li> +<li> +<p><code>refs/tags/NAME</code>: tags. The tag name is the ref name with <code>refs/heads/</code> + removed. Names generally point to commits or tag objects.</p> +</li> +<li> +<p><code>refs/bisect/STATE</code>: <code>git bisect</code> markers for known-good and known-bad + revisions, from which the rest of the bisect state can be derived.</p> +</li> +</ul> +<p>There are also a few special refs directly in the <code>refs/</code> namespace, most +notably:</p> +<ul> +<li><code>refs/stash</code>: The most recent stash entry, as maintained by <code>git stash</code>. + (Other stash entries are maintained by a separate system.) Names generally + point to commits.</li> +</ul> +<p>Tools can invent new refs for their own purposes, or manipulate existing refs; +the convention is that tools that use refs (which is, as I said, most of them) +respect the state of the ref as if they'd created that state themselves, +rather than sanity-checking the ref before using it.</p> +<h2 id="special-refs">Special refs</h2> +<p>There are a handful of special refs used by Git commands for their own +operation. These refs do <em>not</em> begin with <code>refs/</code>:</p> +<ul> +<li> +<p><code>HEAD</code>: the “current” commit for most operations. This is set when checking + out a commit, and many revision-related commands default to <code>HEAD</code> if not + given a revision to operate on. <code>HEAD</code> can either be a symbolic ref + (pointing to a branch ref) or a normal ref (pointing directly to a commit), + and is very frequently a symbolic ref.</p> +</li> +<li> +<p><code>MERGE_HEAD</code>: during a merge, <code>MERGE_HEAD</code> resolves to the commit whose + history is being merged.</p> +</li> +<li> +<p><code>ORIG_HEAD</code>: set by operations that change <code>HEAD</code> in potentially destructive + ways by resolving <code>HEAD</code> before making the change.</p> +</li> +<li> +<p><code>CHERRY_PICK_HEAD</code> is set during <code>git cherry-pick</code> to the commit whose + changes are being copied.</p> +</li> +<li> +<p><code>FETCH_HEAD</code> is set by the forms of <code>git fetch</code> that fetch a single ref, and + points to the commit the fetched ref pointed to.</p> +</li> +</ul> +<h2 id="examining-and-manipulating-refs">Examining and manipulating refs</h2> +<p>The <code>git show-ref</code> command will list the refs in namespaces under <code>refs</code> in +your repository, printing the SHA-1 hashes they resolve to. Pass <code>--head</code> to +also include <code>HEAD</code>.</p> +<p>The following commands can be used to manipulate refs directly:</p> +<ul> +<li> +<p><code>git update-ref <ref> <sha1></code> forcibly sets <code><ref></code> to the passed <code><sha1></code>.</p> +</li> +<li> +<p><code>git update-ref -d <ref></code> deletes a ref.</p> +</li> +<li> +<p><code>git symbolic-ref <ref></code> prints the target of <code><ref></code>, if <code><ref></code> is a + symbolic ref. (It will fail with an error message for normal refs.)</p> +</li> +<li> +<p><code>git symbolic-ref <ref> <target></code> forcibly makes <code><ref></code> a symbolic ref + pointing to <code><target></code>.</p> +</li> +</ul> +<p>Additionally, you can see what ref a given name resolves to using <code>git +rev-parse --symbolic-full-name <name></code> or <code>git show-ref <name></code>.</p> + </div> + + + +<div id="comments"> +<div id="disqus_thread"></div> +<script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'grimoire'; // required: replace example with your forum shortname + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); +</script> +<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript> +<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a> +</div> + + + + <div id="footer"> + <p> + + The Codex — + + Powered by <a href="http://markdoc.org/">Markdoc</a>. + +<a href="https://bitbucket.org/ojacobson/grimoire.ca/src/master/wiki/git/theory-and-practice/refs-and-names.md">See this page on Bitbucket</a> (<a href="https://bitbucket.org/ojacobson/grimoire.ca/history-node/master/wiki/git/theory-and-practice/refs-and-names.md">history</a>). + + </p> + </div> + +</div> +</body> +</html>
\ No newline at end of file |