Mercurial > hg
comparison hgext/lfs/__init__.py @ 35768:60a6ab7bcda7
lfs: expand the user facing documentation
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Fri, 19 Jan 2018 21:29:31 -0500 |
parents | 73432eee0ac4 |
children | f00edef84c3b |
comparison
equal
deleted
inserted
replaced
35767:5f5fb279fd39 | 35768:60a6ab7bcda7 |
---|---|
5 # This software may be used and distributed according to the terms of the | 5 # This software may be used and distributed according to the terms of the |
6 # GNU General Public License version 2 or any later version. | 6 # GNU General Public License version 2 or any later version. |
7 | 7 |
8 """lfs - large file support (EXPERIMENTAL) | 8 """lfs - large file support (EXPERIMENTAL) |
9 | 9 |
10 The extension reads its configuration from a versioned ``.hglfs`` | 10 This extension allows large files to be tracked outside of the normal |
11 configuration file found in the root of the working directory. The | 11 repository storage and stored on a centralized server, similar to the |
12 ``.hglfs`` file uses the same syntax as all other Mercurial | 12 ``largefiles`` extension. The ``git-lfs`` protocol is used when |
13 configuration files. It uses a single section, ``[track]``. | 13 communicating with the server, so existing git infrastructure can be |
14 | 14 harnessed. Even though the files are stored outside of the repository, |
15 The ``[track]`` section specifies which files are stored as LFS (or | 15 they are still integrity checked in the same manner as normal files. |
16 not). Each line is keyed by a file pattern, with a predicate value. | 16 |
17 The first file pattern match is used, so put more specific patterns | 17 The files stored outside of the repository are downloaded on demand, |
18 first. The available predicates are ``all()``, ``none()``, and | 18 which reduces the time to clone, and possibly the local disk usage. |
19 ``size()``. See "hg help filesets.size" for the latter. | 19 This changes fundamental workflows in a DVCS, so careful thought |
20 | 20 should be given before deploying it. :hg:`convert` can be used to |
21 Example versioned ``.hglfs`` file:: | 21 convert LFS repositories to normal repositories that no longer |
22 | 22 require this extension, and do so without changing the commit hashes. |
23 [track] | 23 This allows the extension to be disabled if the centralized workflow |
24 # No Makefile or python file, anywhere, will be LFS | 24 becomes burdensome. However, the pre and post convert clones will |
25 **Makefile = none() | 25 not be able to communicate with each other unless the extension is |
26 **.py = none() | 26 enabled on both. |
27 | 27 |
28 **.zip = all() | 28 To start a new repository, or add new LFS files, just create and add |
29 **.exe = size(">1MB") | 29 an ``.hglfs`` file as described below. Because the file is tracked in |
30 | 30 the repository, all clones will use the same selection policy. During |
31 # Catchall for everything not matched above | 31 subsequent commits, Mercurial will consult this file to determine if |
32 ** = size(">10MB") | 32 an added or modified file should be stored externally. The type of |
33 storage depends on the characteristics of the file at each commit. A | |
34 file that is near a size threshold may switch back and forth between | |
35 LFS and normal storage, as needed. | |
36 | |
37 Alternately, both normal repositories and largefile controlled | |
38 repositories can be converted to LFS by using :hg:`convert` and the | |
39 ``lfs.track`` config option described below. The ``.hglfs`` file | |
40 should then be created and added, to control subsequent LFS selection. | |
41 The hashes are also unchanged in this case. The LFS and non-LFS | |
42 repositories can be distinguished because the LFS repository will | |
43 abort any command if this extension is disabled. | |
44 | |
45 Committed LFS files are held locally, until the repository is pushed. | |
46 Prior to pushing the normal repository data, the LFS files that are | |
47 tracked by the outgoing commits are automatically uploaded to the | |
48 configured central server. No LFS files are transferred on | |
49 :hg:`pull` or :hg:`clone`. Instead, the files are downloaded on | |
50 demand as they need to be read, if a cached copy cannot be found | |
51 locally. Both committing and downloading an LFS file will link the | |
52 file to a usercache, to speed up future access. See the `usercache` | |
53 config setting described below. | |
54 | |
55 .hglfs:: | |
56 | |
57 The extension reads its configuration from a versioned ``.hglfs`` | |
58 configuration file found in the root of the working directory. The | |
59 ``.hglfs`` file uses the same syntax as all other Mercurial | |
60 configuration files. It uses a single section, ``[track]``. | |
61 | |
62 The ``[track]`` section specifies which files are stored as LFS (or | |
63 not). Each line is keyed by a file pattern, with a predicate value. | |
64 The first file pattern match is used, so put more specific patterns | |
65 first. The available predicates are ``all()``, ``none()``, and | |
66 ``size()``. See "hg help filesets.size" for the latter. | |
67 | |
68 Example versioned ``.hglfs`` file:: | |
69 | |
70 [track] | |
71 # No Makefile or python file, anywhere, will be LFS | |
72 **Makefile = none() | |
73 **.py = none() | |
74 | |
75 **.zip = all() | |
76 **.exe = size(">1MB") | |
77 | |
78 # Catchall for everything not matched above | |
79 ** = size(">10MB") | |
33 | 80 |
34 Configs:: | 81 Configs:: |
35 | 82 |
36 [lfs] | 83 [lfs] |
37 # Remote endpoint. Multiple protocols are supported: | 84 # Remote endpoint. Multiple protocols are supported: |
39 # git-lfs endpoint | 86 # git-lfs endpoint |
40 # - file:///tmp/path | 87 # - file:///tmp/path |
41 # local filesystem, usually for testing | 88 # local filesystem, usually for testing |
42 # if unset, lfs will prompt setting this when it must use this value. | 89 # if unset, lfs will prompt setting this when it must use this value. |
43 # (default: unset) | 90 # (default: unset) |
44 url = https://example.com/lfs | 91 url = https://example.com/repo.git/info/lfs |
45 | 92 |
46 # Which files to track in LFS. Path tests are "**.extname" for file | 93 # Which files to track in LFS. Path tests are "**.extname" for file |
47 # extensions, and "path:under/some/directory" for path prefix. Both | 94 # extensions, and "path:under/some/directory" for path prefix. Both |
48 # are relative to the repository root. | 95 # are relative to the repository root. |
49 # File size can be tested with the "size()" fileset, and tests can be | 96 # File size can be tested with the "size()" fileset, and tests can be |