version.dart 30.6 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6 7
import 'package:meta/meta.dart';

import 'base/common.dart';
8
import 'base/file_system.dart';
9
import 'base/io.dart';
10
import 'base/process.dart';
11
import 'base/time.dart';
12
import 'cache.dart';
13
import 'convert.dart';
14
import 'globals.dart' as globals;
15

16 17 18 19 20 21 22 23 24 25 26 27 28 29
/// The flutter GitHub repository.
String get _flutterGit => globals.platform.environment['FLUTTER_GIT_URL'] ?? 'https://github.com/flutter/flutter.git';

/// This maps old branch names to the names of branches that replaced them.
///
/// For example, in early 2018 we changed from having an "alpha" branch to
/// having a "dev" branch, so anyone using "alpha" now gets transitioned to
/// "dev".
const Map<String, String> kObsoleteBranches = <String, String>{
  'alpha': 'dev',
  'hackathon': 'dev',
  'codelab': 'dev',
};

30 31 32 33 34 35 36 37
/// The names of each channel/branch in order of increasing stability.
enum Channel {
  master,
  dev,
  beta,
  stable,
}

38 39 40 41 42 43 44
// Beware: Keep order in accordance with stability
const Set<String> kOfficialChannels = <String>{
  'master',
  'dev',
  'beta',
  'stable',
};
45

46 47
/// Retrieve a human-readable name for a given [channel].
///
48
/// Requires [kOfficialChannels] to be correctly ordered.
49
String getNameForChannel(Channel channel) {
50
  return kOfficialChannels.elementAt(channel.index);
51 52 53 54 55
}

/// Retrieve the [Channel] representation for a string [name].
///
/// Returns `null` if [name] is not in the list of official channels, according
56
/// to [kOfficialChannels].
57
Channel getChannelForName(String name) {
58 59
  if (kOfficialChannels.contains(name)) {
    return Channel.values[kOfficialChannels.toList().indexOf(name)];
60 61 62 63
  }
  return null;
}

64
class FlutterVersion {
65 66 67 68 69
  /// Parses the Flutter version from currently available tags in the local
  /// repo.
  ///
  /// Call [fetchTagsAndUpdate] to update the version based on the latest tags
  /// available upstream.
70 71 72
  FlutterVersion([this._clock = const SystemClock(), this._workingDirectory]) {
    _frameworkRevision = _runGit(
      gitLog(<String>['-n', '1', '--pretty=format:%H']).join(' '),
73
      processUtils,
74 75
      _workingDirectory,
    );
76
    _gitTagVersion = GitTagVersion.determine(processUtils, workingDirectory: _workingDirectory, fetchTags: false);
77 78 79 80 81 82 83 84 85 86
    _frameworkVersion = gitTagVersion.frameworkVersionFor(_frameworkRevision);
  }

  /// Fetchs tags from the upstream Flutter repository and re-calculates the
  /// version.
  ///
  /// This carries a performance penalty, and should only be called when the
  /// user explicitly wants to get the version, e.g. for `flutter --version` or
  /// `flutter doctor`.
  void fetchTagsAndUpdate() {
87
    _gitTagVersion = GitTagVersion.determine(processUtils, workingDirectory: _workingDirectory, fetchTags: true);
88
    _frameworkVersion = gitTagVersion.frameworkVersionFor(_frameworkRevision);
89
  }
90

91
  final SystemClock _clock;
92
  final String _workingDirectory;
93

94
  String _repositoryUrl;
95 96 97 98
  String get repositoryUrl {
    final String _ = channel;
    return _repositoryUrl;
  }
99

100 101 102 103
  /// Whether we are currently on the master branch.
  bool get isMaster {
    final String branchName = getBranchName();
    return !<String>['dev', 'beta', 'stable'].contains(branchName);
104 105
  }

106
  String _channel;
107
  /// The channel is the upstream branch.
108
  /// `master`, `dev`, `beta`, `stable`; or old ones, like `alpha`, `hackathon`, ...
109 110
  String get channel {
    if (_channel == null) {
111 112
      final String channel = _runGit(
        'git rev-parse --abbrev-ref --symbolic @{u}',
113
        processUtils,
114 115
        _workingDirectory,
      );
116 117 118
      final int slash = channel.indexOf('/');
      if (slash != -1) {
        final String remote = channel.substring(0, slash);
119 120
        _repositoryUrl = _runGit(
          'git ls-remote --get-url $remote',
121
          processUtils,
122 123
          _workingDirectory,
        );
124
        _channel = channel.substring(slash + 1);
125
      } else if (channel.isEmpty) {
126 127 128 129 130 131 132
        _channel = 'unknown';
      } else {
        _channel = channel;
      }
    }
    return _channel;
  }
133

134 135 136
  GitTagVersion _gitTagVersion;
  GitTagVersion get gitTagVersion => _gitTagVersion;

137 138
  /// The name of the local branch.
  /// Use getBranchName() to read this.
139 140
  String _branch;

141 142
  String _frameworkRevision;
  String get frameworkRevision => _frameworkRevision;
143
  String get frameworkRevisionShort => _shortGitRevision(frameworkRevision);
144 145

