' + log.map(function(l) { return l.map(function (x) { return x.toString(); }).join(', '); }).join('\n') + ''
+ var loghtml = '' + log.map(function(l) { return l.map(function (x) { return x.toString(); }).join(', '); }).join('\n') + ''
+ return (log.length > 0 ? 'Console output:
' + loghtml : '') + + Viz(___filesystem_to_graphviz(filesystem, previous_filesystem), "svg") + ___filesystem_to_string(filesystem, false, previous_filesystem); } function ___git_eval(current) { @@ -559,7 +591,6 @@ function ___git_eval(current) { + 'document.getElementById("out" + current).innerHTML = ___eval_result_to_string(filesystem, ___previous_filesystem, ___log);\n' + 'filesystem;\n'; try { - document.getElementById('debug').innerText = script; eval(script); } catch (e) { // Stack traces usually include :line:column diff --git a/index.html b/index.html index fd9fe40..72bdb19 100644 --- a/index.html +++ b/index.html @@ -2,12 +2,18 @@After creating the branch, we show how the file .git/refs/heads/main can be overwritten
+using git branch -f
+ Usually, the HEAD is a symbolic reference to a branch, i.e. the
+ file .git/HEAD contains ref: refs/heads/name-of-branch.
+ When checking out a commit by specifying its hash directly, or when checking out
+ a non-branch reference, the file .git/HEAD contains the hash of the
+ commit instead.
+
+ The state in which .git/HEAD contains a commit hash is called
+ "detached HEAD", and often sounds alarming to people who have not encountered this
+ before. As we will see in the following sections, the only difference between detached
+ HEAD and the normal state is that git commit updates the branch to point
+ to the new commit in the normal mode of operation. When the HEAD is detached,
+ it does not point to a specific branch, and git commit updates the HEAD
+ directly instead, overwriting it with the new commit hash.
+
+ Since the HEAD is supposed to be a transient pointer, it is easy to lose track of the hash of + an important commit. For example, the following sequence of operations: + +
+git checkout 0123456789abcdef0123456789abcdef01234567 + +touch new_file +git add new_file +git commit -m 'This is a commit adding a new file' + +git checkout branch-of-feature-foobar ++ + roughly means: + +
+HEAD = 0123456789abcdef0123456789abcdef01234567
+// overwrite the contents of the working directory with
+// the contents of commit 0123456789abcdef0123456789abcdef01234567
+checkout(0123456789abcdef0123456789abcdef01234567)
+
+// create commit with the new file:
+HEAD = commit(…)
+
+// Checkout other branch
+HEAD = git_rev_parse('branch-of-feature-foobar')
+
+
+
++ The hash of the new commit which is stored in HEAD on the second step is overwritten + in the third step. In order to later retrieve that specific version with the precious + new_file, one needs that hash. It would be possible to note down these hashes in a + simple text file, but GIT offers a mechanism for that: branches. After all, branches are + merely named text files containing the hash of the latest commit in that line of work. +
+ +
+ The hash of a commit created with git commit does not only exist in the
+ HEAD file (when in detached HEAD) or in the current branch file (normal mode). The official
+ implementation of GIT keeps a log of the changes being made to the various references.
+ .git/logs/HEAD contains a log of the hashes pointed to by .git/HEAD,
+ and .git/logs/refs/heads/main contains a log of the hashes pointed to by
+ .git/refs/heads/main, and the commands git reflog and
+ git reflog main pretty-print these files.
+
+ There are a few more ways to find a lost commit hash, including a careful invocation of
+ git fsck which checks that the files stored in .git/ are not
+ corrupted, and that no reference (to another reference or a commit, tree or blob) points
+ to a non-existing file. The git fsck --unreachable option tells this command
+ to print all object hashes which are not pointed to indirectly by any named reference
+ (so-called unreachable objects, which are well-formed but are not indirectly linked to
+ from a branch or other kind of named pointer).
+
+ The reflog can be used to recover a lost hash but handling hashes manually like this is + somewhat error-prone, and most new users are not aware of those features; for this reason + GIT commands tend to display a warning when switching to a detached HEAD state. +
-git commitIf the HEAD points to a commit hash, then git commit updates the HEAD to point to the new commit.
- Otherwise, when the HEAD points to a branch, then the target branch (represented by a file named .git/refs/heads/the_branch_name) is updated.
+ These files use a .ini syntax
+ with key = value lines grouped under some [section] headings. The configuration above could be
+ stored in ~/.gitconfig or .git/config using the following syntax:
+
+[user] +name = Ada Lovelace +email = ada@analyti.cal ++
+ The $EDITOR variable is a traditional *NIX environment variable, and could e.g. be declared with
+ EDITOR=nano in ~/.profile or ~/.bashrc.
+
git commit
+ The git commit command stores a commit (metadata and a pointer to a tree
+ containing the files given on the command-line), and updates the HEAD or
+ current branch to point to the new commit.
+
If the HEAD points to a commit hash, then git commit updates the HEAD to point to the new commit.
+ Otherwise, when the HEAD points to a branch, then the target branch (represented by a file named .git/refs/heads/the_branch_name) is updated.
+ The official implementation of git commit makes use of the index.
+ When a file is scheduled for the next commit using git add path/to/file, it is added to
+ the index. The index is a representation of a collection of copies of files, which can efficiently be
+ compared to the working directory. It uses a different representation, but its role is very similar
+ to that of a tree object along with the subtrees and blob objects of individual files. When
+ git commit is called without specifying any files, it creates a commit containing the
+ version of the files stored in the index.
+
+ In this simplified implementation, we only support creating commits by specifying all the files that
+ must be present in the commit (including unchanged files). This contrasts with the official implementation
+ which would create a tree containing the files from the current HEAD, as well as the added, modified or
+ deleted files specified by git add or specified directly on the git commit
+ command-line.
+
Intuitively, tags differ from branches in the following way: when checking out a branch,
+ and a subsequent commit is made, the branch is updated to point to the new commit's hash.
+ As we've seen in the implementation of git commit, the difference is actually
+ in the contents of the .git/HEAD file. If it is a symbolic reference (generally
+ a pointer to a branch), then the target of that reference is updated every time a new commit
+ is created. If the .git/HEAD file contains the hash of a commit, then the
+ .git/HEAD file itself is updated every time a new commit is created.
+
+ Therefore, tags and branches differ only in their usage and in the path under which they are
+ stored (.git/refs/heads/name-of-the-branch vs. .git/refs/tags/name-of-the-tag).
+ The file .git/HEAD is overwritten by git commit and git checkout.
+ It is the latter command which will behave differently for tags and branches; git checkout branch-name
+ turns the HEAD into a symbolic reference, whereas git checkout tag-name resolves the tag name to
+ a commit hash, and writes that hash directly into .git/HEAD.
+
git checkoutMore importantly, the HEAD does not normally point to a tag. Although nothing actually
- prevents writing ref: refs/tags/v1.0 into .git/HEAD, the GIT
- commands will not automatically do this. For example, git checkout tag-or-branch-or-hash
- will put a symbolic ref: in .git/HEAD only if the argument is a branch.
+ The git checkout commit-hash-or-reference command modifies the HEAD to point to the given commit,
+ and modifies the working directory to match the contents of the tree object pointed to by that commit.
+
The HEAD does not normally point to a tag. Although nothing actually
+ prevents writing ref: refs/tags/v1.0 into .git/HEAD, the GIT
+ commands will not automatically do this. For example, git checkout tag-or-branch-or-hash
+ will put a symbolic ref: in .git/HEAD only if the argument is a branch.
+ In order to replace the contents of the working directory with those of the given commit, we + recursively compare the subtrees, deleting from the working directory the files or directories + that are not present in the tree object, and overwriting the others. +
+
+ The official implementation of GIT will record the diff between the current working directory
+ and the current commit, and will re-apply these changes on top of the freshly checked-out commit.
+ The official git checkout command will print warnings and refuse to proceed when
+ these changes cannot be re-applied without conflict, encouraging the user to create a commit
+ containing this updated version or to stash the changes (effectively creating a temporary commit
+ containing this version, pointed to by .git/refs/stash). Our simple implementation
+ will always overwrite the changes.
+