Merge pull request #50 from kkm000/gittutorial

Documentation changes related to Git migration

src/doc/about.dox

@@ -33,12 +33,12 @@
   @section about_name The name Kaldi
 
   According to legend, Kaldi was the Ethiopian goatherder who discovered the
-  coffee plant.  
+  coffee plant.
 
   @section about_compare Kaldi's versus other toolkits
 
   Kaldi is similar in aims and scope to HTK.  The goal is to have modern and
-  flexible code, written in C++, that is easy to modify and extend.  
+  flexible code, written in C++, that is easy to modify and extend.
   Important features include:
     - Code-level integration with Finite State Transducers (FSTs)
        - We compile against the OpenFst toolkit (using it as a library).
@@ -49,21 +49,21 @@
        - As far as possible, we provide our algorithms in the most generic
          form possible.  For instance, our decoders are templated on an
          object that provides a score indexed by a (frame, fst-input-symbol)
-         tuple.  This means the decoder could work from any suitable source 
-         of scores, such as a neural net.  
+         tuple.  This means the decoder could work from any suitable source
+         of scores, such as a neural net.
     - Open license
        - The code is licensed under Apache 2.0, which is one of the least
          restrictive licenses available.
     - Complete recipes
-       - Our goal is to make available complete recipes for building 
+       - Our goal is to make available complete recipes for building
          speech recognition systems, that work from widely available
          databases such as those provided by the Linguistic Data
-         Consortium (LDC).  
+         Consortium (LDC).
 
-   The goal of releasing complete recipes is an important aspect of Kaldi. 
-   Since the code is publicly available under a license that permits 
+   The goal of releasing complete recipes is an important aspect of Kaldi.
+   Since the code is publicly available under a license that permits
    modifications and re-release, we would like to encourage people to release
-   their code, along with their script directories, in a similar format to 
+   their code, along with their script directories, in a similar format to
    Kaldi's own example script.
 
    We have tried to make Kaldi's documentation as complete as possible given time
@@ -75,7 +75,7 @@
    to an expert.  In the future we hope to make it somewhat more accessible,
    bearing in mind that our intended audience is speech recognition researchers or
    researchers-in-training.  In general, Kaldi is not a speech recognition
-   toolkit "for dummies."  It will allow you to do many kinds of operations that 
+   toolkit "for dummies."  It will allow you to do many kinds of operations that
    don't make sense.
 
    @section about_flavor The flavor of Kaldi
@@ -88,39 +88,39 @@
 
    - We emphasize generic algorithms and universal recipes
       - By "generic algorithms" we mean things like linear
-        transforms, rather than those that are specific to speech 
+        transforms, rather than those that are specific to speech
         in some way.  But we don't intend to be too dogmatic about this,
         if more specific algorithms are useful.
-      - We would like recipes that can be run on any data-set, rather than 
+      - We would like recipes that can be run on any data-set, rather than
         those that have to be customized.
    - We prefer provably correct algorithms
       - The recipes have been designed in such a way that in principle they
-        should never fail in a catastophic way.  There has been an effort to avoid recipes and 
+        should never fail in a catastophic way.  There has been an effort to avoid recipes and
         algorithms that could possibly fail, even if they don't fail in the
         "normal case" (one example: FST weight-pushing, which normally helps but
         can crash or make things much worse in certain cases).
    - Kaldi code is thoroughly tested.
-      - The goal is for all or nearly all the code to have corresponding 
-        test routines.  
+      - The goal is for all or nearly all the code to have corresponding
+        test routines.
    - We try to keep the simple cases simple.
       - There is a danger when building a large speech toolkit that the
         code can become a forest of rarely used alternatives.  We are trying to avoid
         this by structuring the toolkit in the following way.  Each command-line
         program generally works for a limited set of cases (e.g. a decoder
         might just work for GMMs).  Thus, when you add a new type of model, you create
-        a new command-line decoder (that calls the same underlying templated code).  
+        a new command-line decoder (that calls the same underlying templated code).
    - Kaldi code is easy to understand.
       - Even though the Kaldi toolkit as a whole may get very large, we aim
         for each individual part of it to be understandable without too much
         effort.  We will accept some code duplication if it improves the
         understandability of individual pieces.
    - Kaldi code is easy to reuse and refactor.
