OLD | NEW |
| (Empty) |
1 --- | |
2 title: "Command: Get" | |
3 --- | |
4 | |
5 $ pub get [--offline] | |
6 | |
7 This command gets all the dependencies listed in the | |
8 [`pubspec.yaml`](pubspec.html) file in the current working directory, as well as | |
9 their [transitive dependencies](glossary.html#transitive-dependency), and places | |
10 them in a `packages` directory located next to the pubspec. For example: | |
11 | |
12 $ pub get | |
13 Got dependencies! | |
14 | |
15 Once the dependencies are acquired, they may be referenced in Dart code. For | |
16 example, if a package depends on `unittest`: | |
17 | |
18 {% highlight dart %} | |
19 import "package:unittest/unittest.dart; | |
20 {% endhighlight %} | |
21 | |
22 When `pub get` gets new dependencies, it writes a | |
23 [lockfile](glossary.html#lockfile) to ensure that future gets will use the | |
24 same versions of those dependencies. Application packages should check in the | |
25 lockfile to source control; this ensures the application will use the exact same | |
26 versions of all dependencies for all developers and when deployed to production. | |
27 Library packages should not check in the lockfile, though, since they're | |
28 expected to work with a range of dependency versions. | |
29 | |
30 If a lockfile already exists, `pub get` uses the versions of dependencies | |
31 locked in it if possible. If a dependency isn't locked, pub will get the | |
32 latest version of that dependency that satisfies all the [version | |
33 constraints](glossary.html#version-constraint). This is the primary difference | |
34 between `pub get` and [`pub upgrade`](pub-upgrade.html), which always tries to | |
35 get the latest versions of all dependencies. | |
36 | |
37 ## Getting a new dependency | |
38 | |
39 If a dependency is added to the pubspec and then `pub get` is run, it will | |
40 get the new dependency and any of its transitive dependencies and place them in | |
41 the `packages` directory. However, it won't change the versions of any | |
42 already-acquired dependencies unless that's necessary to get the new | |
43 dependency. | |
44 | |
45 ## Removing a dependency | |
46 | |
47 If a dependency is removed from the pubspec and then `pub get` is run, it will | |
48 remove the dependency from the `packages` directory, thus making it | |
49 unavailable for importing. Any transitive dependencies of the removed dependency | |
50 will also be removed, as long as no remaining immediate dependencies also depend | |
51 on them. Removing a dependency will never change the versions of any | |
52 already-acquired dependencies. | |
53 | |
54 ## Linked `packages` directories | |
55 | |
56 Every [entrypoint](glossary.html#entrypoint) in a package needs to be next to a | |
57 `packages` directory in order for it to import packages acquired by Pub. | |
58 However, it's not convenient to put every entrypoint at the top level of the | |
59 package alongside the main `packages` directory. You may have example scripts or | |
60 tests that you want to be able to run from subdirectories. | |
61 | |
62 `pub get` solves this issue by creating additional `packages` directories | |
63 that link to the main `packages` directory at the root of your package. It | |
64 assumes your package is laid out according to the [package layout | |
65 guide](package-layout.html), and creates a linked `packages` directory in | |
66 `bin/`, `test/`, and `example/`, as well as their subdirectories. | |
67 | |
68 ## The system package cache | |
69 | |
70 Dependencies are not physically stored in the `packages` directory that pub | |
71 creates. Dependencies downloaded over the internet, such as those from Git and | |
72 [pub.dartlang.org](http://pub.dartlang.org), are stored in a system-wide cache | |
73 and linked to from the `packages` directory. This means that if multiple | |
74 packages use the same version of the same dependency, it will only need to be | |
75 downloaded and stored locally once. It also means that it's safe to delete the | |
76 `packages` directory without worrying about re-downloading packages. | |
77 | |
78 By default, the system package cache is located in the `.pub-cache` subdirectory | |
79 of your home directory. However, it may be configured by setting the `PUB_CACHE` | |
80 environment variable before running Pub. | |
81 | |
82 ## Getting while offline | |
83 | |
84 If you don't have network access, you can still run `pub get`. Since pub | |
85 downloads packages to a central cache shared by all packages on your system, it | |
86 can often find previous-downloaded packages there without needing to hit the | |
87 network. | |
88 | |
89 However, by default, pub will always try to go online when you get if you | |
90 have any hosted dependencies so that it can see if newer versions of them are | |
91 available. If you don't want it to do that, pass the `--offline` flag when | |
92 running pub. In this mode, it will only look in your local package cache and | |
93 try to find a set of versions that work with your package from what's already | |
94 available. | |
95 | |
96 Keep in mind that pub *will* generate a lockfile after it does this. If the | |
97 only version of some dependency in your cache happens to be old, this will lock | |
98 your app to that version. The next time you are online, you will likely want to | |
99 run [`pub upgrade`](pub-upgrade.html) to upgrade to a later version. | |
OLD | NEW |