Mercurial > hg
annotate hgext/remotefilelog/README.md @ 42725:7492899c6fc6
rawdata: implement the method for `remotefilelog` too
This is needed for all storage implementations.
author | Pierre-Yves David <pierre-yves.david@octobus.net> |
---|---|
date | Wed, 07 Aug 2019 20:51:52 +0200 |
parents | 433189151d5d |
children | 28f0092ec89f |
rev | line source |
---|---|
40495
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
1 remotefilelog |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
2 ============= |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
3 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
5 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
7 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
8 Installing |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
9 ========== |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
10 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
11 **NOTE:** See the limitations section below to check if remotefilelog will work for your use case. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
12 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
13 remotefilelog can be installed like any other Mercurial extension. Download the source code and add the remotefilelog subdirectory to your `hgrc`: |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
14 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
15 :::ini |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
16 [extensions] |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
17 remotefilelog=path/to/remotefilelog/remotefilelog |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
18 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
19 Configuring |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
20 ----------- |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
21 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
22 **Server** |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
23 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
24 * `server` (required) - Set to 'True' to indicate that the server can serve shallow clones. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
26 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
27 An example server configuration: |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
28 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
29 :::ini |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
30 [remotefilelog] |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
31 server = True |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
32 serverexpiration = 14 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
33 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
34 **Client** |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
35 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
36 * `cachepath` (required) - the location to store locally cached file revisions |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
37 * `cachelimit` - the maximum size of the cachepath. By default it's 1000 GB. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
38 * `cachegroup` - the default unix group for the cachepath. Useful on shared systems so multiple users can read and write to the same cache. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
39 * `cacheprocess` - the external process that will handle the remote caching layer. If not set, all requests will go to the Mercurial server. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
41 * `includepattern` - a list of regex patterns matching files that should be kept remotely. Defaults to all files. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
42 * `excludepattern` - a list of regex patterns matching files that should not be kept remotely and should always be downloaded. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
44 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
45 An example client configuration: |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
46 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
47 :::ini |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
48 [remotefilelog] |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
49 cachepath = /dev/shm/hgcache |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
50 cachelimit = 2 GB |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
51 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
52 Using as a largefiles replacement |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
53 --------------------------------- |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
54 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
56 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
57 The include/exclude settings haven't been extensively tested, so this feature is still considered experimental. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
58 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
59 An example largefiles style client configuration: |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
60 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
61 :::ini |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
62 [remotefilelog] |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
63 cachepath = /dev/shm/hgcache |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
64 cachelimit = 2 GB |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
65 includepattern = *.sql3 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
66 bin/* |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
67 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
68 Usage |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
69 ===== |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
70 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
71 Once you have configured the server, you can get a shallow clone by doing: |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
72 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
73 :::bash |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
74 hg clone --shallow ssh://server//path/repo |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
75 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
76 After that, all normal mercurial commands should work. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
77 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
79 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
80 Limitations |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
81 =========== |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
82 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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). |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
84 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
86 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
88 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
90 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
92 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
93 Contributing |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
94 ============ |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
95 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
96 Patches are welcome as pull requests, though they will be collapsed and rebased to maintain a linear history. Tests can be run via: |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
97 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
98 :::bash |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
99 cd tests |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
100 ./run-tests --with-hg=path/to/hgrepo/hg |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
101 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
103 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
105 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
106 License |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
107 ======= |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
108 |
3a333a582d7b
remotefilelog: import pruned-down remotefilelog extension from hg-experimental
Augie Fackler <augie@google.com>
parents:
diff
changeset
|
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. |