[PATCH 4 of 4] largefiles: improve help

[Greg Ward]

# HG changeset patch
# User Greg Ward <greg at gerg.ca>
# Date 1318381803 14400
# Node ID ce4f688f6a1ec3a3f0f81c7dda9219d25cb3641d
# Parent  3a14a9ab169a9a9a677a1da17e50a0420c1df307
largefiles: improve help

Extension help taken from the URL formerly in the text
(https://developers.kilnhg.com/Repo/Kiln/largefiles/largefiles/File/usage.txt)
and improved.

diff --git a/hgext/largefiles/__init__.py b/hgext/largefiles/__init__.py
--- a/hgext/largefiles/__init__.py
+++ b/hgext/largefiles/__init__.py
@@ -8,22 +8,76 @@
 
 '''track large binary files
 
-Large binary files tend to be not very compressible, not very "diffable", and
-not at all mergeable.  Such files are not handled well by Mercurial\'s storage
-format (revlog), which is based on compressed binary deltas.  largefiles solves
-this problem by adding a centralized client-server layer on top of Mercurial:
-largefiles live in a *central store* out on the network somewhere, and you only
-fetch the ones that you need when you need them.
+Large binary files tend to be not very compressible, not very
+diffable, and not at all mergeable. Such files are not handled
+efficiently by Mercurial's storage format (revlog), which is based on
+compressed binary deltas; storing large binary files as regular
+Mercurial files wastes bandwidth and disk space and increases
+Mercurial's memory usage. The largefiles extension addresses these
+problems by adding a centralized client-server layer on top of
+Mercurial: largefiles live in a *central store* out on the network
+somewhere, and you only fetch the revisions that you need when you
+need them.
 
-largefiles works by maintaining a *standin* in .hglf/ for each largefile.  The
-standins are small (41 bytes: an SHA-1 hash plus newline) and are tracked by
-Mercurial.  Largefile revisions are identified by the SHA-1 hash of their
-contents, which is written to the standin.  largefiles uses that revision ID to
-get/put largefile revisions from/to the central store.
+largefiles works by maintaining a "standin file" in .hglf/ for each
+largefile. The standins are small (41 bytes: an SHA-1 hash plus
+newline) and are tracked by Mercurial. Largefile revisions are
+identified by the SHA-1 hash of their contents, which is written to
+the standin. largefiles uses that revision ID to get/put largefile
+revisions from/to the central store. This saves both disk space and
+bandwidth, since you don't need to retrieve all historical revisions
+of large files when you clone or pull.
 
-A complete tutorial for using lfiles is included in ``usage.txt`` in the lfiles
-source distribution.  See
-https://developers.kilnhg.com/Repo/Kiln/largefiles/largefiles/File/usage.txt
+To start a new repository or add new large binary files, just add
+--large to your ``hg add`` command. For example::
+
+  $ dd if=/dev/urandom of=randomdata count=2000
+  $ hg add --large randomdata
+  $ hg commit -m 'add randomdata as a largefile'
+
+When you push a changeset that adds/modifies largefiles to a remote
+repository, its largefile revisions will be uploaded along with it.
+Note that the remote Mercurial must also have the largefiles extension
+enabled for this to work.
+
+When you pull a changeset that affects largefiles from a remote
+repository, Mercurial behaves as normal. However, when you update to
+such a revision, any largefiles needed by that revision are downloaded
+and cached (if they have never been downloaded before). This means
+that network access may be required to update to changesets you have
+not previously updated to.
+
+If you already have large files tracked by Mercurial without the
+largefiles extension, you will need to convert your repository in
+order to benefit from largefiles. This is done with the 'hg lfconvert'
+command::
+
+  $ hg lfconvert --size 10 oldrepo newrepo
+
+In repositories that already have largefiles in them, any new file
+over 10MB will automatically be added as a largefile. To change this
+threshhold, set ``largefiles.size`` in your Mercurial config file to
+the minimum size in megabytes to track as a largefile, or use the
+--lfsize option to the add command (also in megabytes)::
+
+  [largefiles]
+  size = 2           XXX wouldn't minsize be a better name?
+
+  $ hg add --lfsize 2
+
+The ``largefiles.patterns`` config option allows you to specify a list
+of filename patterns (see ``hg help patterns``) that should always be
+tracked as largefiles::
+
+  [largefiles]
+  patterns = 
+    *.jpg 
+    re:.*\.(png|bmp)$ 
+    library.zip
+    content/audio/*
+
+Files that match one of these patterns will be added as largefiles
+regardless of their size.
 '''
 
 from mercurial import commands
diff --git a/hgext/largefiles/lfcommands.py b/hgext/largefiles/lfcommands.py
--- a/hgext/largefiles/lfcommands.py
+++ b/hgext/largefiles/lfcommands.py
@@ -20,14 +20,23 @@
 # -- Commands ----------------------------------------------------------
 
 def lfconvert(ui, src, dest, *pats, **opts):
-    '''Convert a normal repository to a largefiles repository
+    '''convert a normal repository to a largefiles repository
 
-    Convert source repository creating an identical repository, except that all
-    files that match the patterns given, or are over the given size will be
-    added as largefiles. The size used to determine whether or not to track a
-    file as a largefile is the size of the first version of the file. After
-    running this command you will need to make sure that largefiles is enabled
-    anywhere you intend to push the new repository.'''
+    Convert repository SOURCE to a new repository DEST, identical to
+    SOURCE except that certain files will be converted as largefiles:
+    specifically, any file that matches any PATTERN *or* whose size is
+    above the minimum size threshold is converted as a largefile. The
+    size used to determine whether or not to track a file as a
+    largefile is the size of the first version of the file. The
+    minimum size can be specified either with --size or in
+    configuration as ``largefiles.size``.
+
+    After running this command you will need to make sure that
+    largefiles is enabled anywhere you intend to push the new
+    repository.
+
+    Use --tonormal to convert largefiles back to normal files; after
+    this, the DEST repository can be used without largefiles at all.'''
 
     if opts['tonormal']:
         tolfile = False
@@ -469,10 +478,12 @@
 
 cmdtable = {
     'lfconvert': (lfconvert,
-                  [('s', 'size', '', 'All files over this size (in megabytes) '
-                  'will be considered largefiles. This can also be specified '
-                  'in your hgrc as [largefiles].size.'),
-                  ('','tonormal',False,
-                      'Convert from a largefiles repo to a normal repo')],
+                  [('s', 'size', '', 
+                    _('minimum size (MB) for files to be converted '
+                      'as largefiles'),
+                    'SIZE'),
+                  ('', 'tonormal', False,
+                   _('convert from a largefiles repo to a normal repo')),
+                  ],
                   _('hg lfconvert SOURCE DEST [FILE ...]')),
     }