Mercurial > hg
annotate hgext/largefiles/__init__.py @ 18704:d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
After discussion, we've agreed that largefiles for newly pulled heads should
not be cached by default. The use case for this is using largefiles repos
with multiple remote servers (and therefore multiple remote largefiles caches),
where users will be pulling from non-default locations on a regular basis. We
think this use case will be significantly less common than the use case where
all largefiles are stored on the same central server, so the default should be
no caching.
The old behavior can be obtained by passing the --cache-largefiles flag to
pull.
author | Na'Tosha Bard <natosha@unity3d.com> |
---|---|
date | Sat, 09 Feb 2013 21:07:42 +0000 |
parents | 5cd1dbf4c5d2 |
children | aa8205a9f51a |
rev | line source |
---|---|
15168 | 1 # Copyright 2009-2010 Gregory P. Ward |
2 # Copyright 2009-2010 Intelerad Medical Systems Incorporated | |
3 # Copyright 2010-2011 Fog Creek Software | |
4 # Copyright 2010-2011 Unity Technologies | |
5 # | |
6 # This software may be used and distributed according to the terms of the | |
7 # GNU General Public License version 2 or any later version. | |
8 | |
9 '''track large binary files | |
10 | |
15230 | 11 Large binary files tend to be not very compressible, not very |
12 diffable, and not at all mergeable. Such files are not handled | |
13 efficiently by Mercurial's storage format (revlog), which is based on | |
14 compressed binary deltas; storing large binary files as regular | |
15 Mercurial files wastes bandwidth and disk space and increases | |
16 Mercurial's memory usage. The largefiles extension addresses these | |
17 problems by adding a centralized client-server layer on top of | |
18 Mercurial: largefiles live in a *central store* out on the network | |
19 somewhere, and you only fetch the revisions that you need when you | |
20 need them. | |
21 | |
22 largefiles works by maintaining a "standin file" in .hglf/ for each | |
23 largefile. The standins are small (41 bytes: an SHA-1 hash plus | |
24 newline) and are tracked by Mercurial. Largefile revisions are | |
25 identified by the SHA-1 hash of their contents, which is written to | |
26 the standin. largefiles uses that revision ID to get/put largefile | |
27 revisions from/to the central store. This saves both disk space and | |
28 bandwidth, since you don't need to retrieve all historical revisions | |
29 of large files when you clone or pull. | |
30 | |
31 To start a new repository or add new large binary files, just add | |
15352
b74f74b482d8
largefiles: improve markup in module help text
Martin Geisler <mg@aragost.com>
parents:
15304
diff
changeset
|
32 --large to your :hg:`add` command. For example:: |
15230 | 33 |
34 $ dd if=/dev/urandom of=randomdata count=2000 | |
35 $ hg add --large randomdata | |
36 $ hg commit -m 'add randomdata as a largefile' | |
37 | |
38 When you push a changeset that adds/modifies largefiles to a remote | |
39 repository, its largefile revisions will be uploaded along with it. | |
40 Note that the remote Mercurial must also have the largefiles extension | |
41 enabled for this to work. | |
15168 | 42 |
15230 | 43 When you pull a changeset that affects largefiles from a remote |
18704
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
44 repository, the largefiles for the changeset won't be pulled down. |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
45 Instead, when you later update to such a revision, any largefiles |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
46 needed by that revision are downloaded and cached (if they have |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
47 never been downloaded before). This means that network access may |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
48 be required to update to changesets you have previously updated to. |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
49 |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
50 If you know you are pulling from a non-default location and want to |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
51 ensure that you will have the largefiles needed to merge or rebase |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
52 with new heads that you are pulling, then you can pull with the |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
53 --cache-largefiles flag to pre-emptively download any largefiles |
d69585a5c5c0
largefiles: don't cache largefiles for pulled heads by default
Na'Tosha Bard <natosha@unity3d.com>
parents:
18599
diff
changeset
|
54 that are new in the heads you are pulling. |
18599
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
55 |
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
56 The one exception to the "largefiles won't be pulled until you update |
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
57 to a revision that changes them" rule is when you pull new heads. |
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
58 Because you could be pulling new heads (that you may later want to |
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
59 merge with) from a non-default location (that Mercurial won't know |
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
60 about later), when you pull new heads, largefiles revisions for those |
5cd1dbf4c5d2
largefiles: document behavior of caching largefiles for new heads
Na'Tosha Bard <natosha@unity3d.com>
parents:
17233
diff
changeset
|
61 heads are downloaded and cached locally. |
15230 | 62 |
63 If you already have large files tracked by Mercurial without the | |
64 largefiles extension, you will need to convert your repository in | |
15352
b74f74b482d8
largefiles: improve markup in module help text
Martin Geisler <mg@aragost.com>
parents:
15304
diff
changeset
|
65 order to benefit from largefiles. This is done with the |
b74f74b482d8
largefiles: improve markup in module help text
Martin Geisler <mg@aragost.com>
parents:
15304
diff
changeset
|
66 :hg:`lfconvert` command:: |
15230 | 67 |
68 $ hg lfconvert --size 10 oldrepo newrepo | |
15168 | 69 |
15230 | 70 In repositories that already have largefiles in them, any new file |
71 over 10MB will automatically be added as a largefile. To change this | |
15304
9aa9d4bb3d88
largefiles: rename config setting 'size' to 'minsize'
Greg Ward <greg@gerg.ca>
parents:
15291
diff
changeset
|
72 threshold, set ``largefiles.minsize`` in your Mercurial config file |
9aa9d4bb3d88
largefiles: rename config setting 'size' to 'minsize'
Greg Ward <greg@gerg.ca>
parents:
15291
diff
changeset
|
73 to the minimum size in megabytes to track as a largefile, or use the |
15230 | 74 --lfsize option to the add command (also in megabytes):: |
75 | |
76 [largefiles] | |
15304
9aa9d4bb3d88
largefiles: rename config setting 'size' to 'minsize'
Greg Ward <greg@gerg.ca>
parents:
15291
diff
changeset
|
77 minsize = 2 |
15230 | 78 |
79 $ hg add --lfsize 2 | |
80 | |
81 The ``largefiles.patterns`` config option allows you to specify a list | |
15352
b74f74b482d8
largefiles: improve markup in module help text
Martin Geisler <mg@aragost.com>
parents:
15304
diff
changeset
|
82 of filename patterns (see :hg:`help patterns`) that should always be |
15230 | 83 tracked as largefiles:: |
84 | |
85 [largefiles] | |
86 patterns = | |
87 *.jpg | |
88 re:.*\.(png|bmp)$ | |
89 library.zip | |
90 content/audio/* | |
91 | |
92 Files that match one of these patterns will be added as largefiles | |
93 regardless of their size. | |
15743
6266b1b970a5
largefiles: clarify help when options are ignored until first add is done
Michal Sznajder <michalsznajder@gmail.com>
parents:
15352
diff
changeset
|
94 |
6266b1b970a5
largefiles: clarify help when options are ignored until first add is done
Michal Sznajder <michalsznajder@gmail.com>
parents:
15352
diff
changeset
|
95 The ``largefiles.minsize`` and ``largefiles.patterns`` config options |
6266b1b970a5
largefiles: clarify help when options are ignored until first add is done
Michal Sznajder <michalsznajder@gmail.com>
parents:
15352
diff
changeset
|
96 will be ignored for any repositories not already containing a |
6266b1b970a5
largefiles: clarify help when options are ignored until first add is done
Michal Sznajder <michalsznajder@gmail.com>
parents:
15352
diff
changeset
|
97 largefile. To add the first largefile to a repository, you must |
6266b1b970a5
largefiles: clarify help when options are ignored until first add is done
Michal Sznajder <michalsznajder@gmail.com>
parents:
15352
diff
changeset
|
98 explicitly do so with the --large flag passed to the :hg:`add` |
6266b1b970a5
largefiles: clarify help when options are ignored until first add is done
Michal Sznajder <michalsznajder@gmail.com>
parents:
15352
diff
changeset
|
99 command. |
15168 | 100 ''' |
101 | |
102 from mercurial import commands | |
103 | |
104 import lfcommands | |
105 import reposetup | |
106 import uisetup | |
107 | |
17233
acea82757d8a
largefiles: mark as a first party extension
Matt Harbison <matt_harbison@yahoo.com>
parents:
15743
diff
changeset
|
108 testedwith = 'internal' |
acea82757d8a
largefiles: mark as a first party extension
Matt Harbison <matt_harbison@yahoo.com>
parents:
15743
diff
changeset
|
109 |
15168 | 110 reposetup = reposetup.reposetup |
111 uisetup = uisetup.uisetup | |
112 | |
113 commands.norepo += " lfconvert" | |
114 | |
115 cmdtable = lfcommands.cmdtable |