git-utils
A few useful command to get git infos. Required node 10 or higher.
Prerequisites
The library is a wrapper around the git binary you have to install git before use this library.
Commands
Clone
Clone a remote repository
const { clone } = require('@ert78gb/git-utils')
// Equivalent git command
// git clone https://github.com/ert78gb/git-utils-test.git /Users/User/git/git-utils-test
await clone({
url: 'https://github.com/ert78gb/git-utils-test.git',
cwd: '/Users/User/git/git-utils-test', // where to clone
})Options
| parameter (type) | default value | description |
|---|---|---|
| url (string) | empty | HTTPS url of the remote repository |
| cwd (string) | inherited | Where to clone the remote repository. Inherited from the Node.js context |
Checkout Branch
Checkout existing branch.
const { checkoutBranch } = require('@ert78gb/git-utils')
// Equivalent git command
// git checkout <branch-name>
await checkoutBranch({
branchName: 'my-branch',
cwd: 'path of the git repo',
})Options
| parameter (type) | default value | description |
|---|---|---|
| branchName (string) | empty | Name of the branch that would like to checkout |
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Get Current Branch
Current branch name.
const { getCurrentBranchName } = require('@ert78gb/git-utils')
// Equivalent git command
// git rev-parse --abbrev-ref HEAD
const branch = await checkoutBranch({
cwd: 'path of the git repo',
})
console.log(branch) // my-branchOptions
| parameter (type) | default value | description |
|---|---|---|
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Get Current Sha
The current SHA1 hash.
const { getCurrentSha } = require('@ert78gb/git-utils')
// Equivalent git command
// git rev-parse HEAD
const sha = await getCurrentSha({
cwd: 'path of the git repo',
})
console.log(sha) // dd064f731ce78a1dd64c41781c8bb01cfda9a6d8Options
| parameter (type) | default value | description |
|---|---|---|
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Get File Changes
All commit info of a file path. The array is ordered by commit date in descending order.
const { getFileChanges } = require('@ert78gb/git-utils')
// Equivalent git command
// git log --follow --no-decorate --date=iso8601-strict -- file-path
const commitInfos = await getFileChanges({
cwd: 'path of the git repo',
path: 'folder/file.path'
})
console.log(commitInfos)
// [
// {
// sha: 'd3e89505291cb1d5881c6033d2ffd0abfc68fe10',
// author: 'Committer',
// date: 2021-02-08T16:19:42.000Z, // Commit date as Date
// message: 'fix: modify file'
// },
// {
// sha: '7f15cc49347592fbd60ea839f7e06be553965234',
// author: 'Committer',
// date: 2020-02-08T16:19:42.000Z, // Commit date as Date
// message: 'feat: create file'
// }
// ]Options
| parameter (type) | default value | description |
|---|---|---|
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
| path (string) | The path of the file from the repository root |
Get Commit Info
The latest commit info.
const { getCommitInfo } = require('@ert78gb/git-utils')
// Equivalent git command
// git rev-parse HEAD
const info = await getCommitInfo({
cwd: 'path of the git repo',
})
console.log(info)
// {
// sha: '7f15cc49347592fbd60ea839f7e06be553965234',
// author: 'Committer',
// date: 2020-02-08T16:19:42.000Z, // Commit date as Date
// message: 'feat: add b.txt\n\nBody of the comment'
// }Options
| parameter (type) | default value | description |
|---|---|---|
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Output
Array<{
sha:string,
author: string,
date: Date,
message: string
}>Get Parent SHA
Query the parent shas of the latest commit or the provided SHA. If a commit is a merge commit it has multiple parent
const { getParentShas } = require('@ert78gb/git-utils')
// Equivalent git command
// git log --pretty=%P -1 7f15cc49347592fbd60ea839f7e06be553965234
const shas = await getCommitInfo({
sha: '7f15cc49347592fbd60ea839f7e06be553965234',
cwd: 'path of the git repo',
})
console.log(shas) // ['cde7266d8004b1391ce033fd86f0ffe4a1ce1793']Options
| parameter (type) | default value | description |
|---|---|---|
| sha (string) | empty | SHA of the commit which parents you would like to get. You can use branch name too. |
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Get Merge base
Get the merge base of 2 sha or 2 branch
const { getMergeBase } = require('@ert78gb/git-utils')
// Equivalent git command
// git merge-base 7f15cc49347592fbd60ea839f7e06be553965234 cde7266d8004b1391ce033fd86f0ffe4a1ce1793
// git merge-base master feature-branch-name
const sha = await getMergeBase({
sha1: '7f15cc49347592fbd60ea839f7e06be553965234',
sha2: 'cde7266d8004b1391ce033fd86f0ffe4a1ce1793',
cwd: 'path of the git repo',
})
console.log(sha) // d3e89505291cb1d5881c6033d2ffd0abfc68fe10Options
| parameter (type) | default value | description |
|---|---|---|
| sha1 (string) | empty | SHA or branch name which part of the merge |
| sha2 (string) | sha of the latest commit | SHA or branch name which part of the merge. The default value is the latest commit in the current branch |
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Get Changed Files
Get the changed files of 2 sha or 2 commit
const { getChangedFiles } = require('@ert78gb/git-utils')
// Equivalent git command
// git diff --name-status 7f15cc49347592fbd60ea839f7e06be553965234 cde7266d8004b1391ce033fd86f0ffe4a1ce1793
// git dif --name-status master feature-branch-name
const changedFiles = await getChangedFiles({
sha1: '7f15cc49347592fbd60ea839f7e06be553965234',
sha2: 'cde7266d8004b1391ce033fd86f0ffe4a1ce1793',
cwd: 'path of the git repo',
})
console.log(changedFiles) // [ { action: 'added', path: 'b.txt' } ]Options
| parameter (type) | default value | description |
|---|---|---|
| sha1 (string) | empty | SHA or branch name which part of the diff |
| sha2 (string) | sha of the latest commit | SHA or branch name which diff. The default value is the latest commit in the current branch |
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Output
Array<{
action: string,
path: string
}>Values of the actions
- added
- modified
- deleted
Get Remote Tags
const { getRemoteTags } = require('@ert78gb/git-utils')
// Equivalent git command
// git ls-remote --tags https://github.com/ert78gb/git-utils-test.git org/feature/*
const tags = await getRemoteTags({
remote: 'https://github.com/ert78gb/git-utils-test.git',
prefix: 'org/feature/*',
})
console.log(tags) // Map { 'org/feature/v1.0.0' => 'cde7266d8004b1391ce033fd86f0ffe4a1ce1793', 'org/feature/v1.1.0' => '14630f2c65026f9bda22d6def4abd80ada6fcc6e' }Options
| parameter (type) | default value | description |
|---|---|---|
| remote (string) | 'origin' | URL of the remote git repo or alias remote of the local repo |
| prefix (string) | empty | return only tags that match this pattern. If the * missing from the end of the string it will exact match not just prefix |
| cwd (string) | inherited | Path of the git repository. Inherited from the Node.js context |
Output
Map<string, string> // the key and the value also string.
// The key is the tag name the value is the commit sha
![dependabot[bot]](https://avatars.githubusercontent.com/u/49699333?size=120)
