Improve sync-all usage doc

1 files changed, 60 insertions, 46 deletions

diff --git a/sync-all b/sync-all
index 064a2728a5..025b60ddfb 100755
--- a/sync-all
+++ b/sync-all
@@ -438,7 +438,8 @@ sub help
 Usage:
 
 ./sync-all [-q] [-s] [--ignore-failure] [-r repo] [--checked-out] [--bare]
-           [--nofib] [--extra] [--testsuite] [--resume] cmd [git flags]
+           [--nofib] [--extra] [--testsuite] [--no-dph] [--resume]
+           cmd [git flags]
 
 Applies the command "cmd" to each repository in the tree.
 
@@ -465,12 +466,12 @@ and then we can pull from this other tree with
 get
 
     Clones all sub-repositories from the same place that the ghc
-    repository was cloned from.  See "which repos to use" below
+    repository was cloned from. See "which repos to use" below
     for details of how the subrepositories are laid out.
 
     There are various --<package-tag> options that can be given
-    before "get" that enable extra repositories.  The full list is
-    given at the end of this help.  For example:
+    before "get" that enable extra repositories. The full list is
+    given at the end of this help. For example:
 
     ./sync-all --testsuite get
 
@@ -482,13 +483,13 @@ remote rm <remote-name>
 remote set-url [--push] <remote-name>
 
     Runs a "git remote" command on each subrepository, adjusting the
-    repository location in each case appropriately.  For example, to
+    repository location in each case appropriately. For example, to
     add a new remote pointing to the upstream repositories:
 
     ./sync-all -r http://darcs.haskell.org/ remote add upstream
 
     The -r flag points to the root of the repository tree (see "which
-    repos to use" below).  For a repository on the local filesystem it
+    repos to use" below). For a repository on the local filesystem it
     would point to the ghc reposiroty, and for a remote repository it
     points to the directory containing "ghc.git".
 
@@ -515,30 +516,28 @@ any extra arguments to git:
   status
 
 -------------- Flags -------------------
-  These flags are given *before* the command and modify the way
-  sync-all behaves.  Flags given *after* the command are passed to
-  git.
+These flags are given *before* the command and modify the way sync-all behaves.
+Flags given *after* the command are passed to git.
 
   -q says to be quiet, and -s to be silent.
 
-  --resume will restart a command that failed, from the repo at which
-  it failed. This means you don't need to wait while, e.g., "pull"
-  goes through all the repos it's just pulled, and tries to pull them
-  again.
+  --resume will restart a command that failed, from the repo at which it
+  failed. This means you don't need to wait while, e.g., "pull" goes through
+  all the repos it's just pulled, and tries to pull them again.
 
   --ignore-failure says to ignore errors and move on to the next repository
 
   -r repo says to use repo as the location of package repositories
 
-  --checked-out says that the remote repo is in checked-out layout, as
-  opposed to the layout used for the main repo.  By default a repo on
-  the local filesystem is assumed to be checked-out, and repos accessed
-  via HTTP or SSH are assumed to be in the main repo layout; use
-  --checked-out to override the latter.
+  --checked-out says that the remote repo is in checked-out layout, as opposed
+  to the layout used for the main repo. By default a repo on the local
+  filesystem is assumed to be checked-out, and repos accessed via HTTP or SSH
+  are assumed to be in the main repo layout; use --checked-out to override the
+  latter.
 
-  --bare says that the local repo is in bare layout, same as the main repo.
-  It also means that these repos are bare. You only have to use this flag if
-  you don't have a bare ghc.git in the current directory and would like to 'get'
+  --bare says that the local repo is in bare layout, same as the main repo. It
+  also means that these repos are bare. You only have to use this flag if you
+  don't have a bare ghc.git in the current directory and would like to 'get'
   all of the repos bare. Requires packages.conf to be present in the current
   directory (a renamed packages file from the main ghc repo).
 
@@ -546,34 +545,49 @@ any extra arguments to git:
         --checked-out: describes the layout of the remote repository tree.
         --bare:        describes the layout of the local repository tree.
 
-  --nofib, --testsuite also get the nofib and testsuite repos respectively
+  --nofib also clones the nofib benchmark suite
+
+  --testsuite also clones the ghc testsuite 
+
+  --extra also clone some extra library packages
+
+  --no-dph avoids cloning the dph pacakges
+
+
+------------ Checking out a branch -------------
+To check out a branch you can run the following command:
+
+  \$ ./sync-all checkout ghc-7.4
 
 
 ------------ Which repos to use -------------
-  sync-all uses the following algorithm to decide which remote repos to use
-
-  It always computes the remote repos from a single base, <repo_base>
-  How is <repo_base> set?
-    If you say "-r repo", then that's <repo_base>
-    otherwise <repo_base> is set by asking git where the ghc repo came
-    from, and removing the last component (e.g. /ghc.git/ or /ghc/).
-
-  Then sync-all iterates over the package found in the file
-  ./packages; see that file for a description of the contents.
-
-    If <repo_base> looks like a local filesystem path, or if you give
-    the --checked-out flag, sync-all works on repos of form
-          <repo_base>/<local-path>
-    otherwise sync-all works on repos of form
-          <repo_base>/<remote-path>
-    This logic lets you say
-      both    sync-all -r http://darcs.haskell.org/ghc-6.12 remote add ghc-6.12
-      and     sync-all -r ../working remote add working
-    The latter is called a "checked-out tree".
-
-  NB: sync-all *ignores* the defaultrepo of all repos other than the
-  root one.  So the remote repos must be laid out in one of the two
-  formats given by <local-path> and <remote-path> in the file 'packages'.
+sync-all uses the following algorithm to decide which remote repos to use
+
+It always computes the remote repos from a single base, <repo_base> How is
+<repo_base> set? If you say "-r repo", then that's <repo_base> otherwise
+<repo_base> is set by asking git where the ghc repo came from, and removing the
+last component (e.g. /ghc.git/ or /ghc/).
+
+Then sync-all iterates over the package found in the file ./packages; see that
+file for a description of the contents.
+
+If <repo_base> looks like a local filesystem path, or if you give the
+--checked-out flag, sync-all works on repos of form:
+
+  <repo_base>/<local-path>
+
+otherwise sync-all works on repos of form:
+
+  <repo_base>/<remote-path>
+
+This logic lets you say
+  both    sync-all -r http://darcs.haskell.org/ghc-6.12 remote add ghc-6.12
+  and     sync-all -r ../working remote add working
+The latter is called a "checked-out tree".
+
+sync-all *ignores* the defaultrepo of all repos other than the root one. So the
+remote repos must be laid out in one of the two formats given by <local-path>
+and <remote-path> in the file 'packages'.
 
 Available package-tags are:
 END