-      - We aim for the toolkit to as loosely coupled as possible. 
+      - We aim for the toolkit to as loosely coupled as possible.
         In general this means that any given header should need to \#include as
         few other header files as possible.  The matrix library, in particular,
         only depends on code in one other subdirectory so it can be used independently
         of almost all the rest of Kaldi.
-   
+
   @section about_status Status of the project
 
  Currently, we have code and scripts for most standard techniques, including all standard
@@ -134,12 +134,9 @@
  Note: after an early phase in which we intended to use version numbers for
  major releases of Kaldi ("v1" and so on), we realized that these type of
  releases do not mesh well with the natural style of development, which is very
- continuous.  Currently we maintain two major versions of Kaldi: the "trunk"
- version, and the "complete" version (which maintains some little-used features
- that were deleted from trunk).  We also maintain various sandboxes for feature
- development; these are merged back into trunk when the feature is complete.
- For most purposes, the "trunk" is the version you should use, and you should 
- frequently do "svn up" to keep it up to date; see \ref install for more details.
+ continuous.  Currently we maintain only the "master" development branch, and
+ this is the version you should use. Also,
+ frequently do "git pull" to keep it up to date; see \ref install for more details.
 
  See \ref roadmap for details of features we are currently working on.
 

src/doc/dependencies.dox

@@ -33,7 +33,7 @@
     grid will have NVidia GPUs which you can use for neural net training,
     and you can reserve these on the queue by adding some extra option to qsub.
     See \ref queue for more information.
-  
+
     We have started a separate project called <a
     href=https://sourceforge.net/projects/kluster/> Kluster </a> that shows you
     how to create such a cluster on Amazon's EC2; MIT's <a
@@ -65,7 +65,7 @@
    will not work there, and we are not very actively maintaining the Windows
    compatibility of the code or the Windows build scripts (we fix problems when
    we are told about them though).
-   
+
    \section dependencies_packages Software packages required
 
 
@@ -73,9 +73,9 @@
    order to install Kaldi.  The full list is not important since the installation
    scripts will tell you what you are missing.
 
-    - Subversion (svn): this is needed to download Kaldi and other software that it depends on.
+    - Git: this is needed to download Kaldi and other software that it depends on.
     - wget is required for the installation of some non-Kaldi components described below
-    - The example scripts require standard UNIX utilities such as bash, 
+    - The example scripts require standard UNIX utilities such as bash,
       perl, awk, grep, and make.
 
    It can also be helpful if you have an ATLAS linear-algebra package installed
@@ -91,7 +91,7 @@
    non-exhaustive list).
 
     - OpenFst:  we compile against this and use it heavily.
-    - IRSTLM: this a language modeling toolkit.  Some of the example scripts require it but 
+    - IRSTLM: this a language modeling toolkit.  Some of the example scripts require it but
       it is not tightly integrated with Kaldi; we can convert any Arpa format
       language model to an FST.
       - The IRSTLM build process requires automake, aclocal, and libtoolize
@@ -102,9 +102,9 @@
       as wav.  It's needed for the example scripts that use LDC data.
     - sclite: this is for scoring and is not necessary as we have our own, simple
       scoring program (compute-wer.cc).
-    - ATLAS, the linear algebra library.  This is only needed for the headers; in 
+    - ATLAS, the linear algebra library.  This is only needed for the headers; in
       typical setups we expect that ATLAS will be on your system.  However, if it not
-      already on your system you can compile ATLAS as long as your machine does not 
+      already on your system you can compile ATLAS as long as your machine does not
       have CPU throttling enabled.
     - CLAPACK, the linear algebra library (we download the headers).
       This is useful only on systems where you don't have ATLAS and are

src/doc/install.dox

@@ -22,54 +22,35 @@
  \page install Downloading and installing Kaldi
 
 
-  \section install_transition  Transition to github
+ \section install_download  Dowloading Kaldi
 