  String _frameworkAge;
146
  String get frameworkAge {
147 148
    return _frameworkAge ??= _runGit(
      gitLog(<String>['-n', '1', '--pretty=format:%ar']).join(' '),
149
      processUtils,
150 151
      _workingDirectory,
    );
152
  }
153

154 155 156
  String _frameworkVersion;
  String get frameworkVersion => _frameworkVersion;

157 158
  String get frameworkDate => frameworkCommitDate;

159
  String get dartSdkVersion => globals.cache.dartSdkVersion;
160

161
  String get engineRevision => globals.cache.engineRevision;
162
  String get engineRevisionShort => _shortGitRevision(engineRevision);
163

164
  Future<void> ensureVersionFile() {
165
    globals.fs.file(globals.fs.path.join(Cache.flutterRoot, 'version')).writeAsStringSync(_frameworkVersion);
166
    return Future<void>.value();
167
  }
168 169 170

  @override
  String toString() {
171
    final String versionText = frameworkVersion == 'unknown' ? '' : ' $frameworkVersion';
172
    final String flutterText = 'Flutter$versionText • channel $channel${repositoryUrl ?? 'unknown source'}';
173 174 175
    final String frameworkText = 'Framework • revision $frameworkRevisionShort ($frameworkAge) • $frameworkCommitDate';
    final String engineText = 'Engine • revision $engineRevisionShort';
    final String toolsText = 'Tools • Dart $dartSdkVersion';
176

177 178 179 180
    // Flutter 1.10.2-pre.69 • channel master • https://github.com/flutter/flutter.git
    // Framework • revision 340c158f32 (84 minutes ago) • 2018-10-26 11:27:22 -0400
    // Engine • revision 9c46333e14
    // Tools • Dart 2.1.0 (build 2.1.0-dev.8.0 bf26f760b1)
181

182
    return '$flutterText\n$frameworkText\n$engineText\n$toolsText';
183 184
  }

185
  Map<String, Object> toJson() => <String, Object>{
186 187 188 189 190 191 192 193
    'frameworkVersion': frameworkVersion ?? 'unknown',
    'channel': channel,
    'repositoryUrl': repositoryUrl ?? 'unknown source',
    'frameworkRevision': frameworkRevision,
    'frameworkCommitDate': frameworkCommitDate,
    'engineRevision': engineRevision,
    'dartSdkVersion': dartSdkVersion,
  };
194

195
  /// A date String describing the last framework commit.
196 197 198 199 200 201 202 203 204 205 206 207 208
  ///
  /// If a git command fails, this will return a placeholder date.
  String get frameworkCommitDate => _latestGitCommitDate(lenient: true);

  // The date of the latest commit on the given branch. If no branch is
  // specified, then it is the current local branch.
  //
  // If lenient is true, and the git command fails, a placeholder date is
  // returned. Otherwise, the VersionCheckError exception is propagated.
  static String _latestGitCommitDate({
    String branch,
    bool lenient = false,
  }) {
209
    final List<String> args = gitLog(<String>[
210 211 212 213 214
      if (branch != null) branch,
      '-n',
      '1',
      '--pretty=format:%ad',
      '--date=iso',
215
    ]);
216 217 218 219 220 221 222
    try {
      // Don't plumb 'lenient' through directly so that we can print an error
      // if something goes wrong.
      return _runSync(args, lenient: false);
    } on VersionCheckError catch (e) {
      if (lenient) {
        final DateTime dummyDate = DateTime.fromMillisecondsSinceEpoch(0);
223
        globals.printError('Failed to find the latest git commit date: $e\n'
224 225 226 227 228 229 230
          'Returning $dummyDate instead.');
        // Return something that DateTime.parse() can parse.
        return dummyDate.toString();
      } else {
        rethrow;
      }
    }
231 232 233 234 235 236 237 238
  }

