src/Darcs/Commands/Init.lhs

   1 %  Copyright (C) 2002-2003 David Roundy
   2 %
   3 %  This program is free software; you can redistribute it and/or modify
   4 %  it under the terms of the GNU General Public License as published by
   5 %  the Free Software Foundation; either version 2, or (at your option)
   6 %  any later version.
   7 %
   8 %  This program is distributed in the hope that it will be useful,
   9 %  but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 %  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 %  GNU General Public License for more details.
  12 %
  13 %  You should have received a copy of the GNU General Public License
  14 %  along with this program; see the file COPYING.  If not, write to
  15 %  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16 %  Boston, MA 02110-1301, USA.
  17
  18 \subsection{darcs initialize}\label{initialize}
  19 \begin{code}
  20 module Darcs.Commands.Init ( initialize, initialize_cmd ) where
  21 import Darcs.Commands ( DarcsCommand(..), nodefaults )
  22 import Darcs.Arguments ( DarcsFlag, pristine_tree, working_repo_dir,
  23                         inventory_choices )
  24 import Darcs.Repository ( amNotInRepository, createRepository )
  25 \end{code}
  26
  27 \options{initialize}
  28
  29 \haskell{initialize_description}
  30
  31 \begin{code}
  32 initialize_description :: String
  33 initialize_description = "Initialize a new source tree as a darcs repository."
  34 \end{code}
  35 Call \verb|initialize| once for each project you work on. Run it from the top
  36 level directory of the project, with the project files already there.
  37 \verb|initialize| will set up all the directories and files darcs needs in order to
  38 start keeping track of revisions for your project.
  39
  40 \begin{code}
  41 initialize_help :: String
  42 initialize_help =
  43  "Call initialize once for each project you work on. Run it from the top\n"++
  44  "level directory of the project, with the project files already there.\n"++
  45  "Initialize will set up all the directories and files darcs needs in order to\n"++
  46  "start keeping track of revisions for your project.\n"
  47 \end{code}
  48
  49 \begin{code}
  50 initialize :: DarcsCommand
  51 initialize = DarcsCommand {command_name = "initialize",
  52                          command_help = initialize_help,
  53                          command_description = initialize_description,
  54                          command_extra_args = 0,
  55                          command_extra_arg_help = [],
  56                          command_prereq = amNotInRepository,
  57                          command_command = initialize_cmd,
  58                          command_get_arg_possibilities = return [],
  59                          command_argdefaults = nodefaults,
  60                          command_advanced_options = [],
  61                          command_basic_options = [pristine_tree, inventory_choices,
  62                                                   working_repo_dir]}
  63 \end{code}
  64
  65 \verb|initialize| creates a single directory named \verb|_darcs|, with contents
  66 for internal use. The one subdictory of interest to users is
  67 \verb'_darcs/prefs', which will include an empty file \verb'_darcs/prefs/motd'
  68 (see Section~\ref{motd}), as well as files named \verb'boring' and
  69 \verb'binaries', which contain useful defaults as described in Sections
  70 \ref{boring} \emph{et seq.}
  71
  72 \begin{options}
  73 --old-fashioned-inventory
  74 --hashed
  75 --darcs-2
  76 \end{options}
  77
  78 These options describe possible repository formats to use.
  79
  80 \verb'old-fashioned-inventory' is now deprecated and should be avoided if at
  81 all possible.
  82
  83 \verb'hashed' Offers several features while still being compatible with old-fashioned repositories. The specific features are:
  84
  85 \begin{itemize}
  86
  87 \item The hashed format allows for greater atomicity of operations. This makes for greater safety and simultaneously greater efficiency. These benefits, however, have not been fully realized in this release. For instance, with a hashed repository, there is no need for darcs push to require a repository lock, so you could record patches while waiting for a push to finish (for instance, if it's waiting on the test suite).
  88
  89 \item The \verb!_darcs/pristine! directory no longer holds the pristine
  90 cache. This disallows certain hackish short-cuts, but also dramatically
  91 reduces the danger of third-party programs (e.g. DreamWeaver) recursing
  92 into the pristine cache and corrupting darcs repositories.
  93
  94 \item Darcs get can optionally operate in a much faster ``lazy''
  95 fashion, meaning that patches are downloaded only when they are
  96 needed. This gives us much of the benefits of --partial repositories,
  97 without most of their disadvantages. This approach, however, does have
  98 several new dangers. First, some operations may unexpectedly require the
  99 download of large numbers of patches, which could be slow (but you could
 100 always interrupt with \verb!^C!). Secondly, if the source repository disappears,
 101 or you lose network connectivity, some operations may fail.
 102
 103 \item Darcs now supports caching of patches and file contents to reduce bandwidth and save disk space. It greatly speeds up a number of operations, and is essentially transparent. The only reason we don't enable it by default is because it creates a large directory in ~/.darcs/cache without the user's explicit consent.
 104
 105 \end{itemize}
 106
 107 \verb'darcs-2' Is the default.  It enables all available features, and
 108 requiring that all repos for a project use the same format. In addition to the
 109 features of the \verb'hashed' format described above, the \verb'darcs-2' format
 110 also enables the following:
 111
 112 \begin{itemize}
 113
 114 \item It should no longer be possible to confuse darcs or freeze it indefinitely by merging conflicting changes.
 115
 116 \item Identical primitive changes no longer conflict. This is a long-requested feature, and has far-reaching implications.
 117
 118 \end{itemize}
 119
 120 \begin{options}
 121 --no-pristine-tree
 122 \end{options}
 123 In order to save disk space, you can use \verb|initialize| with the
 124 \verb|--no-pristine-tree| flag to create a repository with no pristine
 125 tree.  Please see Section~\ref{disk-usage} for more information.
 126
 127 \begin{code}
 128 initialize_cmd :: [DarcsFlag] -> [String] -> IO ()
 129 initialize_cmd opts _ = createRepository opts
 130 \end{code}
 131