-  Due to the long recent sourceforge outage, we have now transitioned to
- github for all future development.  We still intend to maintain a
- read-only subversion mirror of the github parent, located at sourceforge and mirrored
- by us; however, we won't be able to set that up until Sourceforge comes back up.
-
-  While sourceforge is still down, the easiest way to access Kaldi as follows:
-\verbatim
-  git clone https://github.com/kaldi-asr/kaldi.git
-\endverbatim
- You can then keep it up-to-date using "git pull".
-  When sourceforge comes back up, you will be free to access it either through github
-  or through the subversion commands below.
-
- If you may want to contribute to Kaldi, this will mostly be done using pull requests.
- You would first log in to github and go to https://github.com/kaldi-asr/kaldi and click on
- "fork" to fork the repository.  Then, in your local fork of the repository you would
- do your work in a differently named branch, and generate a pull request through the
- online interface of github.  We will soon provide more detailed instructions on this.
-
- \section install_download  Dowloading Kaldi (old instructions)
-
-  You first need to install Subversion (SVN).  The most current version of Kaldi,
+  We have now transitioned to GitHub for all future development.
+  You first need to install Git. The most current version of Kaldi,
   possibly including unfinished and experimental features, can
    be downloaded by typing into a shell:
   \verbatim
-    svn co https://svn.code.sf.net/p/kaldi/code/trunk kaldi-trunk
+    git clone https://github.com/kaldi-asr/kaldi.git kaldi-trunk --origin golden
+    cd kaldi-trunk
   \endverbatim
  If you want to get updates and bug fixes you can go to some checked-out
  directory, and type
   \verbatim
-    svn update
+    git pull
   \endverbatim
- If "svn update" prints out scary looking messages about conflicts (caused by
- you changing parts of files that were later modified centrally),
- you may have to resolve the conflicts; for that, we recommend that you
- read about how svn works.
+ If "git pull" prints out a message telling it cannot pull the remote
+ changes because you have changed files locally,
+ you may have to commit locally and merge your changes, or stash them temporarily
+ and then apply back the stash; for that, we recommend that you
+ read about how Git works, possibly starting with the \ref tutorial_git.
 
 
   \section install_install Installing Kaldi
-   
-  The top-level installation instructions are in the file INSTALL. 
-  For Windows, there are separate instructions (unfortunately, not actively maintained and woefully out of date)
-   in windows/INSTALL.
+
+  The top-level installation instructions are in the file \c INSTALL.
+  For Windows, there are separate instructions in \c windows/INSTALL.
   See also \ref build_setup which explains how the build process
   works internally.
 
-  The example scripts are in egs/
+  The example scripts are in \c egs/
 
 */

src/doc/legal.dox

@@ -24,11 +24,11 @@
  for that.  In this page we explain what the legal stuff means (as we
  understand it).
 
- The code and other content (e.g. scripts, documentation) in 
+ The code and other content (e.g. scripts, documentation) in
  Kaldi is released under the Apache license, version 2.0.  The Apache
  license is a popular "BSD-like" license.  This means you can use
  Kaldi for free and redistribute it, even for commercial purposes,
- although you can't take off the license headers (and under some 
+ although you can't take off the license headers (and under some
  circumstances you may have to distribute a license document).  Apache is
  not a ``viral'' license like the GPL, which forces you to release
  your modifications to the source code.  Also note that this project has no
@@ -54,22 +54,22 @@
  header on them that says something like:
 \verbatim
   // Copyright 2012  Joe M. Schmo
-  // 
+  //
 // See ../../COPYING for clarification regarding multiple authors
 //
   // Licensed under the Apache License, Version 2.0 (the "License");
-  // etc. 
+  // etc.
 \endverbatim
  However, if Joe Schmo works for Acme Corporation and releases code
- as part of his work, then (depending what country Joe lives in) the header 
+ as part of his work, then (depending what country Joe lives in) the header
  would probably look something like this:
 \verbatim
   // Copyright 2012  Acme Corporation
-  // 
+  //
 // See ../../COPYING for clarification regarding multiple authors
 //
   // Licensed under the Apache License, Version 2.0 (the "License");
-  // etc. 
+  // etc.
 \endverbatim
  This would be the case under some circumstances even if he did it
  in his spare time.  For example: the terms of Joe's employment with
@@ -83,18 +83,18 @@
  look something like this:
 \verbatim
   // Copyright 2012  Acme Corporation  Jane Doe
-  // 
+  //
 // See ../../COPYING for clarification regarding multiple authors
 //
   // Licensed under the Apache License, Version 2.0 (the "License");