  /// The name of the temporary git remote used to check for the latest
  /// available Flutter framework version.
  ///
  /// In the absence of bugs and crashes a Flutter developer should never see
  /// this remote appear in their `git remote` list, but also if it happens to
  /// persist we do the proper clean-up for extra robustness.
239
  static const String _versionCheckRemote = '__flutter_version_check__';
240 241 242

  /// The date of the latest framework commit in the remote repository.
  ///
243 244
  /// Throws [VersionCheckError] if a git command fails, for example, when the
  /// remote git repository is not reachable due to a network issue.
245
  static Future<String> fetchRemoteFrameworkCommitDate(String branch) async {
246 247 248 249 250 251
    await _removeVersionCheckRemoteIfExists();
    try {
      await _run(<String>[
        'git',
        'remote',
        'add',
252
        _versionCheckRemote,
253
        _flutterGit,
254
      ]);
255
      await _run(<String>['git', 'fetch', _versionCheckRemote, branch]);
256 257 258 259
      return _latestGitCommitDate(
        branch: '$_versionCheckRemote/$branch',
        lenient: false,
      );
260 261 262 263 264 265 266
    } on VersionCheckError catch (error) {
      if (globals.platform.environment.containsKey('FLUTTER_GIT_URL')) {
        globals.logger.printError('Warning: the Flutter git upstream was overriden '
        'by the environment variable FLUTTER_GIT_URL = $_flutterGit');
      }
      globals.logger.printError(error.toString());
      rethrow;
267 268 269 270 271
    } finally {
      await _removeVersionCheckRemoteIfExists();
    }
  }

272
  static Future<void> _removeVersionCheckRemoteIfExists() async {
273 274
    final List<String> remotes = (await _run(<String>['git', 'remote']))
        .split('\n')
275
        .map<String>((String name) => name.trim()) // to account for OS-specific line-breaks
276
        .toList();
277
    if (remotes.contains(_versionCheckRemote)) {
278
      await _run(<String>['git', 'remote', 'remove', _versionCheckRemote]);
279
    }
280 281
  }

282
  /// Return a short string for the version (e.g. `master/0.0.59-pre.92`, `scroll_refactor/a76bc8e22b`).
283
  String getVersionString({ bool redactUnknownBranches = false }) {
284
    if (frameworkVersion != 'unknown') {
285
      return '${getBranchName(redactUnknownBranches: redactUnknownBranches)}/$frameworkVersion';
286
    }
287
    return '${getBranchName(redactUnknownBranches: redactUnknownBranches)}/$frameworkRevisionShort';
288 289 290 291
  }

  /// Return the branch name.
  ///
292 293
  /// If [redactUnknownBranches] is true and the branch is unknown,
  /// the branch name will be returned as `'[user-branch]'`.
294
  String getBranchName({ bool redactUnknownBranches = false }) {
295
    _branch ??= () {
296
      final String branch = _runGit('git rev-parse --abbrev-ref HEAD', processUtils);
297 298
      return branch == 'HEAD' ? channel : branch;
    }();
299
    if (redactUnknownBranches || _branch.isEmpty) {
300
      // Only return the branch names we know about; arbitrary branch names might contain PII.
301 302
      if (!kOfficialChannels.contains(_branch) &&
          !kObsoleteBranches.containsKey(_branch)) {
303
        return '[user-branch]';
304
      }
305
    }
306
    return _branch;
307
  }
308

309 310 311 312 313 314 315
  /// Returns true if `tentativeDescendantRevision` is a direct descendant to
  /// the `tentativeAncestorRevision` revision on the Flutter framework repo
  /// tree.
  bool checkRevisionAncestry({
    String tentativeDescendantRevision,
    String tentativeAncestorRevision,
  }) {
316
    final ProcessResult result = globals.processManager.runSync(
317 318 319 320 321 322 323
      <String>[
        'git',
        'merge-base',
        '--is-ancestor',
        tentativeAncestorRevision,
        tentativeDescendantRevision
      ],
324 325 326 327 328
      workingDirectory: Cache.flutterRoot,
    );
    return result.exitCode == 0;
  }

329 330 331
  /// The amount of time we wait before pinging the server to check for the
  /// availability of a newer version of Flutter.
  @visibleForTesting
332
  static const Duration checkAgeConsideredUpToDate = Duration(days: 3);
333 334

