Improve the `pub outdated --help` text (#2429)
Co-Authored-By: Kathy Walrath <kathyw@google.com>
diff --git a/lib/src/command/outdated.dart b/lib/src/command/outdated.dart
index 99ba8f1..4109860 100644
--- a/lib/src/command/outdated.dart
+++ b/lib/src/command/outdated.dart
@@ -32,39 +32,43 @@
OutdatedCommand() {
argParser.addFlag('color',
- help: 'Whether to color the output. Defaults to color '
- 'when connected to a terminal, and no-color otherwise.');
-
- argParser.addFlag('json',
- help: 'Outputs the results in a json formatted report',
- negatable: false);
-
- argParser.addFlag('up-to-date',
- defaultsTo: false,
- help: 'Include dependencies that are already at the latest version.');
-
- argParser.addFlag('pre-releases',
- defaultsTo: false,
- help: 'Include pre-releases when reporting latest version.');
-
- argParser.addFlag(
- 'dev-dependencies',
- defaultsTo: true,
- help: 'When true take dev-dependencies into account when resolving.',
- );
+ help: 'Whether to color the output.\n'
+ 'Defaults to color when connected to a\n'
+ 'terminal, and no-color otherwise.');
argParser.addFlag(
'dependency-overrides',
defaultsTo: true,
- help: 'Show resolutions with `dependency_override`',
+ help: 'Show resolutions with `dependency_overrides`.',
);
+ argParser.addFlag(
+ 'dev-dependencies',
+ defaultsTo: true,
+ help: 'Take dev dependencies into account.',
+ );
+
+ argParser.addFlag('json',
+ help: 'Output the results using a json format.', negatable: false);
+
argParser.addOption('mark',
help: 'Highlight packages with some property in the report.',
valueHelp: 'OPTION',
allowed: ['outdated', 'none'],
defaultsTo: 'outdated',
hide: true);
+
+ argParser.addFlag('prereleases',
+ defaultsTo: false, help: 'Include prereleases in latest version.');
+
+ // Preserve for backwards compatibility.
+ argParser.addFlag('pre-releases',
+ defaultsTo: false, help: 'Alias of prereleases.', hide: true);
+
+ argParser.addFlag('up-to-date',
+ defaultsTo: false,
+ help: 'Include dependencies that are already at the\n'
+ 'latest version.');
}
@override
@@ -222,7 +226,10 @@
if (available.isEmpty) {
return null;
}
- available.sort(argResults['pre-releases']
+ final prereleases = argResults.wasParsed('prereleases')
+ ? argResults['prereleases']
+ : argResults['pre-releases'];
+ available.sort(prereleases
? (x, y) => x.version.compareTo(y.version)
: (x, y) => Version.prioritize(x.version, y.version));
return available.last;
diff --git a/test/outdated/goldens/circular_dependencies.txt b/test/outdated/goldens/circular_dependencies.txt
index 3e4bd80..038fae9 100644
--- a/test/outdated/goldens/circular_dependencies.txt
+++ b/test/outdated/goldens/circular_dependencies.txt
@@ -58,7 +58,7 @@
1 upgradable dependency is locked (in pubspec.lock) to an older version.
To update it, use `pub upgrade`.
-$ pub outdated --no-color --pre-releases
+$ pub outdated --no-color --prereleases
Dependencies Current Upgradable Resolvable Latest
foo *1.2.3 1.3.0 1.3.0 1.3.0
diff --git a/test/outdated/goldens/dependency_overrides.txt b/test/outdated/goldens/dependency_overrides.txt
index 95e1a57..6ead691 100644
--- a/test/outdated/goldens/dependency_overrides.txt
+++ b/test/outdated/goldens/dependency_overrides.txt
@@ -103,7 +103,7 @@
Dependencies are all on the latest resolvable versions.
Newer versions, while available, are not mutually compatible.
-$ pub outdated --no-color --pre-releases
+$ pub outdated --no-color --prereleases
Dependencies Current Upgradable Resolvable Latest
bar *1.0.1 (overridden) *1.0.1 (overridden) *1.0.1 (overridden) 2.0.0
baz *2.0.0 (overridden) *2.0.0 (overridden) *2.0.0 (overridden) 2.0.0
diff --git a/test/outdated/goldens/dependency_overrides_no_solution.txt b/test/outdated/goldens/dependency_overrides_no_solution.txt
index dbf27fb..0a2d267 100644
--- a/test/outdated/goldens/dependency_overrides_no_solution.txt
+++ b/test/outdated/goldens/dependency_overrides_no_solution.txt
@@ -82,7 +82,7 @@
Dependencies are all on the latest resolvable versions.
Newer versions, while available, are not mutually compatible.
-$ pub outdated --no-color --pre-releases
+$ pub outdated --no-color --prereleases
Dependencies Current Upgradable Resolvable Latest
bar *1.0.0 (overridden) *1.0.0 (overridden) *1.0.0 (overridden) 2.0.0
foo *1.0.0 (overridden) *1.0.0 (overridden) *1.0.0 (overridden) 2.0.0
diff --git a/test/outdated/goldens/helptext.txt b/test/outdated/goldens/helptext.txt
new file mode 100644
index 0000000..70e286a
--- /dev/null
+++ b/test/outdated/goldens/helptext.txt
@@ -0,0 +1,20 @@
+$ pub outdated --help
+Analyze your dependencies to find which ones can be upgraded.
+
+Usage: pub outdated [options]
+-h, --help Print this usage information.
+ --[no-]color Whether to color the output.
+ Defaults to color when connected to a
+ terminal, and no-color otherwise.
+ --[no-]dependency-overrides Show resolutions with `dependency_overrides`.
+ (defaults to on)
+ --[no-]dev-dependencies Take dev dependencies into account.
+ (defaults to on)
+ --json Output the results using a json format.
+ --[no-]prereleases Include prereleases in latest version.
+ --[no-]up-to-date Include dependencies that are already at the
+ latest version.
+
+Run "pub help" to see global options.
+See https://dart.dev/tools/pub/cmd/pub-outdated for detailed documentation.
+
diff --git a/test/outdated/goldens/mutually_incompatible.txt b/test/outdated/goldens/mutually_incompatible.txt
index f2b8a82..9f279c1 100644
--- a/test/outdated/goldens/mutually_incompatible.txt
+++ b/test/outdated/goldens/mutually_incompatible.txt
@@ -76,7 +76,7 @@
Dependencies are all on the latest resolvable versions.
Newer versions, while available, are not mutually compatible.
-$ pub outdated --no-color --pre-releases
+$ pub outdated --no-color --prereleases
Dependencies Current Upgradable Resolvable Latest
bar *1.0.0 *1.0.0 *1.0.0 2.0.0
foo *1.0.0 *1.0.0 *1.0.0 2.0.0
diff --git a/test/outdated/goldens/newer_versions.txt b/test/outdated/goldens/newer_versions.txt
index 32216b7..1580804 100644
--- a/test/outdated/goldens/newer_versions.txt
+++ b/test/outdated/goldens/newer_versions.txt
@@ -149,7 +149,7 @@
3 dependencies are constrained to versions that are older than a resolvable version.
To update these dependencies, edit pubspec.yaml.
-$ pub outdated --no-color --pre-releases
+$ pub outdated --no-color --prereleases
Dependencies Current Upgradable Resolvable Latest
foo *1.2.3 *1.3.0 *2.0.0 3.0.0
diff --git a/test/outdated/goldens/no_dependencies.txt b/test/outdated/goldens/no_dependencies.txt
index bfd5e07..fc40068 100644
--- a/test/outdated/goldens/no_dependencies.txt
+++ b/test/outdated/goldens/no_dependencies.txt
@@ -12,7 +12,7 @@
$ pub outdated --no-color --up-to-date
Found no outdated packages.
-$ pub outdated --no-color --pre-releases
+$ pub outdated --no-color --prereleases
Found no outdated packages.
$ pub outdated --no-color --no-dev-dependencies
diff --git a/test/outdated/outdated_test.dart b/test/outdated/outdated_test.dart
index 1d3f222..b8aaf8a 100644
--- a/test/outdated/outdated_test.dart
+++ b/test/outdated/outdated_test.dart
@@ -7,6 +7,18 @@
import '../golden_file.dart';
import '../test_pub.dart';
+/// Runs `pub outdated [args]` and appends the output to [buffer].
+Future<void> runPubOutdated(List<String> args, StringBuffer buffer) async {
+ final process = await startPub(args: ['outdated', ...args]);
+ await process.shouldExit(0);
+ expect(await process.stderr.rest.toList(), isEmpty);
+ buffer.writeln([
+ '\$ pub outdated ${args.join(' ')}',
+ ...await process.stdout.rest.toList()
+ ].join('\n'));
+ buffer.write('\n');
+}
+
/// Try running 'pub outdated' with a number of different sets of arguments.
///
/// Compare the output to the file in goldens/$[name].
@@ -17,18 +29,11 @@
['--no-color'],
['--no-color', '--mark=none'],
['--no-color', '--up-to-date'],
- ['--no-color', '--pre-releases'],
+ ['--no-color', '--prereleases'],
['--no-color', '--no-dev-dependencies'],
['--no-color', '--no-dependency-overrides'],
]) {
- final process = await startPub(args: ['outdated', ...args]);
- await process.shouldExit(0);
- expect(await process.stderr.rest.toList(), isEmpty);
- buffer.writeln([
- '\$ pub outdated ${args.join(' ')}',
- ...await process.stdout.rest.toList()
- ].join('\n'));
- buffer.write('\n');
+ await runPubOutdated(args, buffer);
}
// The easiest way to update the golden files is to delete them and rerun the
// test.
@@ -36,6 +41,12 @@
}
Future<void> main() async {
+ test('help text', () async {
+ final buffer = StringBuffer();
+ await runPubOutdated(['--help'], buffer);
+ expectMatchesGoldenFile(
+ buffer.toString(), 'test/outdated/goldens/helptext.txt');
+ });
test('no dependencies', () async {
await d.appDir().create();
await pubGet();
