##// END OF EJS Templates
upstream » mercurial-mirror
RSS

Clone from https://www.mercurial-scm.org/repo/hg-all

remotefilelog: rip out a missed mention of lz4...
Augie Fackler -
r40561:43318915 default
parent child Browse files
Show More
Show file before | Show file after | Hide comments
@@ -1,111 +1,109 b''
1 remotefilelog
1 remotefilelog
2 =============
2 =============
3
3
4 The remotefilelog extension allows Mercurial to clone shallow copies of a repository such that all file contents are left on the server and only downloaded on demand by the client. This greatly speeds up clone and pull performance for repositories that have long histories or that are growing quickly.
4 The remotefilelog extension allows Mercurial to clone shallow copies of a repository such that all file contents are left on the server and only downloaded on demand by the client. This greatly speeds up clone and pull performance for repositories that have long histories or that are growing quickly.
5
5
6 In addition, the extension allows using a caching layer (such as memcache) to serve the file contents, thus providing better scalability and reducing server load.
6 In addition, the extension allows using a caching layer (such as memcache) to serve the file contents, thus providing better scalability and reducing server load.
7
7
8 Installing
8 Installing
9 ==========
9 ==========
10
10
11 **NOTE:** See the limitations section below to check if remotefilelog will work for your use case.
11 **NOTE:** See the limitations section below to check if remotefilelog will work for your use case.
12
12
13 remotefilelog can be installed like any other Mercurial extension. Download the source code and add the remotefilelog subdirectory to your `hgrc`:
13 remotefilelog can be installed like any other Mercurial extension. Download the source code and add the remotefilelog subdirectory to your `hgrc`:
14
14
15 :::ini
15 :::ini
16 [extensions]
16 [extensions]
17 remotefilelog=path/to/remotefilelog/remotefilelog
17 remotefilelog=path/to/remotefilelog/remotefilelog
18
18
19 The extension currently has a hard dependency on lz4, so the [lz4 python library](https://pypi.python.org/pypi/lz4) must be installed on both servers and clients.
20
21 Configuring
19 Configuring
22 -----------
20 -----------
23
21
24 **Server**
22 **Server**
25
23
26 * `server` (required) - Set to 'True' to indicate that the server can serve shallow clones.
24 * `server` (required) - Set to 'True' to indicate that the server can serve shallow clones.
27 * `serverexpiration` - The server keeps a local cache of recently requested file revision blobs in .hg/remotefilelogcache. This setting specifies how many days they should be kept locally. Defaults to 30.
25 * `serverexpiration` - The server keeps a local cache of recently requested file revision blobs in .hg/remotefilelogcache. This setting specifies how many days they should be kept locally. Defaults to 30.
28
26
29 An example server configuration:
27 An example server configuration:
30
28
31 :::ini
29 :::ini
32 [remotefilelog]
30 [remotefilelog]
33 server = True
31 server = True
34 serverexpiration = 14
32 serverexpiration = 14
35
33
36 **Client**
34 **Client**
37
35
38 * `cachepath` (required) - the location to store locally cached file revisions
36 * `cachepath` (required) - the location to store locally cached file revisions
39 * `cachelimit` - the maximum size of the cachepath. By default it's 1000 GB.
37 * `cachelimit` - the maximum size of the cachepath. By default it's 1000 GB.
40 * `cachegroup` - the default unix group for the cachepath. Useful on shared systems so multiple users can read and write to the same cache.
38 * `cachegroup` - the default unix group for the cachepath. Useful on shared systems so multiple users can read and write to the same cache.
41 * `cacheprocess` - the external process that will handle the remote caching layer. If not set, all requests will go to the Mercurial server.
39 * `cacheprocess` - the external process that will handle the remote caching layer. If not set, all requests will go to the Mercurial server.
42 * `fallbackpath` - the Mercurial repo path to fetch file revisions from. By default it uses the paths.default repo. This setting is useful for cloning from shallow clones and still talking to the central server for file revisions.
40 * `fallbackpath` - the Mercurial repo path to fetch file revisions from. By default it uses the paths.default repo. This setting is useful for cloning from shallow clones and still talking to the central server for file revisions.
43 * `includepattern` - a list of regex patterns matching files that should be kept remotely. Defaults to all files.
41 * `includepattern` - a list of regex patterns matching files that should be kept remotely. Defaults to all files.
44 * `excludepattern` - a list of regex patterns matching files that should not be kept remotely and should always be downloaded.
42 * `excludepattern` - a list of regex patterns matching files that should not be kept remotely and should always be downloaded.
45 * `pullprefetch` - a revset of commits whose file content should be prefetched after every pull. The most common value for this will be '(bookmark() + head()) & public()'. This is useful in environments where offline work is common, since it will enable offline updating to, rebasing to, and committing on every head and bookmark.
43 * `pullprefetch` - a revset of commits whose file content should be prefetched after every pull. The most common value for this will be '(bookmark() + head()) & public()'. This is useful in environments where offline work is common, since it will enable offline updating to, rebasing to, and committing on every head and bookmark.
46
44
47 An example client configuration:
45 An example client configuration:
48
46
49 :::ini
47 :::ini
50 [remotefilelog]
48 [remotefilelog]
51 cachepath = /dev/shm/hgcache
49 cachepath = /dev/shm/hgcache
52 cachelimit = 2 GB
50 cachelimit = 2 GB
53
51
54 Using as a largefiles replacement
52 Using as a largefiles replacement
55 ---------------------------------
53 ---------------------------------
56
54
57 remotefilelog can theoretically be used as a replacement for the largefiles extension. You can use the `includepattern` setting to specify which directories or file types are considered large and they will be left on the server. Unlike the largefiles extension, this can be done without converting the server repository. Only the client configuration needs to specify the patterns.
55 remotefilelog can theoretically be used as a replacement for the largefiles extension. You can use the `includepattern` setting to specify which directories or file types are considered large and they will be left on the server. Unlike the largefiles extension, this can be done without converting the server repository. Only the client configuration needs to specify the patterns.
58
56
59 The include/exclude settings haven't been extensively tested, so this feature is still considered experimental.
57 The include/exclude settings haven't been extensively tested, so this feature is still considered experimental.
60
58
61 An example largefiles style client configuration:
59 An example largefiles style client configuration:
62
60
63 :::ini
61 :::ini
64 [remotefilelog]
62 [remotefilelog]
65 cachepath = /dev/shm/hgcache
63 cachepath = /dev/shm/hgcache
66 cachelimit = 2 GB
64 cachelimit = 2 GB
67 includepattern = *.sql3
65 includepattern = *.sql3
68 bin/*
66 bin/*
69
67
70 Usage
68 Usage
71 =====
69 =====
72
70
73 Once you have configured the server, you can get a shallow clone by doing:
71 Once you have configured the server, you can get a shallow clone by doing:
74
72
75 :::bash
73 :::bash
76 hg clone --shallow ssh://server//path/repo
74 hg clone --shallow ssh://server//path/repo
77
75
78 After that, all normal mercurial commands should work.
76 After that, all normal mercurial commands should work.
79
77
80 Occasionly the client or server caches may grow too big. Run `hg gc` to clean up the cache. It will remove cached files that appear to no longer be necessary, or any files that exceed the configured maximum size. This does not improve performance; it just frees up space.
78 Occasionly the client or server caches may grow too big. Run `hg gc` to clean up the cache. It will remove cached files that appear to no longer be necessary, or any files that exceed the configured maximum size. This does not improve performance; it just frees up space.
81
79
82 Limitations
80 Limitations
83 ===========
81 ===========
84
82
85 1. The extension must be used with Mercurial 3.3 (commit d7d08337b3f6) or higher (earlier versions of the extension work with earlier versions of Mercurial though, up to Mercurial 2.7).
83 1. The extension must be used with Mercurial 3.3 (commit d7d08337b3f6) or higher (earlier versions of the extension work with earlier versions of Mercurial though, up to Mercurial 2.7).
86
84
87 2. remotefilelog has only been tested on linux with case-sensitive filesystems. It should work on other unix systems but may have problems on case-insensitive filesystems.
85 2. remotefilelog has only been tested on linux with case-sensitive filesystems. It should work on other unix systems but may have problems on case-insensitive filesystems.
88
86
89 3. remotefilelog only works with ssh based Mercurial repos. http based repos are currently not supported, though it shouldn't be too difficult for some motivated individual to implement.
87 3. remotefilelog only works with ssh based Mercurial repos. http based repos are currently not supported, though it shouldn't be too difficult for some motivated individual to implement.
90
88
91 4. Tags are not supported in completely shallow repos. If you use tags in your repo you will have to specify `excludepattern=.hgtags` in your client configuration to ensure that file is downloaded. The include/excludepattern settings are experimental at the moment and have yet to be deployed in a production environment.
89 4. Tags are not supported in completely shallow repos. If you use tags in your repo you will have to specify `excludepattern=.hgtags` in your client configuration to ensure that file is downloaded. The include/excludepattern settings are experimental at the moment and have yet to be deployed in a production environment.
92
90
93 5. A few commands will be slower. `hg log <filename>` will be much slower since it has to walk the entire commit history instead of just the filelog. Use `hg log -f <filename>` instead, which remains very fast.
91 5. A few commands will be slower. `hg log <filename>` will be much slower since it has to walk the entire commit history instead of just the filelog. Use `hg log -f <filename>` instead, which remains very fast.
94
92
95 Contributing
93 Contributing
96 ============
94 ============
97
95
98 Patches are welcome as pull requests, though they will be collapsed and rebased to maintain a linear history. Tests can be run via:
96 Patches are welcome as pull requests, though they will be collapsed and rebased to maintain a linear history. Tests can be run via:
99
97
100 :::bash
98 :::bash
101 cd tests
99 cd tests
102 ./run-tests --with-hg=path/to/hgrepo/hg
100 ./run-tests --with-hg=path/to/hgrepo/hg
103
101
104 We (Facebook) have to ask for a "Contributor License Agreement" from someone who sends in a patch or code that we want to include in the codebase. This is a legal requirement; a similar situation applies to Apache and other ASF projects.
102 We (Facebook) have to ask for a "Contributor License Agreement" from someone who sends in a patch or code that we want to include in the codebase. This is a legal requirement; a similar situation applies to Apache and other ASF projects.
105
103
106 If we ask you to fill out a CLA we'll direct you to our [online CLA page](https://developers.facebook.com/opensource/cla) where you can complete it easily. We use the same form as the Apache CLA so that friction is minimal.
104 If we ask you to fill out a CLA we'll direct you to our [online CLA page](https://developers.facebook.com/opensource/cla) where you can complete it easily. We use the same form as the Apache CLA so that friction is minimal.
107
105
108 License
106 License
109 =======
107 =======
110
108
111 remotefilelog is made available under the terms of the GNU General Public License version 2, or any later version. See the COPYING file that accompanies this distribution for the full text of the license.
109 remotefilelog is made available under the terms of the GNU General Public License version 2, or any later version. See the COPYING file that accompanies this distribution for the full text of the license.
General Comments 0
You need to be logged in to leave comments. Login now