git_stamp 5.1.0

Advanced await-less information provider. From simple information such as build-branch to a screen with Flutter code with commits and change history.

Git Stamp 🏷 Stamp Every App Build!

Advanced await-less information provider and development tool.

• Git Stamp 🏷 Stamp Every App Build!
  • 🏞️ Preview
  • 📑️ About
    • 1. Why Git Stamp?
    • 2. 🕯️ Mechanism
    • 3. Motivation
    • 4. Changelog
  • 🛠️ Installation
    • 1. pubspec.yaml
    • 2. .gitignore
    • 3. analysis_options.yaml
    • 4. README.md
    • 5. 📦 Integration - GitHub Actions
  • 🏗️ Generating
    • 1. Examples
    • 2. Benchmarks (Repo 615 Commits)
    • 3. Tip
    • 4. Custom gen-only parameters
  • 💻 Usage
    • 1. GitStampListTile
    • 2. GitStampIcon
    • 3. Custom
    • 4. showGitStampLicensePage()
    • 5. Central GitStamp node for advanced usage:
  • 💰 Sponsors
  • 📝 License

🏞️ Preview

Status	Link
📂 Decrypted	gitstamp.web.app
🔒 Encrypted	gitstamp-encrypted.web.app

📑️ About

1. Why Git Stamp?

When working with Flutter and Git, especially in a team environment, human errors such as forgetting to run git pull can lead to issues during branch merges. Git Stamp helps address these problems by offering:

• Build Date, SHA & Branch Information - Git Stamp allows you to precisely determine which version of the application was deployed. This is especially useful during debugging or verifying issues, as application versions and build numbers are not always updated correctly.
• Debugging and Troubleshooting - Knowing the build date and exact code version (SHA) makes it much easier for the development team to identify the problematic code when users report bugs.
• Avoiding Lost Changes in Teamwork - It allows you to quickly see which commits made it into the final version of the application, helping to prevent missing changes due to overlooked git pull commands.
• Caching Issues in the Web Version - Even if the latest version is deployed, users may still see an older version due to caching. Git Stamp helps identify whether the deployed version or an outdated one was loaded.

2. 🕯️ Mechanism

graph TD
    CODE((SOURCE CODE))-->SYNC(flutter pub get)
    SYNC-->BUILD(flutter build ...)

    subgraph "App"
        CODE
        PUB
        PUB((PACKAGES))-->CODE
    end

    subgraph "Git Stamp"
        GIT_CLI(GIT CLI)-->GENERATOR
        DART_CLI(DART CLI)-->GENERATOR
        FLUTTER_CLI(FLUTTER CLI)-->GENERATOR
    end

    subgraph "Git Stamp CLI"
        GENERATE
        ADD
    end

    GENERATOR((GENERATOR))-->ADD(~$ dart pub add git_stamp)
    ADD-->|Add package|PUB

    GENERATOR-->GENERATE(~$ dart run git_stamp)
    GENERATE-->|Create ./git_stamp directory with .dart files|CODE

3. Motivation

The main motivation was Minecraft with information like this:

Version: v1.20.81
Build: 24130126
Branch: r/20_u8
SHA: a9081c5429038dcf3f26269f7351d89f

Git Stamp code:

import 'git_stamp/git_stamp.dart';

Text('Version: ${GitStamp.appVersion}'),
Text('Build: ${GitStamp.appBuild}'),
Text('Branch: ${GitStamp.buildBranch}'),
Text('SHA: ${GitStamp.sha}'),

4. Changelog

🆕 Version	🗓️ Date	📝 Change Description
Version 6	Someday it will be	📦 JSON data export
Version 5	07.10.2024	🔐 Data encription
Version 4	24.07.2024	🌟 New icon build-type
Version 3	30.06.2024	🔧 New gen-only build-type
Version 2	10.04.2024	🛠️ Commit diff
Version 1	11.12.2023	🚀 First version

🛠️ Installation

1. pubspec.yaml

dart pub add git_stamp

2. .gitignore

Important

Add git_stamp to .gitignore.

echo -e "\n/lib/git_stamp/" >> .gitignore.

If you add a /git_stamp folder for the repository and use the FULL version, the size of the repository will grow EXPONENTIALLY.

3. analysis_options.yaml