-  // etc. 
+  // etc.
 \endverbatim
- In this case Acme Corporation and Jane Doe (and we're assuming that they 
+ In this case Acme Corporation and Jane Doe (and we're assuming that they
  agreed to this), jointly own the copyright on the code that they wrote.
  The order of names has no legal meaning.
  Joint ownership means that if either party chooses (and they don't have to
- both agree), they can release the code themselves under a different 
- license.  However, for Apache-licensed projects, there is 
+ both agree), they can release the code themselves under a different
+ license.  However, for Apache-licensed projects, there is
  typically no point in doing this, since Apache already
  allows for commercial use.
 
@@ -108,17 +108,17 @@
  The way this is normally handled is, Jane Doe
  should add a new Apache header at the top of the file, above the one
  mentioning Acme Corporation, and she should say something to the
- effect that the work is  derived from the original file from Acme 
+ effect that the work is  derived from the original file from Acme
  Corporation, and the whole modified file is being released under Apache.
  We haven't done it this way, because the project is very
- collaborative, and if we did it like this we would have extremely long copyright 
+ collaborative, and if we did it like this we would have extremely long copyright
  headers.  Instead we use the convention that if Jane makes a change,
  she simply adds her name to the list of authors in the copyright
  header.  We are treating this as
  a kind of shorthand for the whole multiple-header thing (this is
  explained in the COPYING file).  The way you can disambiguate
  between joint copyright ownership and derivative work, is to
- go back in the version history in subversion, and see what the original
+ go back in the version history in Git, and see what the original
  release contained.  We guess that most people won't care about
  this distinction, which is why we have not bothered to disambiguate it.
  For shell and perl scripts and other non-C++ content

src/doc/other.dox

@@ -23,18 +23,15 @@
  \page other Other Kaldi-related resources (and how to get help)
 
  The main places where Kaldi knowledge can be found are this website,
- and in the code repository (which we are currently in the process of moving
-from subversion to git; see \ref install for instructions).
+ and in the code repository (see \ref install for instructions).
  The repository contains the Kaldi code; the installation scripts;
  and example scripts for a number of different datasets, which are located
- in the sub-directory egs/).  
-  
-
- Kaldi's <a href=http://sourceforge.net/projects/kaldi/>project page on Sourceforge</a> contains
- a number of useful resources, but after the recent extended outage we are migrating away from
- Sourceforge.  <a href=http://kaldi-asr.org/>kaldi-asr.org/</a> is now the top-level
- location you should go to; see in particular information about help forums and email
- lists at <a href=http://kaldi-asr.org/forums.html>kaldi-asr.org/forums.html</a>.
+ in the sub-directory \c egs/).
+
+
+ Kaldi's <a href="http://kaldi-asr.org/">project page</a> contains
+ a number of useful resources; see in particular information about help forums and email
+ lists at <a href="http://kaldi-asr.org/forums.html">kaldi-asr.org/forums.html</a>.
 
 
 

src/doc/tutorial.dox

@@ -22,7 +22,7 @@
 
   - \subpage tutorial_prereqs "Prerequisites"
   - \subpage tutorial_setup "Getting started" (15 minutes)
-  - \subpage tutorial_svn "Version control with Subversion" (5 minutes)
+  - \subpage tutorial_git "Version control with Git" (5 minutes)
   - \subpage tutorial_looking "Overview of the distribution"  (25 minutes)
   - \subpage tutorial_running "Running the example scripts" (40 minutes)
   - \subpage tutorial_code "Reading and modifying the code" (30 minutes)

src/doc/tutorial_code.dox

@@ -36,7 +36,7 @@
 
 
  Go to the top-level directory (we called it kaldi-1) and then into
- src/.  
+ src/.
  First look at the file base/kaldi-common.h (don't follow the links within
  this document; view it from the shell or from an editor).  This \#includes a number of
  things from the base/ directory that are used by almost every Kaldi program.  You
@@ -56,7 +56,7 @@
 
 
  \section tutorial_code_matrix Matrix library (and modifying and debugging code)
