From 49e440d12ed301c0c4bc8ef57f18dd32752fb4d2 Mon Sep 17 00:00:00 2001 From: Mike Doel Date: Thu, 12 Mar 2015 13:38:11 -0400 Subject: [PATCH] Pull correct read over from neo README previously had been a pointer to neo, but this is now canonical. --- README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 215 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3648348d..53da501d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,216 @@ -# THIS IS A FORK. +# Git Immersion Labs -# THE MAIN REPOSITORY IS NOW AT [https://github.com/neo/git_immersion](https://github.com/neo/git_immersion) +These are the labs for the Git Immersion training, a series of +self-paced exercises that take you through the basics of using git. + +## Online + +You can find the labs online at +[http://gitimmersion.com](http://gitimmersion.com). + +## Building the Labs + +The labs are generated from a single source file that describes +each of the labs. The generation is done in two steps. + +Before running the labs, make sure you have the following alias +in your .gitconfig file. The `hist` command is used extensively +throughout the tutorial. + + [alias] + hist = log --pretty=format:'%h %ad | %s%d [%an]' --graph --date=short + +First, the `rake run` command runs through each of the labs and +executes the listed commands and captures the output. The `auto` +directory is used for the automatic running and the output is captured +in the `samples` directory. + +Second, the `rake labs` command generates the HTML labs using the text +from the `src/labs.txt` file and the captured live output from the +`samples` directory. Template files for the main index, the lab +pages, and the navigation divs can be found in the `templates` +directory. + +The HTML output is put into `git_tutorial/html`. Browsing the +`git_tutorial/html/index.html` file will bring up the git tutorial in +your browser. + +## Publishing the Labs + +To publish the labs on the web-site, run the `rake publish` command. +This will copy the `git_tutorial/html` directory to the `gh-pages` +branch. The `gh-pages` branch is then pushed, which auto-publishes it +from github. + +Manually modifying the files in the `gh-pages` branch is probably the +wrong thing to do. Modify the appropriate template or css file on the +master branch, then run `rake publish`. + +## Lab Format Directives + +The `labs.txt` file contains all the lab text, formatted as a textile +file with additional directives interpreted for both run time +(generating the sample output) and format time (generating the HTML). + +The Format Directives are: + +### h1. _\_ + +Starts a new lab with the name _\_. Each lab + +Example: + + h1. Using Revert + +### pre(_\_). + +A section of predefined code, using the HTML class of _\_. The predefined code block runs until a blank line. + +Example: + + pre(instructions). + git log --pretty=oneline --max-count=2 + git log --pretty=oneline --since='5 minutes ago' + git log --pretty=oneline --until='5 minutes ago' + +The *instructions* class is used to format command similar to the +execute section, but without executing the commands in the run phase. + +### p. _\_ + +A paragraph of text. The text for the paragraph will continue on +following lines until a blank line. + +Example: + + p. If you have never used git before, you need to do some setup + first. Run the following commands so that git knows your name and + email. If you have git already setup, you can skip down to the + line ending section. + +### Execute: + +Execute the following shell command until a blank line is encountered. +Commands are executed as they appear with the following exceptions. + +* +_\_ + + Run this _\_ line silently, do not include it on the lab + output. + +* -_\_ + + Do not run this _\_, but include it in the lab + output. + +* =*\* + +For example, the following will execute the `git status` command and +capture its output in the `status` sample for the lab. The first `git +commit` is ignored at runtime (but will be included in lab output). +The second `git commit` with a commit message will be executed (but +will not appear in the lab output). However, the output of the second +command is captured in a sample. + + Execute: + git status + =status + -git commit + +git commit -m 'Using ARGV' + =commit + +### File: _\_ + +Format the following lines (until an "EOF" string is encountered) as +the contents of a file name _\_. + +Example: + + File: hello.rb + # This is the hello world program in Ruby. + + puts "Hello, World!" + EOF + +### Output: + +Format the following line. (until an "EOF" string is encountered) as +the output of commands. + +Output lines starting with = are used to grab the sample files +generated during the run phase. + +Example: + + Output: + git commit + Waiting for Emacs... + [master 569aa96] Using ARGV + 1 files changed, 1 insertions(+), 1 deletions(-) + EOF + +Often sample lines are included in the output. Assuming you have +captured the output of a status command and a commit command, you +might use the following: + + Output: + =status + =commit + EOF + +### Set: _\_=_\_ + +Evaluate the _\_ and set the _\_ to that +value. Often used to grab dynamic data from the run phase for use in +later commands. + +For example, the following will grab the git hash value for the commit +labeled "First Commit", and store it in _\_. When the `git +checkout` command is executed, it uses the value of _\_ in the +command. + + Set: hash=hash_for("First Commit") + Execute: + git checkout + +### =_\_ + +Define/use a sample output. + +Sample output are generated during the run phase of building the Git +Immersion labs. They are the output of a single command line in the +Execute sction of a lab. + +Example: + + Execute: + git checkout master + =checkout + git status + =status + +The two sample lines above capture the output from the checkout and +status git commands respectively. The sample output is saved (in the +`samples` directory) until the HTML generation phase is performed. + +During HTML generation, the sample lines may be "played back" by +including them in the Output section of a lab. + +Example: + + Output: + =checkout + =status + EOF + +Sample names must be unique within a single lab, but do not have to be +unique across the entire project. + +# License + +![CC by-nc-sa](http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png) + +GitImmersion is released under a +[Creative Commons, Attribution-NonCommercial-ShareAlike, Version 3.0](http://creativecommons.org/licenses/by-nc-sa/3.0/) +License.