From 792c5bc78fe0729d25e52fbefefde2e228074971 Mon Sep 17 00:00:00 2001 From: Suzanne Soy Date: Wed, 23 Jun 2021 19:51:17 +0100 Subject: [PATCH] Section numbers and better numbering for exercises --- git-tutorial.css | 16 +++++++++- index.html | 82 ++++++++++++++++++++++++++++++++++-------------- 2 files changed, 73 insertions(+), 25 deletions(-) diff --git a/git-tutorial.css b/git-tutorial.css index 4b8781d..e2c88f4 100644 --- a/git-tutorial.css +++ b/git-tutorial.css @@ -122,4 +122,18 @@ article#git-tutorial .onlytoc { display: none; } #git-tutorial .graph-view-tooltips tr th { opacity: 1; border: none; border-bottom:thin solid #444; text-align: left; } #git-tutorial .graph-view-tooltips tr td { opacity: 1; border: none; border-top:thin solid: #444; } #git-tutorial .graph-view-tooltips > .graph-view-tooltips-default { color: #444; text-align: center; } -#git-tutorial .graph-view .legend { padding: 0.8em 0.3em 0.3em; } \ No newline at end of file +#git-tutorial .graph-view .legend { padding: 0.8em 0.3em 0.3em; } + +/* Section counters */ +#git-tutorial { counter-reset: h1counter h2counter h3counter; } +#git-tutorial > section { counter-reset: h2counter h3counter;} +#git-tutorial > section > h1 { counter-increment: h1counter; } +#git-tutorial > section > h1::before { content: counter(h1counter) ". " } +#git-tutorial > section > section { counter-reset: h3counter; } +#git-tutorial > section > section > h1 { counter-increment: h2counter; } +#git-tutorial > section > section > h1::before { content: counter(h1counter) "." counter(h2counter) ". " } +#git-tutorial > section > section.exercise > h1::before { content: "Exercise " counter(h1counter) "." counter(h2counter) ". " } + +#git-tutorial .exercise-task { border: thin solid #80c5c5; background: #f1faff; padding: 1em } +#git-tutorial .exercise-reason { border: thin solid #80c5c5; background: #f8fdff; padding: 1em } +#git-tutorial .exercise-reason:before { content: "Rationale "; margin-bottom: 0.7em; font-weight: bold; display: block; } \ No newline at end of file diff --git a/index.html b/index.html index 542c371..7739f69 100644 --- a/index.html +++ b/index.html @@ -167,7 +167,7 @@ write('proj/src/main.scm', '(map (lambda (x) (+ x 1)) (list 1 2 3))\n'); -
+

git init (creating .git)

The first thing to do is to initialize the GIT directory. For now, only the .git folder is needed, The rest @@ -1031,7 +1031,6 @@ git_tag('v1.0', second_commit);

git checkout

-

The git checkout commit-hash-or-reference command modifies the HEAD to point to the given commit, and modifies the working tree to match the contents of the tree object pointed to by that commit. @@ -1048,6 +1047,7 @@ function git_checkout(tag_or_branch_or_hash) { checkout_files(git_rev_parse('HEAD')); } +

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 @@ -1374,31 +1374,48 @@ commands.

The reader willing to improve their grasp of GIT's mental model, and reduce their reliance on a few learned recipies, might be interested in the following warm-up exercises:

-
    -
  • + +
    +

    Inspection using git cat-file

    +

    Inspect an existing repository, starting with cat .git/HEAD and using git cat-file -p some-hash - to pretty-print an object given its hash. This will help sink in the points explained in this tutorial, and give a better + to pretty-print an object given its hash. +

    +

    + This will help sink in the points explained in this tutorial, and give a better understanding of the internals of GIT. This knowledge is helpful for day-to-day tasks, as the GIT commands usually perform simple changes to this internal representation. Understanding the representation better can demistify the semantics of the daily GIT commands. Furthermore, equipped with a better understanding of GIT's implementation, the dreamy reader will be tempted to compare this lack of intrinsic complexity with the apparent complexity, and be entitled to expect a better, less arcane user interface for a tool with such a simple implementation. -

    • -
  • +

    +
+
+

Inspection of the files in .git/

+

