Necessitates Proper Modularity

    gitlog
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.4 • Public • Published

    node-gitlog

    Git log parser for Node.JS

    build status dependency status

    Installation

    npm install gitlog --save

    Usage

    const gitlog = require("gitlog").default;
    
    const options = {
      repo: __dirname + "/test-repo-folder",
      number: 20,
      author: "Dom Harrington",
      fields: ["hash", "abbrevHash", "subject", "authorName", "authorDateRel"],
      execOptions: { maxBuffer: 1000 * 1024 },
    };
    
    // Synchronous
    const commits = gitlog(options);
    console.log(commits);
    
    // Asynchronous (with Callback)
    gitlog(options, function (error, commits) {
      // Commits is an array of commits in the repo
      console.log(commits);
    });
    
    const { gitlogPromise } = require("gitlog");
    
    // Asynchronous (with Promise)
    gitlogPromise(options)
      .then((commits) => console.log(commits))
      .catch((err) => console.log(err));

    gitlog comes with full typescript support!

    import gitlog, { GitlogOptions } from "gitlog";
    
    // Option 1: Just use the function, returned commit type has specified fields
    gitlog({
      repo: "foo",
      fields: ["subject", "authorName", "authorDate"],
    });
    
    // Option 2: Use Options type to create options
    const options: GitlogOptions<"subject" | "authorName" | "authorDate"> = {
      repo: "foo",
      fields: ["subject", "authorName", "authorDate"],
    };
    
    gitlog(options);
    
    // Option 3: Typescript Magic
    const options = {
      repo: "foo",
      fields: ["subject", "authorName", "authorDate"] as const,
    };
    
    gitlog(options);
    
    // NOT SUPPORTED: Without "as const" gitlog can't create a good return type
    const options = {
      repo: "foo",
      fields: ["subject", "authorName", "authorDate"],
    };
    
    gitlog(options);

    Options

    See git log

    repo

    The location of the repo, required field.

    number

    The number of commits to return, defaults to 10.

    since/after

    Show commits more recent than a specific date.

    until/before

    Show commits older than a specific date.

    author/committer

    Limit the commits output to ones with author/committer header lines that match the specified pattern.

    nameStatus

    Below fields was returned from the log:

    • files - changed files names (array)
    • status - changed files status (array)

    This option is enabled by default.

    findCopiesHarder

    Much more likely to set status codes to 'C' if files are exact copies of each other.

    This option is disabled by default.

    includeMergeCommitFiles

    Pass the -m option to includes files in a merge commit.

    This option is disabled by default.

    all

    Find commits on all branches instead of just on the current one.

    This option is disabled by default.

    branch (revision range)

    Show only commits in the specified branch or revision range.

    By default uses the current branch and defaults to HEAD (i.e. the whole history leading to the current commit).

    fileLineRange

    Optional field for getting only the commits that affected a specific line range of a given file.

    file

    Optional file filter for the git log command

    execOptions

    Type: Object

    Specify some options to be passed to the .exec() method:

    • cwd String Current working directory of the child process
    • env Object Environment key-value pairs
    • setsid Boolean
    • encoding String (Default: 'utf8')
    • timeout Number (Default: 0)
    • maxBuffer Number (Default: 200*1024)
    • killSignal String (Default: 'SIGTERM')

    optional fields

    An array of fields to return from the log, here are the possible options:

    • hash - the long hash of the commit e.g. 7dd0b07625203f69cd55d779d873f1adcffaa84a
    • abbrevHash - the abbreviated commit hash e.g. 7dd0b07
    • treeHash - the tree hash of the commit
    • abbrevTreeHash - the abbreviated commit hash
    • parentHashes - the parent hashes
    • abbrevParentHashes - the abbreviated parent hashes
    • authorName - author name of the commit
    • authorEmail - author email of the commit
    • authorDate - author date of the commit
    • authorDateRel - relative author date of the commit
    • committerName - committer name
    • committerEmail - committer email
    • committerDate - committer date
    • committerDateRel - relative committer date
    • subject - commit message (first line)
    • body - commit body
    • rawBody - raw body (subject + body)

    Defaults to 'abbrevHash', 'hash', 'subject' and 'authorName'.

    How it works

    This module works by executing a child process (using child_process.exec()) to the git executable, then parsing the stdout into commits. This is done using the --pretty command line option which allows you to provide a custom formatter to git log. To enable easy parsing the format is delimited by a tab (\t) character.

    Example

    The following is an example of what a parsed commit might look like.

    {
      "hash": "6a7ef5e3b3d9c77743140443c8f9e792b0715721",
      "abbrevHash": "6a7ef5e",
      "treeHash": "f1bf51b15b48a00c33727f364afef695029864c0",
      "abbrevTreeHash": "f1bf51b",
      "parentHashes": "cfe06dbdb8d0a193640977e016a04678f8f3b04f",
      "abbrevParentHashes": "cfe06dbdb8d0a193640977e016a04678f8f3b04f",
      "authorName": "Dom Harrington",
      "authorEmail": "dom@harringtonxxxxx",
      "authorDate": "2015-04-09 09:39:23 +0100",
      "authorDateRel": "6 days ago",
      "committerName": "Dom Harrington",
      "committerEmail": "dom@harringtonxxxxx",
      "committerDate": "Thu Apr 9 09:39:23 2015 +0100",
      "committerDateRel": "6 days ago",
      "subject": "1.0.0",
      "status": ["M"],
      "files": ["package.json"]
    }

    Contributors

    Thanks goes to these wonderful people (emoji key):


    domharrington

    💻 📖 💡 🤔

    Andrew Lisowski

    💻 📖 🚇 🚧

    Stefan Oderbolz

    🐛 💻

    palortoff

    🐛 💻

    Malys

    🐛 💻 📖

    Mike Mellor

    💻

    Hunter Medney

    💻

    Peter Baranyi

    💻 🐛

    Benjamin Blackwood

    📖

    Ash Summers

    💻 ⚠️

    007design

    💻

    tobaccoplaybook

    💻

    Nicola

    💻

    bluelovers

    💻

    Marwan Butrous

    💻

    FishOrBear

    💻

    Asjid Kalam

    💻

    Jamie Slome

    💻

    huntr-helper

    💻

    Chris NeJame

    📖 ⚠️ 💻

    Ron

    ⚠️ 💻

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Keywords

    Install

    npm i gitlog

    DownloadsWeekly Downloads

    28,233

    Version

    4.0.4

    License

    BSD-3-Clause

    Unpacked Size

    125 kB

    Total Files

    22

    Last publish

    Collaborators

    • domharrington
    • alisowski