  /// We warn the user if the age of their Flutter installation is greater than
335 336 337
  /// this duration. The durations are slightly longer than the expected release
  /// cadence for each channel, to give the user a grace period before they get
  /// notified.
338
  ///
339 340
  /// For example, for the beta channel, this is set to five weeks because
  /// beta releases happen approximately every month.
341
  @visibleForTesting
342 343 344 345 346 347 348 349 350 351 352 353
  static Duration versionAgeConsideredUpToDate(String channel) {
    switch (channel) {
      case 'stable':
        return const Duration(days: 365 ~/ 2); // Six months
      case 'beta':
        return const Duration(days: 7 * 8); // Eight weeks
      case 'dev':
        return const Duration(days: 7 * 4); // Four weeks
      default:
        return const Duration(days: 7 * 3); // Three weeks
    }
  }
354

355 356 357
  /// The amount of time we wait between issuing a warning.
  ///
  /// This is to avoid annoying users who are unable to upgrade right away.
358
  @visibleForTesting
359
  static const Duration maxTimeSinceLastWarning = Duration(days: 1);
360 361 362 363 364 365

  /// The amount of time we pause for to let the user read the message about
  /// outdated Flutter installation.
  ///
  /// This can be customized in tests to speed them up.
  @visibleForTesting
366
  static Duration timeToPauseToLetUserReadTheMessage = const Duration(seconds: 2);
367

368 369 370 371 372 373
  /// Reset the version freshness information by removing the stamp file.
  ///
  /// New version freshness information will be regenerated when
  /// [checkFlutterVersionFreshness] is called after this. This is typically
  /// used when switching channels so that stale information from another
  /// channel doesn't linger.
374
  static Future<void> resetFlutterVersionFreshnessCheck() async {
375
    try {
376
      await globals.cache.getStampFileFor(
377
        VersionCheckStamp.flutterVersionCheckStampFile,
378 379 380 381 382 383
      ).delete();
    } on FileSystemException {
      // Ignore, since we don't mind if the file didn't exist in the first place.
    }
  }

384 385 386 387 388
  /// Checks if the currently installed version of Flutter is up-to-date, and
  /// warns the user if it isn't.
  ///
  /// This function must run while [Cache.lock] is acquired because it reads and
  /// writes shared cache files.
389
  Future<void> checkFlutterVersionFreshness() async {
390
    // Don't perform update checks if we're not on an official channel.
391
    if (!kOfficialChannels.contains(channel)) {
392 393 394
      return;
    }

395 396 397 398 399 400
    DateTime localFrameworkCommitDate;
    try {
      localFrameworkCommitDate = DateTime.parse(_latestGitCommitDate(
        lenient: false
      ));
    } on VersionCheckError {
401
      // Don't perform the update check if the version check failed.
402 403 404
      return;
    }

405
    final Duration frameworkAge = _clock.now().difference(localFrameworkCommitDate);
406
    final bool installationSeemsOutdated = frameworkAge > versionAgeConsideredUpToDate(channel);
407

408 409 410 411
    // Get whether there's a newer version on the remote. This only goes
    // to the server if we haven't checked recently so won't happen on every
    // command.
    final DateTime latestFlutterCommitDate = await _getLatestAvailableFlutterDate();
412 413 414 415 416
    final VersionCheckResult remoteVersionStatus = latestFlutterCommitDate == null
        ? VersionCheckResult.unknown
        : latestFlutterCommitDate.isAfter(localFrameworkCommitDate)
          ? VersionCheckResult.newVersionAvailable
          : VersionCheckResult.versionIsCurrent;
417 418

    // Do not load the stamp before the above server check as it may modify the stamp file.
419
    final VersionCheckStamp stamp = await VersionCheckStamp.load();
420 421
    final DateTime lastTimeWarningWasPrinted = stamp.lastTimeWarningWasPrinted ?? _clock.ago(maxTimeSinceLastWarning * 2);
    final bool beenAWhileSinceWarningWasPrinted = _clock.now().difference(lastTimeWarningWasPrinted) > maxTimeSinceLastWarning;
422

423 424 425
    // We show a warning if either we know there is a new remote version, or we couldn't tell but the local
    // version is outdated.
    final bool canShowWarning =
426 427 428
      remoteVersionStatus == VersionCheckResult.newVersionAvailable ||
        (remoteVersionStatus == VersionCheckResult.unknown &&
          installationSeemsOutdated);
429 430 431

    if (beenAWhileSinceWarningWasPrinted && canShowWarning) {
      final String updateMessage =
432 433 434
        remoteVersionStatus == VersionCheckResult.newVersionAvailable
          ? newVersionAvailableMessage()
          : versionOutOfDateMessage(frameworkAge);
435
      globals.printStatus(updateMessage, emphasis: true);
436
      await Future.wait<void>(<Future<void>>[
xster's avatar
xster committed
437 438 439
        stamp.store(
          newTimeWarningWasPrinted: _clock.now(),
        ),
440
        Future<void>.delayed(timeToPauseToLetUserReadTheMessage),
441
      ]);
442
    }
443 444
  }

445 446 447 448 449 450 451 452
  /// log.showSignature=false is a user setting and it will break things,
  /// so we want to disable it for every git log call.  This is a convenience
  /// wrapper that does that.
  @visibleForTesting
  static List<String> gitLog(List<String> args) {
    return <String>['git', '-c', 'log.showSignature=false', 'log'] + args;
  }

453 454 455 456 457 458 459 460 461 462 463 464 465 466 467
  @visibleForTesting
  static String versionOutOfDateMessage(Duration frameworkAge) {
    String warning = 'WARNING: your installation of Flutter is ${frameworkAge.inDays} days old.';
    // Append enough spaces to match the message box width.
    warning += ' ' * (74 - warning.length);

    return '''
  ╔════════════════════════════════════════════════════════════════════════════╗
$warning
  ║                                                                            ║
  ║ To update to the latest version, run "flutter upgrade".                    ║
  ╚════════════════════════════════════════════════════════════════════════════╝
''';
  }

468 469 470 471 472 473 474 475 476 477 478
  @visibleForTesting
  static String newVersionAvailableMessage() {
    return '''
  ╔════════════════════════════════════════════════════════════════════════════╗
  ║ A new version of Flutter is available!                                     ║
  ║                                                                            ║
  ║ To update to the latest version, run "flutter upgrade".                    ║
  ╚════════════════════════════════════════════════════════════════════════════╝
''';
  }

479 480 481
  /// Gets the release date of the latest available Flutter version.
  ///
  /// This method sends a server request if it's been more than
482
  /// [checkAgeConsideredUpToDate] since the last version check.
483
  ///
484
  /// Returns null if the cached version is out-of-date or missing, and we are
485
  /// unable to reach the server to get the latest version.
486
  Future<DateTime> _getLatestAvailableFlutterDate() async {
487
    Cache.checkLockAcquired();
488
    final VersionCheckStamp versionCheckStamp = await VersionCheckStamp.load();
489

490
    if (versionCheckStamp.lastTimeVersionWasChecked != null) {
491 492 493
      final Duration timeSinceLastCheck = _clock.now().difference(
        versionCheckStamp.lastTimeVersionWasChecked,
      );
494 495

      // Don't ping the server too often. Return cached value if it's fresh.
496
      if (timeSinceLastCheck < checkAgeConsideredUpToDate) {
497
        return versionCheckStamp.lastKnownRemoteVersion;
498
      }
499 500 501 502
    }

    // Cache is empty or it's been a while since the last server ping. Ping the server.
    try {
503 504 505
      final DateTime remoteFrameworkCommitDate = DateTime.parse(
        await FlutterVersion.fetchRemoteFrameworkCommitDate(channel),
      );
xster's avatar
xster committed
506
      await versionCheckStamp.store(
507 508 509
        newTimeVersionWasChecked: _clock.now(),
        newKnownRemoteVersion: remoteFrameworkCommitDate,
      );
510 511 512 513 514
      return remoteFrameworkCommitDate;
    } on VersionCheckError catch (error) {
      // This happens when any of the git commands fails, which can happen when
      // there's no Internet connectivity. Remote version check is best effort
      // only. We do not prevent the command from running when it fails.
515
      globals.printTrace('Failed to check Flutter version in the remote repository: $error');
516 517 518 519 520
      // Still update the timestamp to avoid us hitting the server on every single
      // command if for some reason we cannot connect (eg. we may be offline).
      await versionCheckStamp.store(
        newTimeVersionWasChecked: _clock.now(),
      );
521 522 523
      return null;
    }
  }
524 525
}

