Flutter版本控制信息插件commit_info的使用

Flutter版本控制信息插件commit_info的使用

概述

commit_info 是一个用于在Dart项目中安全获取版本控制信息的小工具。在原型或开发阶段，你可能需要你的应用程序包含从哪个特定提交构建的信息。但由于Flutter构建系统的工作方式，这可能会变得具有挑战性，甚至可能需要一些hack。

commit_info 可以创建一个名为 commit_info.g.dart 的文件，其格式如下：

class CommitInfo {
  final String commitId;
  final String commitIdShort;
  final int? timestamp;
  final String? branch;
  final bool? localChanges;

  const CommitInfo({
    required this.commitId,
    required this.commitIdShort,
    required this.timestamp,
    required this.branch,
    this.localChanges = false,
  });

  DateTime? get dateTime => timestamp == null ? null : DateTime.fromMicrosecondsSinceEpoch(timestamp!);
}

const CommitInfo? commitInfo = CommitInfo(
  commitId: "2685ecba8f68feae8f42acb3bc001e73a9290cc5",
  commitIdShort: "2685ecb",
  timestamp: 1693745311,
  branch: "main",
  localChanges: true,
);

你可能希望将此文件添加到 .gitignore 中，以避免在构建过程中出现错误的版本信息。（是的，我知道我也能生成该文件到构建缓存中，但Flutter在那里找不到它……）

目前，它仅支持Git，但它被设计为与版本控制系统无关，支持其他版本控制系统应该很容易实现。

当然，它没有任何Flutter依赖项，因此你也可以在任何Dart项目中使用它。事实上，如果你用 build 构建项目，它应该更有用，因为它会无缝集成。

开始使用

要添加 commit_info 插件，请运行以下命令：

flutter pub add dev:commit_info dev:build_runner

唯一的前提条件是，你所使用的版本控制系统所需的命令行工具必须在任何你想运行此插件的环境中可用（包括CI）。

使用示例

要使用 commit_info，只需导入并使用 commitInfo 常量。

import 'commit_info.g.dart';

class CommitInfoWidget extends StatelessWidget {
  const CommitInfoWidget({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) => Text((commitInfo == null)
      ? "unknown"
      : "commit ${commitInfo!.commitIdShort} on ${commitInfo!.branch}, from ${commitInfo!.timestamp}${commitInfo!.localChanges ? " (with local changes)" : ""}");
}

你可以在该库的git仓库中的 example 文件夹里找到一个稍微复杂一点的例子。

由于截至撰写时，Flutter构建工具还不支持扩展，你需要在构建应用之前手动运行构建器。你可以通过以下命令行来完成：

dart run build_runner build

在CI环境中，只需在 flutter build 步骤之前添加上述命令即可。在开发环境中，没有必要每次构建都运行它；每段编码会话运行一次或者在需要准确信息时每次提交运行一次就足够了。如果你更喜欢从编辑器或IDE运行Flutter，可以添加一个动作来为你运行它。

如果你不想在CI中运行它，可以使用以下命令来创建一个 null 的 CommitInfo：

dart run commit_info:initialize

这将会创建一个包含 null CommitInfo 的 commit_info.g.dart 文件。

你也可以运行这个命令来创建一个 null 的 CommitInfo 并将其推送到版本控制系统，作为替代方案，而不是 .gitignore 生成的文件。虽然这有点麻烦，因为你每次提交前都需要回退这个文件，但这是一种选择。

完整示例

以下是一个完整的示例代码，展示了如何在Flutter项目中使用 commit_info 插件：

// main.dart
import 'package:flutter/material.dart';
import 'commit_info.g.dart'; // 导入生成的commit_info文件

class MyApp extends StatelessWidget {
  final SettingsController settingsController;

  MyApp({required this.settingsController});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: Scaffold(
        appBar: AppBar(
          title: Text('Flutter Demo Home Page'),
        ),
        body: Center(
          child: CommitInfoWidget(),
        ),
      ),
    );
  }
}

class CommitInfoWidget extends StatelessWidget {
  const CommitInfoWidget({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Text((commitInfo == null)
        ? "unknown"
        : "commit ${commitInfo!.commitIdShort} on ${commitInfo!.branch}, from ${commitInfo!.timestamp}${commitInfo!.localChanges ? " (with local changes)" : ""}");
  }
}