analyzer:
  exclude:
    - lib/git_stamp/**

4. README.md

Warning

Add badge to your README.md 😄️

[![Git Stamp](https://img.shields.io/badge/i%20love%20Git%20Stamp-ffff99?style=flat)](https://github.com/arononak/git_stamp)

5. 📦 Integration - GitHub Actions

.github/workflows/build_and_deploy.yml

name: build_and_deploy

on:
  push:
    branches: [main]
  pull_request_target:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.22.2'
          channel: 'stable'
      - run: flutter --version
      - uses: actions/setup-java@v1
        with:
          java-version: "12.x"
      - run: flutter pub get
      - run: dart run git_stamp
      - run: flutter build web --release --web-renderer canvaskit
      - uses: actions/upload-artifact@master
        with:
          name: build
          path: build/web
  deploy:
    name: "Deploy"
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v3
      - uses: actions/download-artifact@master
        with:
          name: build
          path: build/web
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: "${{ secrets.GITHUB_TOKEN }}"
          firebaseServiceAccount: "${{ secrets.FIREBASE_SERVICE_ACCOUNT }}"
          projectId: xxx
          channelId: live

🏗️ Generating

1. Examples

Build type	Pure Dart	Can encrypt	CLI Command
FULL	NO	YES	dart run git_stamp --build-type full --adding-packages disabled --encrypt
LITE	NO	YES	dart run git_stamp
ICON	NO	NO	dart run git_stamp --build-type icon
CUSTOM	YES	NO	dart run git_stamp --gen-only build-branch,build-date-time

Note

To optimize the generation you can disable adding packages to the project for LITE & FULL versions by adding a flag in CLI --adding-packages disabled .

2. Benchmarks (Repo 615 Commits)

Build type	Generating time	Number of dart files generated	Size of generated dart files
FULL	10.16s	33	2.3MB
LITE	3.73s	33	167.9 KB
ICON	1.26s	10	8.8 KB

3. Tip

Caution

Generating requires the use of the git command-line interface (CLI).

4. Custom gen-only parameters

#	Parameter
1	commit-list
2	diff-list
3	diff-stat-list
4	repo-creation-date
5	build-branch
6	build-date-time
7	build-system-info
8	build-machine
9	repo-path
10	observed-files-list
11	app-version
12	app-build
13	app-name
14	git-config
15	git-remote
16	git-remote-list
17	git-tag-list

💻 Usage

1. GitStampListTile

if (kDebugMode) ...[
  GitStampListTile(monospaceFontFamily: GoogleFonts.spaceMono().fontFamily),
],

2. GitStampIcon

if (isProd == false) ...[
  GitStampIcon(),
],

3. Custom

if (isProd == false) ...[
  IconButton(
    onPressed: () => showGitStampPage(context: context, monospaceFontFamily: GoogleFonts.spaceMono().fontFamily),
    icon: const Icon(Icons.book),
  ),
],

4. showGitStampLicensePage()

Note

Use function GitStamp.showLicensePage instead of showLicensePage if you want the name and version to be added automatically.

5. Central GitStamp node for advanced usage:

GitStampNode

abstract class GitStampNode {
  String get commitListString;
  List<GitStampCommit> get commitList;
  GitStampCommit? get latestCommit;
  String get sha;
  int get commitCount;

  String get diffListString;
  Map<String, dynamic> get diffList;
  String get diffStatListString;
  Map<String, dynamic> get diffStatList;

  String get buildMachineString;
  GitStampBuildMachine get buildMachine;

  String get buildBranch;
  String get buildDateTime;
  String get buildSystemInfo;
  String get repoCreationDate;
  String get repoPath;
  
  String get observedFiles;
  List<String> get observedFilesList;
  int get observedFilesCount;
  
  String get appVersionFull => appVersion + ' (' + appBuild + ')';
  String get appVersion;
  String get appBuild;
  String get appName;

  String get gitConfigGlobalUser => gitConfigGlobalUserName + ' (' + gitConfigGlobalUserEmail + ')';
  String get gitConfigGlobalUserName;
  String get gitConfigGlobalUserEmail;

  String get gitConfigUser => gitConfigUserName + ' (' + gitConfigUserEmail + ')';
  String get gitConfigUserName;
  String get gitConfigUserEmail;
  
  String get gitRemote;
  String get gitConfigList;
  String get gitCountObjects;

  void showLicensePage({
    required BuildContext context,
    Widget? applicationIcon,
    String? applicationLegalese,
    bool useRootNavigator = false,
  });
}

💰 Sponsors

Aron Code

📝 License

Note

Copyright © 2024 Aron Onak. All rights reserved.
Licensed under the MIT license.
If you have any feedback, please contact me at [e-mail]