--- a/hgext/lfs/__init__.py Thu Jan 18 00:50:12 2018 +0100
+++ b/hgext/lfs/__init__.py Fri Jan 19 21:29:31 2018 -0500
@@ -7,29 +7,76 @@
"""lfs - large file support (EXPERIMENTAL)
-The extension reads its configuration from a versioned ``.hglfs``
-configuration file found in the root of the working directory. The
-``.hglfs`` file uses the same syntax as all other Mercurial
-configuration files. It uses a single section, ``[track]``.
+This extension allows large files to be tracked outside of the normal
+repository storage and stored on a centralized server, similar to the
+``largefiles`` extension. The ``git-lfs`` protocol is used when
+communicating with the server, so existing git infrastructure can be
+harnessed. Even though the files are stored outside of the repository,
+they are still integrity checked in the same manner as normal files.
-The ``[track]`` section specifies which files are stored as LFS (or
-not). Each line is keyed by a file pattern, with a predicate value.
-The first file pattern match is used, so put more specific patterns
-first. The available predicates are ``all()``, ``none()``, and
-``size()``. See "hg help filesets.size" for the latter.
+The files stored outside of the repository are downloaded on demand,
+which reduces the time to clone, and possibly the local disk usage.
+This changes fundamental workflows in a DVCS, so careful thought
+should be given before deploying it. :hg:`convert` can be used to
+convert LFS repositories to normal repositories that no longer
+require this extension, and do so without changing the commit hashes.
+This allows the extension to be disabled if the centralized workflow
+becomes burdensome. However, the pre and post convert clones will
+not be able to communicate with each other unless the extension is
+enabled on both.
+
+To start a new repository, or add new LFS files, just create and add
+an ``.hglfs`` file as described below. Because the file is tracked in
+the repository, all clones will use the same selection policy. During
+subsequent commits, Mercurial will consult this file to determine if
+an added or modified file should be stored externally. The type of
+storage depends on the characteristics of the file at each commit. A
+file that is near a size threshold may switch back and forth between
+LFS and normal storage, as needed.
+
+Alternately, both normal repositories and largefile controlled
+repositories can be converted to LFS by using :hg:`convert` and the
+``lfs.track`` config option described below. The ``.hglfs`` file
+should then be created and added, to control subsequent LFS selection.
+The hashes are also unchanged in this case. The LFS and non-LFS
+repositories can be distinguished because the LFS repository will
+abort any command if this extension is disabled.
-Example versioned ``.hglfs`` file::
+Committed LFS files are held locally, until the repository is pushed.
+Prior to pushing the normal repository data, the LFS files that are
+tracked by the outgoing commits are automatically uploaded to the
+configured central server. No LFS files are transferred on
+:hg:`pull` or :hg:`clone`. Instead, the files are downloaded on
+demand as they need to be read, if a cached copy cannot be found
+locally. Both committing and downloading an LFS file will link the
+file to a usercache, to speed up future access. See the `usercache`
+config setting described below.
+
+.hglfs::
+
+ The extension reads its configuration from a versioned ``.hglfs``
+ configuration file found in the root of the working directory. The
+ ``.hglfs`` file uses the same syntax as all other Mercurial
+ configuration files. It uses a single section, ``[track]``.
- [track]
- # No Makefile or python file, anywhere, will be LFS
- **Makefile = none()
- **.py = none()
+ The ``[track]`` section specifies which files are stored as LFS (or
+ not). Each line is keyed by a file pattern, with a predicate value.
+ The first file pattern match is used, so put more specific patterns
+ first. The available predicates are ``all()``, ``none()``, and
+ ``size()``. See "hg help filesets.size" for the latter.
+
+ Example versioned ``.hglfs`` file::
- **.zip = all()
- **.exe = size(">1MB")
+ [track]
+ # No Makefile or python file, anywhere, will be LFS
+ **Makefile = none()
+ **.py = none()
- # Catchall for everything not matched above
- ** = size(">10MB")
+ **.zip = all()
+ **.exe = size(">1MB")
+
+ # Catchall for everything not matched above
+ ** = size(">10MB")
Configs::
@@ -41,7 +88,7 @@
# local filesystem, usually for testing
# if unset, lfs will prompt setting this when it must use this value.
# (default: unset)
- url = https://example.com/lfs
+ url = https://example.com/repo.git/info/lfs
# Which files to track in LFS. Path tests are "**.extname" for file
# extensions, and "path:under/some/directory" for path prefix. Both