unplugin-auto-git-info

Unplugin for automatically generating Git information (repo, branch, commit, etc.) in multiple output formats.

Features

• 📦 Automatically extract Git repository information
• 🎯 Support multiple output formats:
  • JSON file
  • Window global variable (via define replacement and HTML injection)
• 🔧 Works with all major build tools (Vite, Webpack, Rollup, esbuild, Rspack, etc.)
• ⚙️ Configurable fields and output options
• 🚀 Compile-time injection for optimal performance

Installation

npm i -D unplugin-auto-git-info

Usage

// vite.config.ts
import AutoGitInfo from 'unplugin-auto-git-info/vite'

export default defineConfig({
  plugins: [AutoGitInfo()],
})

// rollup.config.js
import AutoGitInfo from 'unplugin-auto-git-info/rollup'

export default {
  plugins: [AutoGitInfo()],
}

// rolldown.config.ts / tsdown.config.ts
import AutoGitInfo from 'unplugin-auto-git-info/rolldown'

export default {
  plugins: [AutoGitInfo()],
}

import { build } from 'esbuild'
import AutoGitInfo from 'unplugin-auto-git-info/esbuild'

build({
  plugins: [AutoGitInfo()],
})

// webpack.config.js
import AutoGitInfo from 'unplugin-auto-git-info/webpack'

export default {
  /* ... */
  plugins: [AutoGitInfo()],
}

// rspack.config.js
import AutoGitInfo from 'unplugin-auto-git-info/rspack'

export default {
  /* ... */
  plugins: [AutoGitInfo()],
}

Configuration

Default Behavior

By default, the plugin will:

• Be enabled (enable: true)
• Extract all available Git fields (repo, branch, commit, commitShort, author, authorEmail, commitTime, commitMessage, isDirty)
• Generate a JSON file at your build output directory (e.g., dist/git-info.json for Vite)
• Automatically detect the output directory from your build tool configuration
• Run after build completion

You can use the plugin without any configuration:

// vite.config.ts
import AutoGitInfo from 'unplugin-auto-git-info/vite'

export default defineConfig({
  plugins: [AutoGitInfo()], // That's it!
})

Advanced Configuration

AutoGitInfo({
  // Enable/disable the plugin (default: true)
  enable: true,

  // Git fields to include (default: all)
  fields: ['repo', 'branch', 'commit', 'commitShort', 'author', 'authorEmail', 'commitTime', 'commitMessage', 'isDirty'],

  // Output options
  outputs: {
    // Generate JSON file (default: 'git-info.json' in output directory)
    json: {
      fileName: 'git-info.json', // Relative to build output directory
    },

    // Generate window global variable (default: '__GIT_INFO__')
    // Uses define replacement for compile-time injection
    window: {
      varName: '__GIT_INFO__', // Global variable name
      console: true, // Log Git info to browser console (default: false)
    },
  },

  // Working directory (optional, defaults to process.cwd())
  // cwd: './custom-path',
})

Disable the Plugin

You can conditionally disable the plugin based on environment:

import AutoGitInfo from 'unplugin-auto-git-info/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    AutoGitInfo({
      enable: process.env.NODE_ENV === 'production', // Only enable in production
    }),
  ],
})

Or completely disable it:

AutoGitInfo({
  enable: false, // Plugin will not generate any files
})

Git Fields

The following Git information can be extracted:

• repo - Repository name (extracted from remote URL or directory name)
• branch - Current branch name (handles detached HEAD state)
• commit - Full commit hash
• commitShort - Short commit hash (7 characters)
• author - Author name
• authorEmail - Author email
• commitTime - Commit timestamp (ISO 8601 format)
• commitMessage - Commit message (first line, newlines removed)
• tag - Current tag if HEAD points to a tag
• isDirty - Whether the working directory has uncommitted changes
• remoteUrl - Remote repository URL (e.g., https://github.com/user/repo.git)
• root - Git repository root directory path

Output Examples

JSON Output

By default, the JSON file is generated at your build output directory (e.g., dist/git-info.json):

{
  "repo": "https://github.com/user/repo.git",
  "branch": "main",
  "commit": "abc123def456...",
  "commitShort": "abc123d",
  "author": "John Doe",
  "authorEmail": "[email protected]",
  "commitTime": "2025-01-08T12:00:00.000Z",
  "commitMessage": "feat: add new feature",
  "isDirty": false
}

Window Variable Output

When window output is enabled, the plugin will:

1. For Vite: Automatically inject a <script> tag into your HTML <head> section
2. For other build tools: Use define replacement to inject the variable at compile time
3. Optionally log Git info to browser console (with console: true)

You can then access the Git info anywhere in your code:

// In your browser code
console.log(window.__GIT_INFO__)
console.log(window.__GIT_INFO__.branch)
console.log(window.__GIT_INFO__.commit)

How it works:

• Vite: The plugin injects a <script> tag in the HTML that sets window.__GIT_INFO__ before your code runs
• Other build tools: Uses define replacement - code references to window.__GIT_INFO__ are replaced with the actual Git info object at compile time

Example HTML injection (Vite):

<script>
  if (typeof window !== 'undefined') {
    window.__GIT_INFO__ = {"repo":"...","branch":"main",...};
    // console.log('[Git Info]', window.__GIT_INFO__); // if console: true
  }
</script>

Note: For non-Vite build tools, you need to reference window.__GIT_INFO__ in your code for the define replacement to work.

License

MIT License © 2025-PRESENT Drswith