Overview
The info functions provide utilities to check Git availability and retrieve version information. These functions are useful for validating the environment before executing Git commands.
isGitInstalled
Check if Git is installed and available in the system PATH.
Syntax
function isGitInstalled(): Promise<boolean>
Returns
A promise that resolves to true if Git is installed and accessible, false otherwise.
Usage Example
import { isGitInstalled } from 'use-git'
const installed = await isGitInstalled()
if (installed) {
console.log('Git is installed')
} else {
console.error('Git is not installed')
process.exit(1)
}
Validation Before Commands
Validate Git availability before running commands:
import { isGitInstalled, git } from 'use-git'
if (await isGitInstalled()) {
await git.clone('https://github.com/user/repo.git')
} else {
throw new Error('Git must be installed to continue')
}
Source Code
Location: src/lib/info/isGitInstalled.ts:6
rawVersion
Get the raw version string from Git, exactly as returned by git --version.
Syntax
function rawVersion(): Promise<string>
Returns
A promise that resolves to the raw version string from Git.Example: "git version 2.51.2.windows.1"
Usage Example
import { rawVersion } from 'use-git'
const version = await rawVersion()
console.log(version)
// Output: "git version 2.51.2.windows.1"
This function caches the result for better performance on subsequent calls.
Source Code
Location: src/lib/info/rawVersion.ts:9
version
Get the parsed Git version number without the “git version” prefix.
Syntax
function version(): Promise<string>
Returns
A promise that resolves to the parsed version number.Example: "2.51.2.windows.1"
Usage Example
import { version } from 'use-git'
const gitVersion = await version()
console.log(`Git version: ${gitVersion}`)
// Output: "Git version: 2.51.2.windows.1"
Version Comparison
Compare Git version for feature detection:
import { version } from 'use-git'
const gitVersion = await version()
const [major, minor] = gitVersion.split('.').map(Number)
if (major >= 2 && minor >= 29) {
console.log('SHA-256 repositories are supported')
} else {
console.log('SHA-256 requires Git 2.29 or later')
}
The version function extracts the version number from the raw version string and caches the result.
Source Code
Location: src/lib/info/version.ts:9
Get the Git platform identifier (e.g., “windows”, “macos”, “linux”).
Syntax
function platform(): Promise<string | undefined>
Returns
platform
Promise<string | undefined>
A promise that resolves to the platform identifier, or undefined if not available.Example: "windows", "macos", or undefined for standard Linux builds
Usage Example
import { platform } from 'use-git'
const gitPlatform = await platform()
if (gitPlatform === 'windows') {
console.log('Running on Windows Git')
} else if (gitPlatform) {
console.log(`Running on ${gitPlatform} Git`)
} else {
console.log('Running on standard Git build')
}
import { platform } from 'use-git'
const gitPlatform = await platform()
const lineEnding = gitPlatform === 'windows' ? 'crlf' : 'lf'
console.log(`Recommended line ending: ${lineEnding}`)
The platform is extracted from the version string. Not all Git builds include platform information.
Source Code
Location: src/lib/info/platform.ts:9
isRepo
Check if the current directory (or configured working directory) is inside a Git repository.
Syntax
function isRepo(): Promise<boolean>
Returns
A promise that resolves to true if inside a Git repository working tree, false otherwise.
Usage Example
import { isRepo } from 'use-git'
if (await isRepo()) {
console.log('Currently in a Git repository')
} else {
console.log('Not in a Git repository')
}
Validation Before Operations
Ensure you’re in a repository before running Git commands:
import { isRepo, git } from 'use-git'
async function safeCommit(message: string) {
if (!await isRepo()) {
throw new Error('Not in a Git repository')
}
await git.commit(message)
}
This function uses git rev-parse --is-inside-work-tree internally and returns false if the command fails instead of throwing an error.
Source Code
Location: src/lib/rev-parse/isRepo.ts:6
isInitialized
Check if the current directory has a Git directory (.git folder or file).
Syntax
function isInitialized(): Promise<boolean>
Returns
A promise that resolves to true if a Git directory exists, false otherwise.
Usage Example
import { isInitialized, git } from 'use-git'
if (!await isInitialized()) {
console.log('Initializing repository...')
await git.init()
} else {
console.log('Repository already initialized')
}
Difference from isRepo
While isRepo checks if you’re inside a working tree, isInitialized checks if a .git directory exists:
import { isRepo, isInitialized } from 'use-git'
// Inside .git/ directory
await isInitialized() // true (git dir exists)
await isRepo() // false (not in working tree)
// Inside working tree
await isInitialized() // true (git dir exists)
await isRepo() // true (in working tree)
// Outside repository
await isInitialized() // false (no git dir)
await isRepo() // false (not in working tree)
Use isRepo to verify you’re in a working tree where files can be modified. Use isInitialized to check if Git is set up at all.
Source Code
Location: src/lib/rev-parse/isInitialized.ts:6
Combined Usage
Use multiple info functions together:
import { isGitInstalled, version, platform, rawVersion, isRepo, isInitialized } from 'use-git'
async function printGitInfo() {
if (!await isGitInstalled()) {
console.error('Git is not installed')
return
}
const raw = await rawVersion()
const ver = await version()
const plat = await platform()
const inRepo = await isRepo()
const initialized = await isInitialized()
console.log('Git Information:')
console.log(`- Raw: ${raw}`)
console.log(`- Version: ${ver}`)
console.log(`- Platform: ${plat || 'standard'}`)
console.log(`- In Repository: ${inRepo}`)
console.log(`- Initialized: ${initialized}`)
}
await printGitInfo()
Caching
All info functions use caching to improve performance:
import { version } from 'use-git'
// First call queries Git
const v1 = await version() // Executes git --version
// Subsequent calls return cached result
const v2 = await version() // Returns cached value
const v3 = await version() // Returns cached value
Version information is cached automatically, so you can call these functions frequently without performance concerns.
- createGit - Create a Git instance
- init - Initialize a repository
- clone - Clone a repository