Inspect a small existing repository, starting with cat .git/HEAD and using the zlib decompression tool from the zlib compression section. Larger repositories will make use of GIT packs, which are compressed archives containing a number of objects. GIT packs only matter as an optimization of the - disk space used by large repositories, but other tools would be necessary to inspect those. This should help understand + disk space used by large repositories, but other tools would be necessary to inspect those. +

+

+ This should help understand the internal representation of GIT commits and branches, and should help having a instinctive idea of how the data store is modified by the various commands. This in turn could come in handy in case of apparent data loss (a lost stash or a checkout leaving an unreferenced commit on a detached HEAD), as this would help understand the work done by the various disaster-recovery one-liners that a quick panicked online search provides. - -

  • +

    +
    • +
    +

    Creating a repository from scratch

    +

    Run git init new-directory in a terminal, and create an initial single-file commit from scratch, using only git hash-object, printf and overwriting .git/HEAD and/or .git/refs/heads/name-of-a-branch. This will involve retracing the steps in this tutorial to create a blob - object for the file, a tree object to be the directory containing just that file, and a commit object. This exercise should + object for the file, a tree object to be the directory containing just that file, and a commit object. +

    +

    + This exercise should help sink in the feeling that the internal representation of GIT commits is not very complex, and that many commands with convoluted options have very simple semantics. For example, git reset --soft other-commit is little more than writing that other commit's hash in .git/refs/heads/name-of-the-current-branch or .git/HEAD. @@ -1407,8 +1424,11 @@ commands.

    a day-to-day basis, and be entitled to expect better features in a versioning tool. After all, writing those few lines of code to reimplement the core of a versioning tool shouldn't take more than a couple of afternoons, surely our community can do better? - -
  • +

    +
    • +
    +

    Using only basic GIT commands

    +

    For a couple of weeks, only use the GIT commands commit, diff, checkout, merge, cherry-pick, log, clone, fetch and push remote hash-of-commit:refs/heads/name-of-the-branch. In particular, don't use rebase @@ -1417,28 +1437,42 @@ commands.

    explicitly give the name (origin) or URL of the remote, the hash of the commit to push, and the path that should be updated on the remote (git push while the main branch is checked out locally is equivalent to git push origin HEAD:refs/heads/main, where HEAD can be replaced by the actual hash of - the commit). This should help sink in the feeling that the internals of GIT are very simple (most of these commands + the commit). +

    +

    + This should help sink in the feeling that the internals of GIT are very simple (most of these commands are implemented in this tutorial, and the other ones are merely wrappers around enhanced versions of the *NIX commands diff, patch and scp), and that the rest of the GIT toolkit consists mostly of convenience wrappers to help seasoned users perform common tasks more efficiently. - -

  • +

    +
    • +
    +

    Understanding commits as copies of the root directory

    +

    Try not even using git cherry-pick or git diff a few times, instead make two copies the git directoy, check out the two different commits in each copy, and use the traditional *NIX commands diff and - patch. This should help sink in the feeling that commits are not diffs, but are actual (deduplicated) + patch. +

    +

    + This should help sink in the feeling that commits are not diffs, but are actual (deduplicated) copies of the entire project directory. GIT commits are quite similar to the age-old manual versioning technique of copying the entire directory under a new name at each version, except that the metadata keeps track of which version was the previous one (or which versions were merged together to obtain the new one), and the deduplication avoids excessive space usage, as would be the case with cp --reflink on a filesystem supporting Copy-On-Write (COW). - -

  • +

    +
    • +
    +

    Branches as pointers: living without branches

    +

    For a couple of weeks, don't use any local branch, and stay in detached HEAD state all the time. When checking out a colleague's work, use git fetch && git checkout origin/remote-branch, and use the reflog and a text file - outside of the repository to keep track of the latest commit in a current "branch" instead of relying on GIT. This - should help sink in the feeling that branches are not containers in which commits pile up, but are merely pointers to - the latest commit that are automatically updated. - - + outside of the repository to keep track of the latest commit in a current "branch" instead of relying on GIT. +

    +

    + This should help sink in the feeling that branches are not containers in which commits pile up, but are merely pointers + to the latest commit that are automatically updated. +

    +