526 527 528 529 530 531 532 533 534 535 536 537 538
/// Contains data and load/save logic pertaining to Flutter version checks.
@visibleForTesting
class VersionCheckStamp {
  const VersionCheckStamp({
    this.lastTimeVersionWasChecked,
    this.lastKnownRemoteVersion,
    this.lastTimeWarningWasPrinted,
  });

  final DateTime lastTimeVersionWasChecked;
  final DateTime lastKnownRemoteVersion;
  final DateTime lastTimeWarningWasPrinted;

539 540
  /// The prefix of the stamp file where we cache Flutter version check data.
  @visibleForTesting
541
  static const String flutterVersionCheckStampFile = 'flutter_version_check';
542

543
  static Future<VersionCheckStamp> load() async {
544
    final String versionCheckStamp = globals.cache.getStampFor(flutterVersionCheckStampFile);
545 546 547 548

    if (versionCheckStamp != null) {
      // Attempt to parse stamp JSON.
      try {
549
        final dynamic jsonObject = json.decode(versionCheckStamp);
550
        if (jsonObject is Map<String, dynamic>) {
551
          return fromJson(jsonObject);
552
        } else {
553
          globals.printTrace('Warning: expected version stamp to be a Map but found: $jsonObject');
554
        }
555
      } on Exception catch (error, stackTrace) {
556
        // Do not crash if JSON is malformed.
557
        globals.printTrace('${error.runtimeType}: $error\n$stackTrace');
558 559 560 561
      }
    }

    // Stamp is missing or is malformed.
562
    return const VersionCheckStamp();
563 564
  }

565
  static VersionCheckStamp fromJson(Map<String, dynamic> jsonObject) {
566
    DateTime readDateTime(String property) {
567
      return jsonObject.containsKey(property)
568
          ? DateTime.parse(jsonObject[property] as String)
569
          : null;
570 571
    }

572
    return VersionCheckStamp(
573 574 575 576 577 578
      lastTimeVersionWasChecked: readDateTime('lastTimeVersionWasChecked'),
      lastKnownRemoteVersion: readDateTime('lastKnownRemoteVersion'),
      lastTimeWarningWasPrinted: readDateTime('lastTimeWarningWasPrinted'),
    );
  }

579
  Future<void> store({
580 581 582 583 584 585
    DateTime newTimeVersionWasChecked,
    DateTime newKnownRemoteVersion,
    DateTime newTimeWarningWasPrinted,
  }) async {
    final Map<String, String> jsonData = toJson();

586
    if (newTimeVersionWasChecked != null) {
587
      jsonData['lastTimeVersionWasChecked'] = '$newTimeVersionWasChecked';
588
    }
589

590
    if (newKnownRemoteVersion != null) {
591
      jsonData['lastKnownRemoteVersion'] = '$newKnownRemoteVersion';
592
    }
593

594
    if (newTimeWarningWasPrinted != null) {
595
      jsonData['lastTimeWarningWasPrinted'] = '$newTimeWarningWasPrinted';
596
    }
597

598
    const JsonEncoder prettyJsonEncoder = JsonEncoder.withIndent('  ');
599
    globals.cache.setStampFor(flutterVersionCheckStampFile, prettyJsonEncoder.convert(jsonData));
600 601 602 603 604 605 606 607 608 609 610 611 612
  }

