From aebe5d568c25c151f8848265ed4ce1a353f1395c Mon Sep 17 00:00:00 2001 From: Michael Lohmann Date: Mon, 15 Jan 2024 04:37:16 +0100 Subject: [PATCH] README: explain better what this is all about --- README.md | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b571859..5978e80 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,26 @@ # What is this? -This is the (WIP) script for creating an interactive `git` repo that is a completely self-contained `git` tutorial (and hopefully at least a bit fun, too ;-) ). -The tutorial itself is only in the folder "tutorial" that can be build (see below) and NOT in this repository. Do NOT look around in this repository unless you want to develop it, because otherwise you will be spoiled with the solutions. Also: don't snoop around in the .git-Folder unless explicitly told - it'll spoil the fun for you and as said before: you can find all flags by using git commands ;) +`git` is a nice version control system, but since it has many features, it can be a bit hard to understand, as this lovely xkcd-comic by Randall Munroe shows: +![A comic of stick figures describing how beautiful git is, but they just memorize a few commands. And when they run into an issue, they don't know how to deal with it and just copy the file and delete the folder](https://imgs.xkcd.com/comics/git.png "If that doesn't fix it, git.txt contains the phone number of a friend of mine who understands git. Just wait through a few minutes of 'It's really pretty simple, just think of branches as...' and eventually you'll learn the commands that will fix everything.") -You can download a copy from GitHub, unzip it and (for some cursed reason thanks to GitHub it must also be in a tarball to remain playable) then you also need to extract the tarball. +But fear not! + +There are lots of tutorials online, which describe certain features, but in my experience they all have a drawback: certain actions require your repository to be in a certain state, otherwise commands will fail because you accidentally skipped a step. But that does not have to be this way! Here is a tutorial that explains git by you actually using it. The commands to will only uncover one info at a time, so you can't accidentally skip steps. (And hopefully it is at least a bit of fun, too ;-) ). + +The tutorial itself is only in the folder "tutorial" that can be build (see below) and NOT in this repository. Do NOT look around in this repository unless you want to develop it, because otherwise you will be spoiled with the solutions. + +Also: If you are playing for the "nuggits" (like CTF flags some strings that you can redeem to track your progress) don't snoop around in the .git-Folder unless explicitly told - it'll spoil the fun for you and as said before: you can find (almost) all flags by using git commands only ;) + +Build instructions: +```sh +git clone https://github.com/miallo/nuggit.git +cd nuggit +./build.sh +cd tutorial +# and the fun can begin +``` + +Alternatively: If you don't want to run this "build"-script yourself (it basically just executes a bunch of git commands to create the folder "tutorial" and fills it with all the information you need), you can download a copy from GitHub, unzip it and (for some cursed reason thanks to GitHub the playable folder must also be in a tarball to remain playable) then you also need to extract the tarball that is contained. On MacOS both can be achieved by double-clicking them in finder, but if you are using Linux or you already want to get warmed up using the terminal/command line, you can run those commands in your download folder: ```sh unzip tutorial.zip @@ -12,8 +29,6 @@ cd tutorial ``` and then you are ready! -If instead you want to create a local "playable" copy yourself, you can simply run `./build.sh` and you will find the folder "tutorial". - ## What git functions are already explained? - diff (--staged)