From 0b219a2b0ae722ff52b6c95d1ca15018ecfd183d Mon Sep 17 00:00:00 2001 From: Ben Lynn Date: Thu, 5 Mar 2009 23:32:04 -0800 Subject: [PATCH] Elaborated "Building on Git" section. --- Makefile | 12 ++++++++++-- basic.txt | 2 -- branch.txt | 2 +- drawbacks.txt | 2 -- grandmaster.txt | 22 +++++++++++++++------- intro.txt | 2 +- preface.txt | 5 ++++- 7 files changed, 31 insertions(+), 16 deletions(-) diff --git a/Makefile b/Makefile index 9b304ab6..7aef4b96 100644 --- a/Makefile +++ b/Makefile @@ -7,10 +7,18 @@ TXTFILES=preface.txt intro.txt basic.txt clone.txt branch.txt history.txt grandm book.xml: $(TXTFILES) ( for FILE in $^ ; do cat $$FILE ; echo ; done ) | asciidoc -d book -b docbook - > $@ +# Ignore tidy's exit code because Asciidoc generates section IDs beginning with +# "_", which xmlto converts to "id" attributes of tags. The standard +# insists that "id" attributes begin with a letter, which causes tidy to +# print a warning and return a nonzero code. +# +# When Asciidoc 8.3.0+ is widespread, I'll use its idprefix attribute instead +# of ignoring return codes. + book: book.xml xmlto -m custom-html.xsl -o book html book.xml sed -i 's/xmlns:fo[^ ]*//g' book/*.html - ls book/*.html | xargs -n 1 tidy -utf8 -m -i -q + -ls book/*.html | xargs -n 1 tidy -utf8 -m -i -q ./makeover book/default.css: book.css @@ -19,7 +27,7 @@ book/default.css: book.css book.html: book.xml xmlto -m custom-nochunks.xsl html-nochunks $^ - tidy -utf8 -imq $@ + -tidy -utf8 -imq $@ book.pdf: book.xml docbook2pdf book.xml diff --git a/basic.txt b/basic.txt index 1f796c57..9e8ade3c 100644 --- a/basic.txt +++ b/basic.txt @@ -13,8 +13,6 @@ in the current directory with: $ git add . $ git commit -m "My first backup" -The above sequence of commands should be memorized, or placed in a script, as they will be reused frequently. - Now if your new edits go awry, run: $ git reset --hard diff --git a/branch.txt b/branch.txt index 211bc10e..578b1c76 100644 --- a/branch.txt +++ b/branch.txt @@ -88,7 +88,7 @@ Some projects require your code to be reviewed before you may submit it. To make What if the second part cannot be written until the first part is approved and checked in? In many version control systems, you'd have to send the first part to the reviewers, and then wait until it has been approved before starting on the second part. -Actually that's not quite true, but in these systems editing Part II before Part I has been submitted involves a lot of suffering and hardship. In Git, branching and merging are painless (a technical term for fast and local). So after you've committed the first part and sent it for review: +Actually that's not quite true, but in these systems editing Part II before submitting Part I involves suffering and hardship. In Git, branching and merging are painless (a technical term for fast and local). So after you've committed the first part and sent it for review: $ git checkout -b part2 diff --git a/drawbacks.txt b/drawbacks.txt index d8f88519..ef517a13 100644 --- a/drawbacks.txt +++ b/drawbacks.txt @@ -2,8 +2,6 @@ There are some Git issues I've swept under the carpet. Some can be handled easily with scripts and hooks, some require reorganizing or redefining the project, and for the few remaining annoyances, one will just have to wait. Or better yet, pitch in and help! -I've been playing around with some version control system ideas, and wrote link:/~blynn/gg/[an experimental system based on Git], which addresses some of these problems. - === Microsoft Windows === Git on Microsoft Windows can be cumbersome: diff --git a/grandmaster.txt b/grandmaster.txt index 4f4ed1d4..e2ef261f 100644 --- a/grandmaster.txt +++ b/grandmaster.txt @@ -63,9 +63,9 @@ repository lacks: $ git bundle create somefile HEAD ^COMMON_SHA1 -If done frequently, one could easily forget which commit was the last to be -sent. The help page suggests using tags to solve this. Namely, after you -send a bundle, type: +If done frequently, one could easily forget which commit was last sent. The +help page suggests using tags to solve this. Namely, after you send a bundle, +type: $ git tag -f lastbundle HEAD @@ -175,10 +175,10 @@ in which case commits will only be deleted when you run *git gc* manually. === Building On Git === -In true UNIX fashion, Git's design allows it to be easily used as a low-level component of other programs. There are GUI interfaces, web interfaces, alternative command-line interfaces, and perhaps soon you will have a script or two of your own that calls Git. +In true UNIX fashion, Git's design allows it to be easily used as a low-level component of other programs, such as GUI and web interfaces, alternative command-line interfaces, patch managements tools, importing and conversion tools and so on. In fact, some Git commands are themselves scripts standing on the shoulders of giants. With a little tinkering, you can customize Git to suit your preferences. -One easy trick is to use built-in git aliases to shorten your most frequently used -commands: +One easy trick is to use built-in Git aliases to shorten your most frequently +used commands: $ git config --global alias.co checkout $ git config --global --get-regexp alias # display current aliases @@ -195,7 +195,15 @@ the "refs/heads/" and ignore errors: $ git symbolic-ref HEAD 2> /dev/null | cut -b 12- -See http://git.or.cz/[the Git homepage] for more examples. +The +contrib+ subdirectory is a treasure trove of tools built on basic commands +(which in time may be promoted to official commands). On Debian and Ubuntu, +this directory lives at +/usr/share/doc/git-core/contrib+. + +One popular resident is +workdir/git-new-workdir+. Via clever symlinking, this script creates a new working directory whose history is shared with the original respository: + + $ git-new-workdir an/existing/repo new/directory + +The new directory and files within can be thought of as a clone, except since the history is shared, the two trees automatically stay in sync. There's no need to merge, push or pull. === Daring Stunts === diff --git a/intro.txt b/intro.txt index 897c38bd..e6f9a38d 100644 --- a/intro.txt +++ b/intro.txt @@ -48,7 +48,7 @@ A small project may only need a fraction of the features offered by such a syste For this topic, our computer game analogy becomes too thinly stretched. Instead, let us again consider editing a document. -Suppose Alice has inserted a line at the beginning of a file, and Bob appends one at the end. They both upload their changes. Most systems will automatically deduce a reasonable course of action: accept and merge their changes, so both Alice's and Bob's edits are applied. +Suppose Alice inserts a line at the beginning of a file, and Bob appends one at the end of his copy. They both upload their changes. Most systems will automatically deduce a reasonable course of action: accept and merge their changes, so both Alice's and Bob's edits are applied. Now suppose both Alice and Bob have made distinct edits to the same line. Then it is impossible to resolve the conflict without human intervention. The second person to upload is informed of a merge conflict, and they must either choose one edit over another, or revise the line entirely. diff --git a/preface.txt b/preface.txt index a1c2f586..03a1b055 100644 --- a/preface.txt +++ b/preface.txt @@ -15,10 +15,13 @@ Rather than go into details, we provide rough instructions for particular effect - http://docs.google.com/View?id=dfwthj68_675gz3bw8kj[Chinese translation]: by JunJie, Meng and JiangWei. - link:book.html[Single webpage]: barebones HTML, with no CSS. - link:book.pdf[PDF file]: printer-friendly. + - http://packages.debian.org/search?searchon=names&keywords=gitmagic[Debian gitmagic package]: get a fast and local copy of this site. http://packages.ubuntu.com/jaunty/gitmagic[Ubuntu package (Jaunty Jackalope)] also available. Handy http://csdcf.stanford.edu/status/[when this server is offline for maintenance]. === Thanks! === -Kudos to Dustin Sallings, Alberto Bertogli, James Cameron, Douglas Livingstone, Michael Budde, Richard Albury, Tarmigan, Derek Mahar and Frode Aannevik for suggestions and improvements. [If I've left you out, please tell me because I often forget to update this section.] +Kudos to Dustin Sallings, Alberto Bertogli, James Cameron, Douglas Livingstone, Michael Budde, Richard Albury, Tarmigan, Derek Mahar and Frode Aannevik for suggestions and improvements. Thanks to Daniel Baumann for creating and maintaining the Debian package. Thanks also to JunJie, Meng and JiangWei for the Chinese translation. [If I've left you out, please tell me because I often forget to update this section.] + +My gratitute goes to many others for your support and praise. I wish this were a real physical book, so I could quote your generous words on the cover to promote it! In seriousness, I greatly appreciate each message. Reading one always brightens my mood. === License ===