  Map<String, String> toJson({
    DateTime updateTimeVersionWasChecked,
    DateTime updateKnownRemoteVersion,
    DateTime updateTimeWarningWasPrinted,
  }) {
    updateTimeVersionWasChecked = updateTimeVersionWasChecked ?? lastTimeVersionWasChecked;
    updateKnownRemoteVersion = updateKnownRemoteVersion ?? lastKnownRemoteVersion;
    updateTimeWarningWasPrinted = updateTimeWarningWasPrinted ?? lastTimeWarningWasPrinted;

    final Map<String, String> jsonData = <String, String>{};

613
    if (updateTimeVersionWasChecked != null) {
614
      jsonData['lastTimeVersionWasChecked'] = '$updateTimeVersionWasChecked';
615
    }
616

617
    if (updateKnownRemoteVersion != null) {
618
      jsonData['lastKnownRemoteVersion'] = '$updateKnownRemoteVersion';
619
    }
620

621
    if (updateTimeWarningWasPrinted != null) {
622
      jsonData['lastTimeWarningWasPrinted'] = '$updateTimeWarningWasPrinted';
623
    }
624 625 626 627 628

    return jsonData;
  }
}

629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645
/// Thrown when we fail to check Flutter version.
///
/// This can happen when we attempt to `git fetch` but there is no network, or
/// when the installation is not git-based (e.g. a user clones the repo but
/// then removes .git).
class VersionCheckError implements Exception {

