Git-Date-Extractor NPM Package and CLI Tool

  • report
    Click for Disclaimer
    This Project is over a year old (first published about 4 years ago). As such, please keep in mind that some of the information may no longer be accurate, best practice, or a reflection of how I would approach the same thing today.
  • infoFull Project Details
    info_outlineClick for Full Project Details
    Date Posted:
    Sep. 20, 2019
    Last Updated:
    Sep. 20, 2019
  • classTags
    classClick for Tags

Github and NPM:

Github repo:

NPM link:

About this project:

In general, OS timestamps for files, such as when a file was created or last modified, are problematic for developers. They can be unreliable, ambiguous, and are not exactly portable between systems. For example, in many versions of Linux, trying to get the “birthtime” of a file, or when it was created, gives an empty result. Another wrinkle to this issue is that OS timestamps are not tracked as part of Git – so if you clone a repo, all the files that are created will have timestamps that point to the time of cloning, regardless of when the files were actually last modified.

I built this tool because I needed a solution for retrieving and storing file timestamps, and I realized that although Git does not store timestamps directly on files, they could be pulled programmatically by scraping the Git history of a file and seeing when it was created or modified as part of commits. That is what this tool does; you can give it a list of files (or a directory) and it will use Git as the preferred method for generating timestamps. It can even save the results as a JSON file with the filepaths as keys; this makes it a great alternative solution for storing file modification dates in a system like Gatsby, which has no traditional database for storing that kind of metadata. In fact, I myself use this solution for my own Gatsby site, which is discussed in this post.


Git-Date-Extractor - Advanced Demo

Tech stack:

  • NodeJS
  • Javascript + TypeScript annotations with JSDoc
  • Initial structure was scaffolded from Yeoman generator-nm
  • Uses Meow for CLI parsing
  • Unit and integration tests use Ava
  • Code coverage analysis with Istanbul JS / NYC
  • Automated build CI testing with Travis CI
  • XO for linting


Make sure to checkout the Github repo for the current up-to-date readme, but I’ll list some key features below as well:

  • Usable from both CLI and JS
  • Very configurable (filter results by filename, directory)
  • Get output in console or save as JSON file
  • Creation timestamps are cached once generated, if using JSON file
  • Automatic re-staging of JSON file if calling script with githook option
  • … and more!

Leave a Reply

Your email address will not be published.