# HG changeset patch # User Greg Ward # Date 1318381803 14400 # Node ID 697289c5d41569ee9a4f5f18a8e8303a95eca97b # Parent 89e19ca2a90ee981f367f540d639518d63192575 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 -r 89e19ca2a90e -r 697289c5d415 hgext/largefiles/__init__.py --- a/hgext/largefiles/__init__.py Tue Oct 11 21:11:01 2011 -0400 +++ b/hgext/largefiles/__init__.py Tue Oct 11 21:10:03 2011 -0400 @@ -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 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. + +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. -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. +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 -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 +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 -r 89e19ca2a90e -r 697289c5d415 hgext/largefiles/lfcommands.py --- a/hgext/largefiles/lfcommands.py Tue Oct 11 21:11:01 2011 -0400 +++ b/hgext/largefiles/lfcommands.py Tue Oct 11 21:10:03 2011 -0400 @@ -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 @@ -464,10 +473,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 ...]')), }