en/preface.txt

   1 = Git Magic =
   2 Ben Lynn
   3 August 2007
   4
   5 == Preface ==
   6
   7 http://git.or.cz/[Git] is a version control Swiss army knife. A reliable versatile multipurpose revision control tool whose extraordinary flexibility makes it tricky to learn, let alone master. I'm recording what I've figured out so far in these pages, because I initially had difficulty understanding http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[the Git user manual].
   8
   9 As Arthur C. Clarke observed, any sufficiently advanced technology is indistinguishable from magic. This is a great way to approach Git: newbies can ignore its inner workings and view Git as a gizmo that can amaze friends and infuriate enemies with its wondrous abilities.
  10
  11 Rather than go into details, we provide rough instructions for particular effects. After repeated use, gradually you will understand how each trick works, and how to tailor the recipes for your needs.
  12
  13 .Translations
  14
  15  - http://docs.google.com/View?id=dfwthj68_675gz3bw8kj[Chinese (Simplified)]: by JunJie, Meng and JiangWei. Hosted by Google Docs.
  16  - link:/~blynn/gitmagic/intl/es/[Spanish]: by Rodrigo Toledo.
  17
  18 .Other Editions
  19
  20  - link:book.html[Single webpage]: barebones HTML, with no CSS.
  21  - link:book.pdf[PDF file]: printer-friendly.
  22  - http://packages.debian.org/search?searchon=names&keywords=gitmagic[Debian 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].
  23
  24 === Thanks! ===
  25
  26 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, and Rodrigo Toledo for the Spanish translation. [If I've left you out, please tell me because I often forget to update this section.]
  27
  28 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.
  29
  30 .Free Git hosting
  31
  32  - http://repo.or.cz/[http://repo.or.cz/] hosts free projects. The first Git hosting site. Founded and maintained by one of the earliest Git developers.
  33  - http://gitorious.org/[http://gitorious.org/] is another Git hosting site aimed at open-source projects.
  34  - http://github.com/[http://github.com/] hosts open-source projects for free, and private projects for a fee.
  35
  36 Many thanks to each of these sites for hosting this guide.
  37
  38 === License ===
  39
  40 This guide is released under http://www.gnu.org/licenses/gpl-3.0.html[the GNU General Public License version 3]. Naturally, the source is kept in a Git
  41 repository, and can be obtained by typing:
  42
  43  $ git clone git://repo.or.cz/gitmagic.git  # Creates "gitmagic" directory.
  44
  45 or from one of the mirrors:
  46
  47  $ git clone git://github.com/blynn/gitmagic.git
  48  $ git clone git://gitorious.org/gitmagic/mainline.git
  49
  50 === How to Translate This Guide ===
  51
  52 Clone the source, then create a directory corresponding to the target http://www.iana.org/assignments/language-subtag-registry[language's IETF tag]: see
  53 http://www.w3.org/International/articles/language-tags/Overview.en.php[the W3C article on internationalization]. For example, English is "en", Japanese is "ja", and Traditional Chinese is "zh-Hant". In the new directory, and translate the +txt+ files from the "en" subdirectory.
  54
  55 For instance, to translate the guide into http://en.wikipedia.org/wiki/Klingon_language[Klingon], you might type:
  56
  57  $ git clone git://repo.or.cz/gitmagic.git
  58  $ cd gitmagic
  59  $ mkdir tlh  # "tlh" is the IETF language code for Klingon.
  60  $ cd tlh
  61  $ cp ../en/intro.txt .
  62  $ edit intro.txt  # Translate the file.
  63
  64 and so on for each text file. You can review your work incrementally:
  65
  66  $ make LANG=tlh
  67  $ firefox book.html
  68
  69 Commit your changes often, then let me know when they're ready.
  70 GitHub.com has an interface that facilitates this: fork the "gitmagic" project,
  71 push your changes, then ask me to merge.
  72
  73 I like to have translations follow the above scheme so my scripts can produce
  74 HTML and PDF versions. Also, it conveniently keeps all the translations in the
  75 official repository. But please do whatever suits you best: for example, the
  76 Chinese translators used Google Docs. I'm happy as long as your work
  77 enables more people to access my work.