src/configuring_darcs.tex

   1 %  Copyright (C) 2004 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; if not, write to the Free Software Foundation,
  15 %  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  16
  17 \chapter{Configuring darcs}\label{configuring}
  18
  19 There are several ways you can adjust darcs' behavior to suit your needs.
  20 The first is to edit files in the \verb!_darcs/prefs/! directory of a
  21 repository.  Such configuration only applies when working with that
  22 repository.  To configure darcs on a per-user rather than per-repository
  23 basis (but with essentially the same methods), you can edit (or create)
  24 files in the \verb!~/.darcs/! directory (or on Microsoft Windows, the
  25 C:/Documents And Settings/user/Application Data/darcs directory).
  26 Finally, the behavior of some darcs commands can be modified by setting
  27 appropriate environment variables.
  28
  29 \input{Darcs/Repository/Prefs.lhs}
  30
  31 \input{Darcs/Repository/Motd.lhs}
  32
  33 \section{Environment variables}
  34
  35 There are a few environment variables whose contents affect darcs'
  36 behavior.  Here is a quick list of all the variables and their
  37 documentation in the rest of the manual:
  38
  39 \begin{tabular}{|l|r|}
  40 \hline
  41 \textbf{Variable} & \textbf{Section} \\
  42 \hline
  43 DARCS\_EDITOR, EDITOR, VISUAL & \ref{env:DARCS_EDITOR} \\
  44 DARCS\_PAGER, PAGER &  \ref{env:DARCS_PAGER} \\
  45 HOME & \ref{env:HOME} \\
  46 TERM & \ref{env:TERM} \\
  47 \hline
  48 DARCS\_EMAIL, EMAIL  & \ref{env:DARCS_EMAIL} \\
  49 \hline
  50 DARCS\_APPLY\_FOO & \ref{env:DARCS_X_FOO} \\
  51 DARCS\_GET\_FOO & \ref{env:DARCS_X_FOO} \\
  52 DARCS\_MGET\_FOO & \ref{env:DARCS_X_FOO} \\
  53 DARCS\_MGETMAX & \ref{env:DARCS_MGETMAX} \\
  54 DARCS\_PROXYUSERPWD & \ref{env:DARCS_PROXYUSERPWD} \\
  55 DARCS\_WGET & \ref{env:DARCS_WGET} \\
  56 DARCS\_SSH & \ref{env:DARCS_SSH} \\
  57 DARCS\_SCP & \ref{env:DARCS_SCP} \\
  58 DARCS\_SFTP & \ref{env:DARCS_SFTP} \\
  59 SSH\_PORT & \ref{env:SSH_PORT} \\
  60 \hline
  61 DARCS\_ALTERNATIVE\_COLOR & \ref{env:DARCS_ALWAYS_COLOR}\\
  62 DARCS\_ALWAYS\_COLOR & \ref{env:DARCS_ALWAYS_COLOR}\\
  63 DARCS\_DO\_COLOR\_LINES & \ref{env:DARCS_DO_COLOR_LINES}\\
  64 DARCS\_DONT\_COLOR   & \ref{env:DARCS_ALWAYS_COLOR} \\
  65 DARCS\_DONT\_ESCAPE\_TRAILING\_CR     & \ref{env:DARCS_DONT_ESCAPE_white}\\
  66 DARCS\_DONT\_ESCAPE\_TRAILING\_SPACES & \ref{env:DARCS_DONT_ESCAPE_white} \\
  67 DARCS\_DONT\_ESCAPE\_8BIT & \ref{env:DARCS_DONT_ESCAPE_nonascii}\\
  68 DARCS\_DONT\_ESCAPE\_ANYTHING & \ref{env:DARCS_DONT_ESCAPE_nonascii}\\
  69 DARCS\_DONT\_ESCAPE\_ISPRINT & \ref{env:DARCS_DONT_ESCAPE_nonascii}\\
  70 DARCS\_ESCAPE\_EXTRA & \ref{env:DARCS_DONT_ESCAPE_nonascii}\\
  71 DARCS\_DONT\_ESCAPE\_EXTRA & \ref{env:DARCS_DONT_ESCAPE_nonascii}\\
  72 \hline
  73 \end{tabular}
  74
  75 \section{General-purpose variables}
  76
  77 \paragraph{DARCS\_EDITOR}
  78 \label{env:DARCS_EDITOR}
  79 When pulling up an editor (for example, when adding a long comment in
  80 record), darcs uses the contents of DARCS\_EDITOR if it is defined.  If
  81 not, it tries the contents of VISUAL, and if that isn't defined (or fails
  82 for some reason), it tries EDITOR\@.  If none of those environment variables
  83 are defined, darcs tries \verb!vi!, \verb!emacs!, \verb!emacs -nw! and
  84 \verb!nano! in that order.
  85
  86 \paragraph{DARCS\_PAGER}
  87 \label{env:DARCS_PAGER}
  88 When using a pager for displaying a patch, darcs uses the contents of
  89 DARCS\_PAGER if it is defined.  If not, it tries the contents of PAGER
  90 and then \verb!less!.
  91
  92 \paragraph{DARCS\_TMPDIR}
  93 \label{env:DARCS_TMPDIR}
  94 If the environment variable DARCS\_TMPDIR is defined, darcs will use that
  95 directory for its temporaries.  Otherwise it will use TMPDIR, if that is
  96 defined, and if not that then \verb!/tmp! and if \verb!/tmp! doesn't exist,
  97 it'll put the temporaries in \verb!_darcs!.
  98
  99 This is very helpful, for example, when recording with a test suite that
 100 uses MPI, in which case using \verb!/tmp! to hold the test copy is no good,
 101 as \verb!/tmp! isn't shared over NFS and thus the \verb!mpirun! call will
 102 fail, since the binary isn't present on the compute nodes.
 103
 104 \paragraph{DARCS\_KEEP\_TMPDIR}
 105 \label{env:DARCS_KEEP_TMPDIR}
 106 If the environment variable DARCS\_KEEP\_TMPDIR is defined, darcs will
 107 not remove temprary directories.
 108
 109 This can be useful for darcs debugging.
 110
 111 \paragraph{HOME}
 112 \label{env:HOME}
 113 HOME is used to find the per-user prefs directory, which is located at
 114 \verb!$HOME/.darcs!.
 115
 116 %$ this dollar is a comment to make my emacs leave math mode... (stupid
 117 %  emacs)
 118
 119 \paragraph{TERM}
 120 \label{env:TERM}
 121 If darcs is compiled with libcurses support and support for color output,
 122 it uses the environment variable TERM to decide whether or not color is
 123 supported on the output terminal.
 124
 125 \section{Remote repositories}
 126
 127 \paragraph{SSH\_PORT}
 128 \label{env:SSH_PORT}
 129 When using ssh, if the SSH\_PORT environment variable is defined, darcs will
 130 use that port rather than the default ssh port (which is 22).
 131
 132 \paragraph{DARCS\_SSH}
 133 \label{env:DARCS_SSH}
 134 The DARCS\_SSH environment variable defines the command that darcs will use
 135 when asked to run ssh.  This command is \emph{not} interpreted by a shell,
 136 so you cannot use shell metacharacters, and the first word in the command
 137 must be the name of an executable located in your path.
 138
 139 \paragraph{DARCS\_SCP and DARCS\_SFTP}
 140 \label{env:DARCS_SCP}
 141 \label{env:DARCS_SFTP}
 142 The DARCS\_SCP and DARCS\_SFTP environment variables define the
 143 commands that darcs will use when asked to run scp or sftp.  Darcs uses
 144 scp and sftp to access repositories whose address is of the
 145 form \verb!user@foo.org:foo! or \verb!foo.org:foo!.  Darcs will use
 146 scp to copy single files (e.g.\ repository meta-information), and sftp
 147 to copy multiple files in batches (e.g.\ patches).  These commands are
 148 \emph{not} interpreted by a shell, so you cannot use shell
 149 metacharacters, and the first word in the command must be the name of
 150 an executable located in your path.  By default, \verb!scp! and \verb!sftp!
 151 are used.  When you can use sftp, but not scp (e.g.\ some ISP web sites), it
 152 works to set DARCS\_SCP to `sftp'.  The other way around does not work, i.e.\
 153 DARCS\_FTP must reference an sftp program, not scp.
 154
 155 \paragraph{DARCS\_PROXYUSERPWD}
 156 \label{env:DARCS_PROXYUSERPWD}
 157 This environment variable allows DARCS and libcurl to access remote repositories
 158 via a password-protected HTTP proxy. The proxy itself is specified with the standard
 159 environment variable for this purpose, namely 'http\_proxy'. The DARCS\_PROXYUSERPWD
 160 environment variable specifies the proxy username and password. It must be given in
 161 the form \emph{username:password}.
 162
 163 \paragraph{DARCS\_GET\_FOO, DARCS\_MGET\_FOO and DARCS\_APPLY\_FOO}
 164 \label{env:DARCS_X_FOO}
 165 When trying to access a repository with a URL beginning foo://,
 166 darcs will invoke the program specified by the DARCS\_GET\_FOO
 167 environment variable (if defined) to download each file, and the
 168 command specified by the DARCS\_APPLY\_FOO environment variable (if
 169 defined) when pushing to a foo:// URL.
 170
 171 This method overrides all other ways of getting \verb!foo://xxx! URLs.
 172
 173 Note that each command should be constructed so that it sends the downloaded
 174 content to STDOUT, and the next argument to it should be the URL\@.  Here are some
 175 examples that should work for DARCS\_GET\_HTTP:
 176
 177 \begin{verbatim}
 178 fetch -q -o -
 179 curl -s -f
 180 lynx -source
 181 wget -q -O -
 182 \end{verbatim}
 183
 184 If set, DARCS\_MGET\_FOO
 185 will be used to fetch many files from a single repository simultaneously.
 186 Replace FOO and foo as appropriate to handle other URL schemes.
 187 These commands are \emph{not} interpreted by a shell, so you cannot
 188 use shell metacharacters, and the first word in the command must
 189 be the name of an executable located in your path. The GET command
 190 will be called with a URL for each file.  The MGET command will be
 191 invoked with a number of URLs and is expected to download the files
 192 to the current directory, preserving the file name but not the path.
 193 The APPLY command will be called with a darcs patchfile piped into
 194 its standard input. Example:
 195
 196 \begin{verbatim}
 197 wget -q
 198 \end{verbatim}
 199
 200 \paragraph{DARCS\_MGETMAX}
 201 \label{env:DARCS_MGETMAX}
 202 When invoking a DARCS\_MGET\_FOO command, darcs will limit the
 203 number of URLs presented to the command to the value of this variable,
 204 if set, or 200.
 205
 206 \paragraph{DARCS\_WGET}
 207 \label{env:DARCS_WGET}
 208 This is a very old option that is only used if libcurl is not compiled
 209 in and one of the DARCS\_GET\_FOO is not used. Using one of those
 210 is recommended instead.
 211
 212 The DARCS\_WGET environment variable defines the command that darcs
 213 will use to fetch all URLs for remote repositories.  The first word in
 214 the command must be the name of an executable located in your path.
 215 Extra arguments can be included as well, such as:
 216
 217 \begin{verbatim}
 218 wget -q
 219 \end{verbatim}
 220
 221 Darcs will append \verb!-i! to the argument list, which it uses to provide a
 222 list of URLS to download. This allows wget to download multiple patches at the
 223 same time. It's possible to use another command besides \verb!wget! with this
 224 environment variable, but it must support the \verb!-i! option in the same way.
 225
 226 These commands are \emph{not} interpreted by a shell, so you cannot use shell
 227 meta-characters.
 228
 229
 230 \section{Highlighted output}
 231 \label{env:DARCS_ALWAYS_COLOR}
 232 \label{env:DARCS_DO_COLOR_LINES}
 233 \label{env:DARCS_DONT_ESCAPE_white}
 234
 235 If the terminal understands ANSI color escape sequences,
 236 darcs will highlight certain keywords and delimiters when printing patches.
 237 This can be turned off by setting the environment variable DARCS\_DONT\_COLOR to 1.
 238 If you use a pager that happens to understand ANSI colors, like \verb!less -R!,
 239 darcs can be forced always to highlight the output
 240 by setting DARCS\_ALWAYS\_COLOR to 1.
 241 If you can't see colors you can set DARCS\_ALTERNATIVE\_COLOR to 1,
 242 and darcs will use ANSI codes for bold and reverse video instead of colors.
 243 In addition, there is an extra-colorful mode, which is not enabled by
 244 default, which can be activated with DARCS\_DO\_COLOR\_LINES.
 245
 246 By default darcs will escape (by highlighting if possible) any kind of spaces at the end of lines
 247 when showing patch contents.
 248 If you don't want this you can turn it off by setting
 249 DARCS\_DONT\_ESCAPE\_TRAILING\_SPACES to 1.
 250 A special case exists for only carriage returns:
 251 DARCS\_DONT\_ESCAPE\_TRAILING\_CR.
 252
 253
 254 \section{Character escaping and non-ASCII character encodings}
 255 \label{env:DARCS_DONT_ESCAPE_nonascii}
 256
 257 Darcs needs to escape certain characters when printing patch contents to a terminal.
 258 Characters like \emph{backspace} can otherwise hide patch content from the user,
 259 and other character sequences can even in some cases redirect commands to the shell
 260 if the terminal allows it.
 261
 262 By default darcs will only allow printable 7-bit ASCII characters (including space),
 263 and the two control characters \emph{tab} and \emph{newline}.
 264 (See the last paragraph in this section for a way to tailor this behavior.)
 265 All other octets are printed in quoted form (as \verb!^<control letter>! or
 266 \verb!\!\verb!<hex code>!).
 267
 268 Darcs has some limited support for locales.
 269 If the system's locale is a single-byte character encoding,
 270 like the Latin encodings,
 271 you can set the environment variable DARCS\_DONT\_ESCAPE\_ISPRINT to 1
 272 and darcs will display all the printables in the current system locale
 273 instead of just the ASCII ones.
 274 NOTE: This curently does not work on some architectures if darcs is
 275 compiled with GHC~6.4. Some non-ASCII control characters might be printed
 276 and can possibly spoof the terminal.
 277
 278 For multi-byte character encodings things are less smooth.
 279 UTF-8 will work if you set DARCS\_DONT\_ESCAPE\_8BIT to 1,
 280 but non-printables outside the 7-bit ASCII range are no longer escaped.
 281 E.g., the extra control characters from Latin-1
 282 might leave your terminal at the mercy of the patch contents.
 283 Space characters outside the 7-bit ASCII range are no longer recognized
 284 and will not be properly escaped at line endings.
 285
 286 As a last resort you can set DARCS\_DONT\_ESCAPE\_ANYTHING to 1.
 287 Then everything that doesn't flip code sets should work,
 288 and so will all the bells and whistles in your terminal.
 289 This environment variable can also be handy
 290 if you pipe the output to a pager or external filter
 291 that knows better than darcs how to handle your encoding.
 292 Note that \emph{all} escaping,
 293 including the special escaping of any line ending spaces,
 294 will be turned off by this setting.
 295
 296 There are two environment variables you can set
 297 to explicitly tell darcs to not escape or escape octets.
 298 They are
 299 DARCS\_DONT\_ESCAPE\_EXTRA and DARCS\_ESCAPE\_EXTRA.
 300 Their values should be strings consisting of the verbatim octets in question.
 301 The do-escapes take precedence over the dont-escapes.
 302 Space characters are still escaped at line endings though.
 303 The special environment variable DARCS\_DONT\_ESCAPE\_TRAILING\_CR
 304 turns off escaping of carriage return last on the line (DOS style).