Skip to content

GitLab

Commit 08024e90 authored by kkm's avatar kkm
Browse files

Documentation changes: added Git tutorial, removed Subversion tutorial and... 

Documentation changes: added Git tutorial, removed Subversion tutorial and updated multiple references from Subversion to Git and from SourceForge to Kaldi's own web site or GitHub as appropriate.
parent 1d24e8c9
Hide whitespace changes
Inline Side-by-side
Showing with 375 additions and 205 deletions
src/doc/about.dox
View file @ 08024e90
......@@ -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
View file @ 08024e90
......@@ -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
View file @ 08024e90
......@@ -22,54 +22,40 @@
\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.
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.
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,
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 (unfortunately, not actively
maintained and woefully out of date) 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
View file @ 08024e90
......@@ -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
View file @ 08024e90
......@@ -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
View file @ 08024e90
......@@ -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
View file @ 08024e90
......@@ -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
......@@ -169,6 +169,7 @@ If you need to debug a program that takes command-line arguments, you can do it
\endverbatim
or you can invoke gdb without arguments and then type "r arg1 arg2..." at the prompt.
\todo This paragraph is full of lies!
When you are done, and it compiles, type
\verbatim
svn diff
......@@ -176,7 +177,7 @@ svn diff
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
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
......@@ -190,12 +191,12 @@ svn commit --username=your_sourceforge_username -m "Added a unit-test in matrix/
\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 +212,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 +220,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 +265,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 +286,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 +297,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 0 → 100644
View file @ 08024e90
// 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
Branch fishfix set up to track remote branch master from golden.
Switched to a new branch 'fishfix'
kkm@yupana:~/kaldi[myfix *]$
\endverbatim
So what we did here, we first \em fetched the current changes to the golden
repository to your machine.
This did not update your master