{"id":16330344,"url":"https://github.com/nixinova/linguistjs","last_synced_at":"2025-06-16T05:36:12.606Z","repository":{"id":40388230,"uuid":"374022793","full_name":"Nixinova/LinguistJS","owner":"Nixinova","description":"Analyse and list all languages used in a folder. Implementation of and powered by GitHub's Linguist.","archived":false,"fork":false,"pushed_at":"2025-04-26T08:48:40.000Z","size":248,"stargazers_count":41,"open_issues_count":2,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-31T22:05:15.622Z","etag":null,"topics":["analyzer","cli","detect-language","folder-analyzer","github-linguist","language-analysis","language-detection","language-detector","language-statistics","languages","linguist","nixinova","programming-languages"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nixinova.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-05T04:49:42.000Z","updated_at":"2025-04-26T08:47:48.000Z","dependencies_parsed_at":"2024-03-08T10:42:49.983Z","dependency_job_id":"a84b2e37-b641-435f-ba54-3a109b773501","html_url":"https://github.com/Nixinova/LinguistJS","commit_stats":{"total_commits":140,"total_committers":2,"mean_commits":70.0,"dds":0.06428571428571428,"last_synced_commit":"09f99b1993ed95b5bdb6ccb5200c70545c587998"},"previous_names":["nixinova/linguist"],"tags_count":67,"template":false,"template_full_name":null,"purl":"pkg:github/Nixinova/LinguistJS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixinova%2FLinguistJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixinova%2FLinguistJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixinova%2FLinguistJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixinova%2FLinguistJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nixinova","download_url":"https://codeload.github.com/Nixinova/LinguistJS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixinova%2FLinguistJS/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260106713,"owners_count":22959714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analyzer","cli","detect-language","folder-analyzer","github-linguist","language-analysis","language-detection","language-detector","language-statistics","languages","linguist","nixinova","programming-languages"],"created_at":"2024-10-10T23:19:01.864Z","updated_at":"2025-06-16T05:36:12.558Z","avatar_url":"https://github.com/Nixinova.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Latest version](https://img.shields.io/github/v/release/Nixinova/Linguist?label=latest%20version\u0026style=flat-square)](https://github.com/Nixinova/Linguist/releases)\n[![Last updated](https://img.shields.io/github/release-date/Nixinova/Linguist?label=updated\u0026style=flat-square)](https://github.com/Nixinova/Linguist/releases)\n[![npm downloads](https://img.shields.io/npm/dt/linguist-js?logo=npm)](https://www.npmjs.com/package/linguist-js)\n\n# LinguistJS\n\nAnalyses the languages of all files in a given folder or folders and collates the results.\n\nPowered by [github-linguist](https://github.com/github/linguist), although it doesn't need to be installed.\n\n## Install\n\n[Node.js](https://nodejs.org) must be installed to be able to use LinguistJS.\n\nLinguistJS is available [on npm](https://npmjs.com/package/linguist-js) as `linguist-js`.\n\nInstall locally using `npm install linguist-js` and import it into your code like so:\n\n```js\nconst linguist = require('linguist-js');\n```\n\nOr install globally using `npm install -g linguist-js` and run using the CLI command `linguist` or `linguist-js`.\n\n```\nlinguist --help\nlinguist-js --help\n```\n\n## Usage\n\nLinguistJS contains one function which analyses a given folder or folders.\n\nAs an example, take the following file structure:\n\n```\n/\n| src\n| | cli.js 1kB\n| | index.ts 2kB\n| readme.md 3kB\n| no-lang 10B\n| x.pluginspec 10B\n```\n\nRunning LinguistJS on this folder will return the following JSON:\n\n```json\n{\n  \"files\": {\n    \"count\": 5,\n    \"bytes\": 6020,\n    \"lines\": {\n        \"total\": 100,\n        \"content\": 90,\n        \"code\": 80,\n    },\n    \"results\": {\n      \"/src/index.ts\": \"TypeScript\",\n      \"/src/cli.js\": \"JavaScript\",\n      \"/readme.md\": \"Markdown\",\n      \"/no-lang\": null,\n      \"/x.pluginspec\": \"Ruby\",\n    },\n    \"alternatives\": {\n        \"/x.pluginspec\": [\"XML\"],\n    },\n  },\n  \"languages\": {\n    \"count\": 3,\n    \"bytes\": 6010,\n    \"lines\": {\n        \"total\": 90,\n        \"content\": 80,\n        \"code\": 70,\n    },\n    \"results\": {\n       \"JavaScript\": {\n            \"type\": \"programming\",\n            \"bytes\": 1000,\n            \"lines\": { \"total\": 49, \"content\": 49, \"code\": 44 },\n            \"color\": \"#f1e05a\"\n        },\n        \"Markdown\": {\n            \"type\": \"prose\",\n            \"bytes\": 3000,\n            \"lines\": { \"total\": 10, \"content\": 5, \"code\": 5 },\n            \"color\": \"#083fa1\"\n        },\n        \"Ruby\": {\n            \"type\": \"programming\",\n            \"bytes\": 10,\n            \"lines\": { \"total\": 1, \"content\": 1, \"code\": 1 },\n            \"color\": \"#701516\"\n        },\n        \"TypeScript\": {\n            \"type\": \"programming\",\n            \"bytes\": 2000,\n            \"lines\": { \"total\": 30, \"content\": 25, \"code\": 20 },\n            \"color\": \"#2b7489\"\n        },\n    },\n  },\n  \"unknown\": {\n    \"count\": 1,\n    \"bytes\": 10,\n    \"lines\": {\n        \"total\": 10,\n        \"content\": 10,\n        \"code\": 10,\n    },\n    \"filenames\": {\n      \"no-lang\": 10,\n    },\n    \"extensions\": {},\n  },\n}\n```\n\n### Notes\n\n- File paths in the output use only forward slashes as delimiters, even on Windows.\n- Unless running in offline mode, do not rely on any language classification output from LinguistJS being unchanged between runs.\n  Language data is fetched each run from the latest classifications of [`github-linguist`](https://github.com/github/linguist).\n  This data is subject to change at any time and may change the results of a run even when using the same version of Linguist.\n\n## API\n\n### Node\n\n```js\nconst linguist = require('linguist-js');\n\n// Analyse folder on disc\nconst folder = './src';\nconst options = { keepVendored: false, quick: false };\nconst { files, languages, unknown } = await linguist(folder, options);\n\n// Analyse file content from raw input\nconst fileNames = ['file1.ts', 'file2.ts', 'ignoreme.js'];\nconst fileContent = ['#!/usr/bin/env node', 'console.log(\"Example\");', '\"ignored\"'];\nconst options = { ignoredFiles: ['ignore*'] };\nconst { files, languages, unknown } = await linguist(fileNames, { fileContent, ...options });\n```\n\n- `linguist(entry?, opts?)` (default export):\n  Analyse the language of all files found in a folder or folders.\n  - `entry` (optional; string or string array):\n    The folder(s) to analyse (defaults to `./`).\n  - `opts` (optional; object):\n    An object containing analyser options.\n    - `fileContent` (string or string array):\n      Provides the file content associated with the file name(s) given as `entry` to analyse instead of reading from a folder on disk.\n    - `ignoredFiles` (string array):\n      A list of file path globs to explicitly ignore.\n    - `ignoredLanguages` (string array):\n      A list of languages to ignore.\n    - `categories` (string array):\n      A list of programming language categories that should be included in the results.\n      Defaults to `['data', 'markup', 'programming', 'prose']`.\n    - `childLanguages` (boolean):\n      Whether to display sub-languages instead of their parents when possible (defaults to `false`).\n    - `quick` (boolean):\n      Whether to skip complex language analysis such as the checking of heuristics and gitattributes statements (defaults to `false`).\n      Alias for `checkAttributes:false, checkIgnored:false, checkDetected:false, checkHeuristics:false, checkShebang:false, checkModeline:false`.\n    - `offline` (boolean):\n      Whether to use pre-packaged metadata files instead of fetching them from GitHub at runtime (defaults to `false`).\n    - `calculateLines` (boolean):\n      Whether to calculate line of code totals (defaults to `true`).\n    - `keepVendored` (boolean):\n      Whether to keep vendored files (dependencies, etc) (defaults to `false`).\n      Does nothing when `fileContent` is set.\n    - `keepBinary` (boolean):\n      Whether binary files should be included in the output (defaults to `false`).\n    - `relativePaths` (boolean):\n      Change the absolute file paths in the output to be relative to the current working directory (defaults to `false`).\n    - `checkAttributes` (boolean):\n      Force the checking of `.gitattributes` files (defaults to `true` unless `quick` is set).\n      Does nothing when `fileContent` is set.\n    - `checkIgnored` (boolean):\n      Force the checking of `.gitignore` files (defaults to `true` unless `quick` is set).\n      Does nothing when `fileContent` is set.\n    - `checkDetected` (boolean):\n      Force files marked with `linguist-detectable` to show up in the output, even if the file is not part of the declared `categories`.\n    - `checkHeuristics` (boolean):\n      Apply heuristics to ambiguous languages (defaults to `true` unless `quick` is set).\n    - `checkShebang` (boolean):\n      Check shebang (`#!`) lines for explicit language classification (defaults to `true` unless `quick` is set).\n    - `checkModeline` (boolean):\n      Check modelines for explicit language classification (defaults to `true` unless `quick` is set).\n\n### Command-line\n\n```\nlinguist --analyze [\u003cfolders...\u003e] [\u003coptions...\u003e]\nlinguist --help\nlinguist --version\n```\n\n- `--analyze`:\n  Analyse the language of all files found in a folder or folders.\n  - `[\u003cfolders...\u003e]`:\n    The folders to analyse (defaults to `./`).\n  - `--ignoredFiles \u003cglobs...\u003e`:\n    A list of file path globs to ignore.\n  - `--ignoredLanguages \u003clanguages...\u003e`:\n    A list of languages to exclude from the output.\n  - `--categories \u003ccategories...\u003e`:\n    A list of language categories that should be displayed in the output.\n    Must be one or more of `data`, `prose`, `programming`, `markup`.\n  - `--childLanguages`:\n    Display sub-languages instead of their parents, when possible.\n  - `--json`:\n    Only affects the CLI output.\n    Display the outputted language data as JSON.\n  - `--tree \u003ctraversal\u003e`:\n    Only affects the CLI output.\n    A dot-delimited traversal to the nested object that should be logged to the console instead of the entire output.\n    Requires `--json` to be specified.\n  - `--listFiles`:\n    Only affects the visual CLI output.\n    List each matching file and its size under each outputted language result.\n    Does nothing if `--json` is specified.\n  - `--quick`:\n    Skip the checking of `.gitattributes` and `.gitignore` files for manual language classifications.\n    Alias for `--checkAttributes=false --checkIgnored=false --checkHeuristics=false --checkShebang=false --checkModeline=false`.\n  - `--offline`:\n    Use pre-packaged metadata files instead of fetching them from GitHub at runtime.\n  - `--calculateLines`:\n    Calculate line of code totals from files.\n  - `--keepVendored`:\n    Include vendored files (auto-generated files, dependencies folder, etc) in the output.\n  - `--keepBinary`:\n    Include binary files in the output.\n  - `--relativePaths`:\n    Change the absolute file paths in the output to be relative to the current working directory.\n  - `--checkAttributes`:\n    Force the checking of `.gitatributes` files.\n    Use alongside `--quick` to override it disabling this option.\n  - `--checkIgnored`:\n    Force the checking of `.gitignore` files.\n    Use alongside `--quick` to override it disabling this option.\n  - `--checkDetected`:\n    Force files marked with `linguist-detectable` to show up in the output, even if the file is not part of the declared `--categories`.\n    Use alongside `--quick` to override it disabling this option.\n  - `--checkHeuristics`:\n    Apply heuristics to ambiguous languages.\n    Use alongside `--quick` to override it disabling this option.\n  - `--checkShebang`:\n    Check shebang (`#!`) lines for explicit classification.\n    Use alongside `--quick` to override it disabling this option.\n  - `--checkModeline`:\n    Check modelines for explicit classification.\n    Use alongside `--quick` to override it disabling this option.\n- `--help`:\n  Display the help message.\n- `--version`:\n  Display the current installed version of LinguistJS.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnixinova%2Flinguistjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnixinova%2Flinguistjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnixinova%2Flinguistjs/lists"}