- 
+
  Now look at the file matrix/matrix-lib.h.  See what files it includes.  This provides
  an overview of the kinds of things that are in the matrix library.  This library
  is basically a C++ wrapper for BLAS and LAPACK, if that means anything to you (if not,
@@ -69,7 +69,7 @@
  These types of commends, and block comments that begin with /**, are interpreted by the
  Doxygen software that automatically generates documentation.  It also generates the
  page you are reading right now (the source for this type of documentation
- is in src/doc/).  
+ is in src/doc/).
 
  At this point we would like you to modify the code and compile it.  We will be
  adding a test function to the file matrix/matrix-lib-test.cc.  As mentioned
@@ -92,13 +92,13 @@ void UnitTestAddVec() {
   InitRand(&v);
   InitRand(&w);
   Vector<Real> w2(w); // w2 is a copy of w.
-  Real f = RandGauss(); 
+  Real f = RandGauss();
   w.AddVec(f, v); // w <-- w + f v
   for (int32 i = 0; i < dim; i++) {
     Real a = w(i), b = f * w2(i) + v(i);
     AssertEqual(a, b); // will crash if not equal to within
     // a tolerance.
-  }        
+  }
 }
 \endverbatim
 Add this code to the file matrix-lib-test.cc, just above the function
@@ -109,7 +109,7 @@ MatrixUnitTest().  Then, inside MatrixUnitTest(), add the line:
 It doesn't matter where in the function you add this.
 Then type "make test".  There should be an error (a semicolon that should be
 a comma); fix it and try again.
-Now type "./matrix-lib-test".  This should crash with an assertion failure, 
+Now type "./matrix-lib-test".  This should crash with an assertion failure,
 because there was another mistake in the unit-test code.  Next we will debug it.
 Type
 \verbatim
@@ -130,7 +130,7 @@ values of a and b ("p" is short for "print").  Your screen should look someting
 $5 = -0.931363404
 (gdb) p b
 $6 = -0.270584524
-(gdb) 
+(gdb)
 \endverbatim
 The exact values are, of course, random, and may be different for you.  Since
 the numbers are considerably different, it's clear that it's not just a question
@@ -145,7 +145,7 @@ $8 = 0.281656802
 $9 = -0.931363404
 (gdb) p w2.data_[0]
 $10 = -1.07592916
-(gdb) 
+(gdb)
 \endverbatim
 This may help you work out that the expression for "b" is wrong.  Fix it in the code, recompile, and run
 again (you can just type "r" in the gdb prompt to rerun).  It should now run OK.  Force gdb to break into the
@@ -171,31 +171,25 @@ or you can invoke gdb without arguments and then type "r arg1 arg2..." at the pr
 
 When you are done, and it compiles, type
 \verbatim
-svn diff
-\endverbatim
-to see what changes you made.  If you are contributing to the Kaldi project and you
-are planning to commit code in the near future, you
-may want to revert the changes you made so you don't accidentally commit them.  The following
-commands will save the file you modified in case you need it later, and will revert to 
-the original version:
-\verbatim
- cp matrix-lib-test.cc matrix-lib-test.cc.tmp
- svn revert matrix-lib-test.cc
-\endverbatim
-If you actually wanted to commit the changes, and you had an account on Sourceforge, you
-would have to ask us to add you to the Kaldi project, and you would type something like
-\verbatim
-svn commit --username=your_sourceforge_username -m "Added a unit-test in matrix/ directory."
+ git diff
 \endverbatim
+to see what changes you made.  If you are contributing to the Kaldi project and
+planning to send us code in the near future, you
+may want to commit them to a branch as described in the \tutorial_git, so that you
+can generate a clean <a href="https://help.github.com/articles/using-pull-requests/">
+GitHub pull request</a> later. We recommend that you familiarize
+yourself with Git branches even if you are not contributing your changes
+outright; Git is a powerful tool to maintain your local code changes as well as
+those you may contribute.
 
 \section tutorial_code_acoustic Acoustic modeling code
 
-Next look at gmm/diag-gmm.h (this class stores a Gaussian Mixture Model).  
+Next look at gmm/diag-gmm.h (this class stores a Gaussian Mixture Model).
 The class DiagGmm may look a bit confusing as
 it has many different accessor functions.  Search for "private" and look
 at the class member variables (they always end with an underscore, as per
 the Kaldi style).  This should make it clear how we store the GMM.
-This is just a single GMM, not a whole collection of GMMs. 
+This is just a single GMM, not a whole collection of GMMs.
 Look at gmm/am-diag-gmm.h; this class stores a collection of GMMs.
 Notice that it does not inherit from anything.
 Search for "private" and you can see the member variables (there
@@ -211,7 +205,7 @@ keeping the rest of the system the same.  We'll come to this other stuff later.
 
 Next look at feat/feature-mfcc.h.  Focus on the MfccOptions struct.
 The struct members give you some idea what kind of options are supported
-in MFCC feature extraction.  
+in MFCC feature extraction.
 Notice that some struct members are options structs themselves.
 Look at the Register function.  This is standard in Kaldi options classes.
 Then look at featbin/compute-mfcc-feats.cc (this is a command-line
@@ -219,8 +213,8 @@ program) and search for Register.
 You can see where the Register function of the options struct is called.
 To see a complete list of the options supported for MFCC feature extraction,
 execute the program featbin/compute-mfcc-feats with no arguments.
-Recall that you saw some of these options being registered in 
-the MfccOptions class, and others being registered in 
+Recall that you saw some of these options being registered in
+the MfccOptions class, and others being registered in
 featbin/compute-mfcc-feats.cc.  The way to specify options is --option=value.
 Type
 \verbatim
@@ -264,11 +258,11 @@ adding statistics together and evaluating some kind of objective function
 (e.g. a likelihood).  In the normal recipe, it actually points to a class
 that contains sufficient statistics for estimating a diagonal Gaussian p.d.f..
 
-Do 
+Do
 \verbatim
 less exp/tri1/log/acc_tree.log
 \endverbatim
-There won't be much information in this file, but you can see the command 
+There won't be much information in this file, but you can see the command
 line.  This program accumulates the single-Gaussian statistics for each HMM-state
 (actually, pdf-class) of each seen triphone context.
 The <DFN>--ci-phones</DFN> options is so that it knows to avoid accumulating separate
@@ -285,7 +279,7 @@ This program does the decision-tree clustering; it reads in the statistics
 that were output by.  It is basically a wrapper for the BuildTree function discussed above.
 The questions that it asks in the decision-tree clustering are automatically generated,
 as you can see in the script steps/train_tri1.sh (look for the programs cluster-phones
-and compile-questions).  
+and compile-questions).
 
 
 
@@ -296,7 +290,7 @@ topologies for a number of phones.  In general each phone can have a different
 topology.  The topology includes "default" transitions, used for initialization.
 Look at the example topology in the extended comment at the top of the header.
 There is a tag <PdfClass> (note: as with HTK text formats,
-this file looks vaguely XML-like, but it is not really XML).  
+this file looks vaguely XML-like, but it is not really XML).
 The <PdfClass> is always the same as the HMM-state (<State>) here; in
 general, it doesn't have to be.  This is a mechanism to enforce tying of
 distributions between distinct HMM states; it's possibly useful if you want to

src/doc/tutorial_git.dox

+// doc/tutorial_git.dox
+
+// Copyright 2015 Smart Action Company LLC
+
+// See ../../COPYING for clarification regarding multiple authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//  http://www.apache.org/licenses/LICENSE-2.0
+
+// THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
+// WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
+// MERCHANTABLITY OR NON-INFRINGEMENT.
+// See the Apache 2 License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ \page tutorial_git Kaldi Tutorial: Version control with Git (5 minutes)
+
+    \ref tutorial "Up: Kaldi tutorial" <BR>
+    \ref tutorial_setup "Previous: Getting started" <BR>
+    \ref tutorial_looking "Next: Overview of the distribution" <BR>
+
+Git is a distributed version control system.  This means that, unlike
+Subversion, there are multiple copies of the repository, and the changes are
+transferred between these copies in multiple different ways explicitly, but most
+of the time one's work is backed by a single copy of the repository.  Because of
+this multiplicity of copies, there are multiple possible \em workflows that you
+may want to follow.  Here's one we think best suits you if you just want to
+<i>compile and use</i> Kaldi at first, but then at some point optionally decide
+to \em contribute your work back to the project.
+
+\section tutorial_git_git_setup First-time Git setup
+
+If you have never used Git before,
+<a href="https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup">
+perform some minimal configuration first</a>.  At the very least, set up your
+name and e-mail address:
+
+\verbatim
+$ git config --global user.name "John Doe"
+$ git config --global user.email johndoe@example.com
+\endverbatim
+
+Also, set short names for the most useful git commands you type most often.
+
+\verbatim
+$ git config --global alias.co checkout
+$ git config --global alias.br branch
+$ git config --global alias.st status
+\endverbatim
+
+Another very useful utility comes with <tt>git-prompts.sh</tt>,
+a bash prompt extension utility for Git (if you do not have it,
+search the internet how to install it on your system).
+When installed, it provides a shell function \c __git_ps1 that,
+when added to the prompt,
+expands into the current branch name and pending commit markers,
+so you do not forget where you are.
+You may modify your \c PS1 shell variable so that it includes literally
+<tt>$(__git_ps1 "[%s]")</tt>.
+I have this in my \c ~/.bashrc:
+
+\code{.sh}
+PS1='\[\033[00;32m\]\u@\h\[\033[0m\]:\[\033[00;33m\]\w\[\033[01;36m\]$(__git_ps1 "[%s]")\[\033[01;33m\]\$\[\033[00m\] '
+export GIT_PS1_SHOWDIRTYSTATE=true GIT_PS1_SHOWSTASHSTATE=true
+# fake __git_ps1 when git-prompts.sh not installed
+if [ "$(type -t __git_ps1)" == "" ]; then
+  function __git_ps1() { :; }
+fi
+\endcode
+
+\section tutorial_git_workflow The User Workflow
+
+Set up your repository and the working directory with this command:
+
+\verbatim
+kkm@yupana:~$ git clone https://github.com/kaldi-asr/kaldi.git --branch master --single-branch --origin golden
+Cloning into 'kaldi'...
+remote: Counting objects: 51770, done.
+remote: Compressing objects: 100% (8/8), done.
+remote: Total 51770 (delta 2), reused 0 (delta 0), pack-reused 51762
+Receiving objects: 100% (51770/51770), 67.72 MiB | 6.52 MiB/s, done.
+Resolving deltas: 100% (41117/41117), done.
+Checking connectivity... done.
+kkm@yupana:~$ cd kaldi/
+kkm@yupana:~/kaldi[master]$
+\endverbatim
+
+Now, you are ready to configure and compile Kaldi and work with it.
+Once in a while you want the latest changes in your local branch.
+This is akin to what you usually did with <tt>svn update</tt>.
+
+But please first let's agree to one thing:
+you do not commit any files on the master branch.
+We'll get to that below.
+So far, you are only using the code.
+It will be hard to untangle if you do not follow the rule,
+and Git is so amazingly easy at branching,
+that you always want to do your work on a branch.
+
+\verbatim
+kkm@yupana:~/kaldi[master]$ git pull golden
+remote: Counting objects: 148, done.
+remote: Compressing objects: 100% (55/55), done.
+remote: Total 148 (delta 111), reused 130 (delta 93), pack-reused 0
+Receiving objects: 100% (148/148), 18.39 KiB | 0 bytes/s, done.
+Resolving deltas: 100% (111/111), completed with 63 local objects.
+From https://github.com/kaldi-asr/kaldi
+   658e1b4..827a5d6  master     -> golden/master
+\endverbatim
+
+The command you use is <tt>git pull</tt>,
+and \c golden is the alias we used to designate the main replica of the Kaldi
+repository before.
+
+\section tutorial_git_contributor From User To Contributor
+
+At some point you decided to change Kaldi code,
+be it scripts or source. Maybe you made a simple bug fix.
+Maybe you are contributing a whole recipe. In any case,
+your always do your work on a branch.
+Even if you have uncommitted changes, Git handles that.
+For example, you just realized that the \c fisher_english recipe does not
+actually make use of \c hubscr.pl for scoring, but checks it exists and
+fails.
+You quickly fixed that in your work tree and want to share this change
+with the project.
+
+\subsection tutorial_git_branch Work locally on a branch
+
+\verbatim
+kkm@yupana:~/kaldi[master *]$ git fetch golden
+kkm@yupana:~/kaldi[master *]$ git co golden/master -b fishfix --no-track
+M       fisher_english/s5/local/score.sh