  VersionCheckError(this.message);

  final String message;

  @override
  String toString() => '$VersionCheckError: $message';
}

/// Runs [command] and returns the standard output as a string.
///
646
/// If [lenient] is true and the command fails, returns an empty string.
647
/// Otherwise, throws a [ToolExit] exception.
648
String _runSync(List<String> command, { bool lenient = true }) {
649
  final ProcessResult results = globals.processManager.runSync(
650 651 652
    command,
    workingDirectory: Cache.flutterRoot,
  );
653

654
  if (results.exitCode == 0) {
655
    return (results.stdout as String).trim();
656
  }
657 658

  if (!lenient) {
659
    throw VersionCheckError(
660
      'Command exited with code ${results.exitCode}: ${command.join(' ')}\n'
661
      'Standard out: ${results.stdout}\n'
662 663 664 665 666 667 668
      'Standard error: ${results.stderr}'
    );
  }

  return '';
}

669
String _runGit(String command, ProcessUtils processUtils, [String workingDirectory]) {
670 671
  return processUtils.runSync(
    command.split(' '),
672
    workingDirectory: workingDirectory ?? Cache.flutterRoot,
673
  ).stdout.trim();
674 675
}

676 677 678 679 680
/// Runs [command] in the root of the Flutter installation and returns the
/// standard output as a string.
///
/// If the command fails, throws a [ToolExit] exception.
Future<String> _run(List<String> command) async {
681
  final ProcessResult results = await globals.processManager.run(command, workingDirectory: Cache.flutterRoot);
682

683
  if (results.exitCode == 0) {
684
    return (results.stdout as String).trim();
685
  }
686

687
  throw VersionCheckError(
688 689 690
    'Command exited with code ${results.exitCode}: ${command.join(' ')}\n'
    'Standard error: ${results.stderr}'
  );
691
}
692 693

String _shortGitRevision(String revision) {
694
  if (revision == null) {
695
    return '';
696
  }
697 698
  return revision.length > 10 ? revision.substring(0, 10) : revision;
}
699

700
/// Version of Flutter SDK parsed from Git.
701
class GitTagVersion {
702 703 704 705 706 707 708 709 710
  const GitTagVersion({
    this.x,
    this.y,
    this.z,
    this.hotfix,
    this.devVersion,
    this.devPatch,
    this.commits,
    this.hash,
711
    this.gitTag,
712
  });
713 714 715 716
  const GitTagVersion.unknown()
    : x = null,
      y = null,
      z = null,
717
      hotfix = null,
718
      commits = 0,
719 720
      devVersion = null,
      devPatch = null,
721 722
      hash = '',
      gitTag = '';
723 724 725 726 727 728 729 730 731 732

  /// The X in vX.Y.Z.
  final int x;

  /// The Y in vX.Y.Z.
  final int y;

  /// The Z in vX.Y.Z.
  final int z;

733
  /// the F in vX.Y.Z+hotfix.F.
734 735
  final int hotfix;

736 737 738 739 740 741
  /// Number of commits since the vX.Y.Z tag.
  final int commits;

