From db21471d74b6f94140cb147f222fdf8c4f3f1f71 Mon Sep 17 00:00:00 2001 From: Suzanne Soy Date: Tue, 22 Jun 2021 22:41:01 +0100 Subject: [PATCH] WIP on prose, fixed bug in git checkout, before making a mess with the pretty-parser for hightlighting --- README | 3 +- git-tutorial.css | 11 +- git-tutorial.js | 37 ++++- index.html | 348 +++++++++++++++++++++++++++++++++++++++++++---- viz-lite.js | 200 +++++++++++++++++++++++++++ viz.js | 206 ++++++++++++++++++++++++++++ 6 files changed, 769 insertions(+), 36 deletions(-) create mode 100644 viz-lite.js create mode 100644 viz.js diff --git a/README b/README index e947ffb..595ff29 100644 --- a/README +++ b/README @@ -1,3 +1,4 @@ CodeMirror: https://codemirror.net/ license MIT sha1.js: https://www.movable-type.co.uk/scripts/sha1.html license MIT -pako 2.0.3 https://github.com/nodeca/pako license (MIT AND Zlib) +pako 2.0.3: pako.min.js from https://github.com/nodeca/pako license (MIT AND Zlib) +Viz.js v2.1.2: viz.js and viz-lite.js from https://github.com/mdaines/viz.js license MIT diff --git a/git-tutorial.css b/git-tutorial.css index 1726be5..5196f19 100644 --- a/git-tutorial.css +++ b/git-tutorial.css @@ -6,13 +6,14 @@ article#git-tutorial { position: absolute; top:0; left:0.5em; transition: right, #git-tutorial .lines { position: absolute; z-index: 2000; } #git-tutorial textarea, #git-tutorial .CodeMirror { width: 100%; font-size: 1.2rem; border: thin solid black; } #git-tutorial table { table-layout: fixed; width: 100%; font-size: 100%; font-family: monospace; min-width: 41em; } +#git-tutorial pre.log { border: thin solid gray; padding: 0.3em; font-size: 100%; font-family: monospace; box-sizing: border-box; } #git-tutorial td.cell-contents, #git-tutorial th.cell-contents { font-family: monospace; } article#git-tutorial p, article#git-tutorial h1 { max-width: 63rem; } #git-tutorial td, #git-tutorial th { padding-left: 0.3em; padding-right: 0.3em; } #git-tutorial td.cell-contents, #git-tutorial th.cell-contents { width: 36em; } article#git-tutorial { left: calc(50% - ( 17.4em / 2 ) - ( 63rem / 2 ) ); right:18.4em; max-width: 63rem; } -article#git-tutorial table { width: 77rem; margin-left: calc( ( ( 63rem - 77rem ) / 2 ) ); } +article#git-tutorial table, #git-tutorial pre.log { width: 77rem; margin-left: calc( ( ( 63rem - 77rem ) / 2 ) ); } #git-tutorial #toc { right:0; } #git-tutorial #toc:hover { border-left: 1px solid gray; } @@ -20,7 +21,7 @@ article#git-tutorial table { width: 77rem; margin-left: calc( ( ( 63rem - 77rem #git-tutorial td, #git-tutorial th { padding-left: 0.3em; padding-right: 0.3em; } #git-tutorial td.cell-contents, #git-tutorial th.cell-contents { width: 36em; } article#git-tutorial { left:0.5em; right:18.4em; max-width: 63rem; } - article#git-tutorial table { width: 100%; margin-left: auto; } + article#git-tutorial table, #git-tutorial pre.log { width: 100%; margin-left: auto; } #git-tutorial #toc { right:0; } #git-tutorial #toc:hover { border-left: 1px solid gray; } } @@ -29,7 +30,7 @@ article#git-tutorial table { width: 77rem; margin-left: calc( ( ( 63rem - 77rem #git-tutorial td, #git-tutorial th { padding-left: 0; padding-right: 0; } #git-tutorial td.cell-contents, #git-tutorial th.cell-contents { width: 34em; } article#git-tutorial { left:0.5em; right: 7em; max-width: 63rem; } - article#git-tutorial table { width: 100%; margin-left: auto; } + article#git-tutorial table, #git-tutorial pre.log { width: 100%; margin-left: auto; } #git-tutorial #toc { right: -11em; } #git-tutorial #toc:hover { border-left: 5px solid gray; } } @@ -38,7 +39,7 @@ article#git-tutorial table { width: 77rem; margin-left: calc( ( ( 63rem - 77rem #git-tutorial td, #git-tutorial th { padding-left: 0; padding-right: 0; } #git-tutorial td.cell-contents, #git-tutorial th.cell-contents { width: 30em; } article#git-tutorial { left:0.5em; right:6em; max-width: 63rem; } - article#git-tutorial table { width: 100%; margin-left: auto; } + article#git-tutorial table, #git-tutorial pre.log { width: 100%; margin-left: auto; } #git-tutorial #toc { right: -12em; } #git-tutorial #toc:hover { border-left: 5px solid gray; } } @@ -94,4 +95,4 @@ article#git-tutorial .onlytoc { display: none; } #git-tutorial .trivia { opacity: 80%; border: thin solid slategrey; margin: 1em; padding: 0.3em; } #git-tutorial .trivia:before { content: "Trivia"; border-bottom: thin solid slategrey; display: block; text-align: center; } #git-tutorial .trivia table { min-width: 90%; max-width: 90%; width: 90%; margin-left: auto; margin-right: auto; } -/*#git-tutorial .trivia table td.cell-contents, #git-tutorial .trivia table th.cell-contents { width: 30%; }*/ \ No newline at end of file +/*#git-tutorial .trivia table td.cell-contents, #git-tutorial .trivia table th.cell-contents { width: 30%; }*/ diff --git a/git-tutorial.js b/git-tutorial.js index cb49f1d..4924789 100644 --- a/git-tutorial.js +++ b/git-tutorial.js @@ -529,7 +529,7 @@ var ___script_log_header = '' + 'var console = (function(real_console) {\n' + ' return {\n' + ' log: function() {\n' - + ' ___log[___log.length] = arguments;\n' + + ' ___log[___log.length] = Array.from(arguments);\n' + ' real_console.log.apply(console, arguments);\n' + ' },\n' + ' assert: real_console.assert,\n' @@ -537,8 +537,40 @@ var ___script_log_header = '' + '})(window.console);\n' + '\n'; +function ___file_contents_to_graphviz(s) { + try { + var inflated = pako.inflate(___stringToUint8Array(s)); + } catch(e) { + var inflated = false; + } + if (inflated) { + var id=___global_unique_id++; + return { + html: + '' + + 'deflated:' + + ___specialchars_and_colour_and_hex(___uint8ArrayToString(inflated)) + + '' + + '', + td: function(td) { td.classList.add('deflate-toggle'); td.setAttribute('onclick', '___deflated_click('+id+')'); } + }; + } else { + return { html: ___specialchars_and_colour_and_hex(s), td: function() {} }; + } +} + +function ___filesystem_to_graphviz(filesystem, previous_filesystem) { + return "digraph graph_view {" + + 'a -> b' + + "}"; +} + function ___eval_result_to_string(filesystem, previous_filesystem, log) { - return '
' + 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 @@ GIT tutorial + + + + + + + +

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 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.

- +

+ 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. +

+ @@ -797,11 +1018,10 @@ git_tag('v1.0', second_commit);

git checkout

-

Checkout, branches and other references

-

More 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. +

+

Checkout, branches and other references

+

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.

Checking out files

+

+ 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. +