  /// The git hash (or an abbreviation thereof) for this commit.
  final String hash;

742
  /// The N in X.Y.Z-dev.N.M.
743 744
  final int devVersion;

745
  /// The M in X.Y.Z-dev.N.M.
746 747
  final int devPatch;

748 749 750
  /// The git tag that is this version's closest ancestor.
  final String gitTag;

751 752
  static GitTagVersion determine(ProcessUtils processUtils, {String workingDirectory, bool fetchTags = false}) {
    if (fetchTags) {
753 754 755 756
      final String channel = _runGit('git rev-parse --abbrev-ref HEAD', processUtils, workingDirectory);
      if (channel == 'dev' || channel == 'beta' || channel == 'stable') {
        globals.printTrace('Skipping request to fetchTags - on well known channel $channel.');
      } else {
757
        _runGit('git fetch $_flutterGit --tags -f', processUtils, workingDirectory);
758
      }
759
    }
760
    final List<String> tags = _runGit(
761
      'git tag --points-at HEAD', processUtils, workingDirectory).trim().split('\n');
762 763 764 765

    // Check first for a stable tag
    final RegExp stableTagPattern = RegExp(r'^\d+\.\d+\.\d+$');
    for (final String tag in tags) {
766 767
      if (stableTagPattern.hasMatch(tag.trim())) {
        return parse(tag);
768
      }
769
    }
770 771 772
    // Next check for a dev tag
    final RegExp devTagPattern = RegExp(r'^\d+\.\d+\.\d+-\d+\.\d+\.pre$');
    for (final String tag in tags) {
773 774
      if (devTagPattern.hasMatch(tag.trim())) {
        return parse(tag);
775
      }
776
    }
777 778 779 780 781

    // If we're not currently on a tag, use git describe to find the most
    // recent tag and number of commits past.
    return parse(
      _runGit(
782
        'git describe --match *.*.* --first-parent --long --tags',
783 784 785
        processUtils,
        workingDirectory,
      )
786 787 788
    );
  }

789 790 791 792 793 794
  /// Parse a version string.
  ///
  /// The version string can either be an exact release tag (e.g. '1.2.3' for
  /// stable or 1.2.3-4.5.pre for a dev) or the output of `git describe` (e.g.
  /// for commit abc123 that is 6 commits after tag 1.2.3-4.5.pre, git would
  /// return '1.2.3-4.5.pre-6-gabc123').
795 796
  static GitTagVersion parseVersion(String version) {
    final RegExp versionPattern = RegExp(
797 798 799
      r'^(\d+)\.(\d+)\.(\d+)(-\d+\.\d+\.pre)?(?:-(\d+)-g([a-f0-9]+))?$');
    final Match match = versionPattern.firstMatch(version.trim());
    if (match == null) {
800 801
      return const GitTagVersion.unknown();
    }
802 803 804 805 806 807 808 809 810 811 812 813 814

    final List<String> matchGroups = match.groups(<int>[1, 2, 3, 4, 5, 6]);
    final int x = matchGroups[0] == null ? null : int.tryParse(matchGroups[0]);
    final int y = matchGroups[1] == null ? null : int.tryParse(matchGroups[1]);
    final int z = matchGroups[2] == null ? null : int.tryParse(matchGroups[2]);
    final String devString = matchGroups[3];
    int devVersion, devPatch;
    if (devString != null) {
      final Match devMatch = RegExp(r'^-(\d+)\.(\d+)\.pre$')
        .firstMatch(devString);
      final List<String> devGroups = devMatch.groups(<int>[1, 2]);
      devVersion = devGroups[0] == null ? null : int.tryParse(devGroups[0]);
      devPatch = devGroups[1] == null ? null : int.tryParse(devGroups[1]);
815
    }
816 817 818 819
    // count of commits past last tagged version
    final int commits = matchGroups[4] == null ? 0 : int.tryParse(matchGroups[4]);
    final String hash = matchGroups[5] ?? '';

820
    return GitTagVersion(
821 822 823 824 825 826 827 828
      x: x,
      y: y,
      z: z,
      devVersion: devVersion,
      devPatch: devPatch,
      commits: commits,
      hash: hash,
      gitTag: '$x.$y.$z${devString ?? ''}', // e.g. 1.2.3-4.5.pre
829 830 831 832 833 834 835 836 837 838 839 840
    );
  }

  static GitTagVersion parse(String version) {
    GitTagVersion gitTagVersion;

    gitTagVersion = parseVersion(version);
    if (gitTagVersion != const GitTagVersion.unknown()) {
      return gitTagVersion;
    }
    globals.printTrace('Could not interpret results of "git describe": $version');
    return const GitTagVersion.unknown();
841 842 843
  }

  String frameworkVersionFor(String revision) {
844
    if (x == null || y == null || z == null || !revision.startsWith(hash)) {
845
      return '0.0.0-unknown';
846
    }
847
    if (commits == 0) {
848
      return gitTag;
849
    }
850
    if (hotfix != null) {
851 852 853 854 855
      // This is an unexpected state where untagged commits exist past a hotfix
      return '$x.$y.$z+hotfix.${hotfix + 1}.pre.$commits';
    }
    if (devPatch != null && devVersion != null) {
      return '$x.$y.$z-${devVersion + 1}.0.pre.$commits';
856
    }
857
    return '$x.$y.${z + 1}-0.0.pre.$commits';
858 859
  }
}
860 861 862 863 864 865 866 867 868 869

enum VersionCheckResult {
  /// Unable to check whether a new version is available, possibly due to
  /// a connectivity issue.
  unknown,
  /// The current version is up to date.
  versionIsCurrent,
  /// A newer version is available.
  newVersionAvailable,
}