{"id":29639229,"url":"https://github.com/gapotchenko/gnu-tk","last_synced_at":"2026-01-20T17:32:54.090Z","repository":{"id":304679952,"uuid":"997403224","full_name":"gapotchenko/gnu-tk","owner":"gapotchenko","description":"A mutli-platform command-line utility that provides seamless access to GNU toolkits on non-GNU operating systems.","archived":false,"fork":false,"pushed_at":"2025-07-14T16:31:52.000Z","size":152,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-14T18:43:44.846Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gapotchenko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2025-06-06T13:20:43.000Z","updated_at":"2025-07-14T16:31:55.000Z","dependencies_parsed_at":"2025-07-14T18:43:54.121Z","dependency_job_id":"5a7c815f-8e44-4175-a499-dc276ac4515a","html_url":"https://github.com/gapotchenko/gnu-tk","commit_stats":null,"previous_names":["gapotchenko/gnu-tk"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/gapotchenko/gnu-tk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gapotchenko%2Fgnu-tk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gapotchenko%2Fgnu-tk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gapotchenko%2Fgnu-tk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gapotchenko%2Fgnu-tk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gapotchenko","download_url":"https://codeload.github.com/gapotchenko/gnu-tk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gapotchenko%2Fgnu-tk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266226784,"owners_count":23895710,"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":[],"created_at":"2025-07-21T20:37:18.898Z","updated_at":"2026-01-20T17:32:54.077Z","avatar_url":"https://github.com/gapotchenko.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GNU-TK\n\nGNU-TK is a tiny project that provides seamless scriptable access to GNU tools\non non-Unix operating systems.\n\n## Overview\n\n[GNU](https://www.gnu.org/software/) is a software system that has been\ndeveloped by many people working together for the sake of freedom of all\nsoftware users to control their computing.\n\nThe GNU system offers a wide range of tools, including essential command-line\nutilities such as `bash`, `cp`, `sed`, and many others. For instance, GNU\n[core utilities](https://www.gnu.org/software/coreutils/) are crucial for\nautomating cross-platform projects by enabling the creation of reproducible\nscripts. Beyond that, GNU tools support a wide variety of other use cases.\n\nA **recurring issue with GNU tools**, however, is their limited accessibility on\nnon-Unix operating systems. For example, on Windows, you can use toolkits such\nas [MSYS2](https://www.msys2.org/), [Cygwin](https://cygwin.com/) or\n[WSL](https://learn.microsoft.com/windows/wsl/ \"Windows Subsystem for Linux\").\nYet, they introduce their own challenges: correctly identifying the toolkit\ninstallation path, modifying environment variables, configuring shells with\ntoolkit-specific parameters, and, finally, managing the handoff of control to\nand from the toolkit. All of this makes using GNU tools far from easy and\nreproducible.\n\nGNU-TK project addresses these problems by providing a small `gnu-tk`\ncommand-line utility that acts as an automatic gateway to a GNU toolkit\ninstalled on the system. `gnu-tk` has a concise and stable command-line\ninterface making it suitable for effortless cross-platform scripting. In\naddition, it smoothes out the inconsistencies and shortcomings that typically\ncome with individual GNU toolkit distributions.\n\n## Usage\n\nThe basic usage example:\n\n```sh\ngnu-tk -l cp --help\n```\n\nThe command above invokes `cp` GNU utility with `--help` command-line option.\n\nYou can also pass a command to execute as a single command-line argument:\n\n```sh\ngnu-tk -c \"cp --help\"\n```\n\nOr as a script file:\n\n```sh\ngnu-tk -f \u003cscript-file\u003e\n```\n\n## Installation\n\nYou can install GNU-TK using one of the supported methods below.\n\n### Setup Packages\n\nSetup packages are standalone installers that let you install GNU-TK directly on\nyour system — no additional tools required.\n\n#### Windows\n\n- [GNU-TK Setup for Windows (x64)](https://download.gapotchenko.com/gnu-tk/latest/gnu-tk-setup-windows-x64.msi)\n- [GNU-TK Setup for Windows (ARM64)](https://download.gapotchenko.com/gnu-tk/latest/gnu-tk-setup-windows-arm64.msi)\n\n### Package Managers\n\n#### NPM\n\nNPM is a part of [Node.js](https://nodejs.org/). Use the following command to\ninstall GNU-TK globally:\n\n```sh\nnpm install -g @gapotchenko/gnu-tk\n```\n\nAlternatively, you can install GNU-TK locally within the Node.js project that\nuses it: `npm install --save-dev @gapotchenko/gnu-tk`.\n\n#### NuGet\n\nNuGet is a part of [.NET](https://dotnet.microsoft.com/). Use the following\ncommand to install GNU-TK as a global .NET tool:\n\n```sh\ndotnet tool install -g Gapotchenko.GnuTK\n```\n\n### Supported Platforms\n\nGNU-TK can be readily used on the following platforms:\n\n- Operating systems: Windows, macOS, Linux\n- CPU architectures: x64, ARM64\n\n### GNU Toolkits\n\nAside from GNU-TK utility itself, you may also need an actual GNU toolkit\ninstalled on your system:\n\n- **Windows:**\n  - [BusyBox](https://frippery.org/busybox/)\n  - [Cygwin](https://cygwin.com/)\n  - [Git](https://git-scm.com/downloads/win) (isn't a GNU toolkit by itself, but it conveniently includes a stripped-down immutable version of MSYS2)\n  - [MSYS2](https://www.msys2.org/) (recommended)\n  - [WSL](https://learn.microsoft.com/windows/wsl/ \"Windows Subsystem for Linux\")\n- **macOS:**\n  - [Homebrew](https://brew.sh/) package manager with installed GNU packages;\n    [`bash`](https://formulae.brew.sh/formula/bash) and\n    [`coreutils`](https://formulae.brew.sh/formula/coreutils) is a recommended\n    bare minimum\n  - OS includes a pre-installed GNU-like toolkit\n- **Linux:**\n  - [BusyBox](http://www.busybox.net/)\n  - OS includes a pre-installed GNU toolkit\n\n#### Built-in Toolkits\n\nThe following built-in toolkits are bundled with GNU-TK packages to guarantee\nthat GNU tools minimally work even when no specialized GNU toolkit is available:\n\n- **Windows:** [BusyBox](https://frippery.org/busybox/)\n\n## How it Works\n\nInternally, `gnu-tk` automatically finds and selects an appropriate GNU toolkit\ninstalled in the system, and then executes a specified command using it.\n\nTo list all available toolkits, you can use `gnu-tk list` command:\n\n```\nAvailable GNU Toolkits\n\nName               Description                Location\n------------------------------------------------------------------------------\nbusybox            BusyBox 1.38.0             (built-in)\ncygwin             Cygwin 3.6.2               C:\\cygwin64\ngit                Git 2.50.1                 C:\\Program Files\\Git\nmsys2-clang64      MSYS2 2025-02-21           C:\\msys64\nmsys2-clangarm64   MSYS2 2025-02-21           C:\\msys64\nmsys2-mingw32      MSYS2 2025-02-21           C:\\msys64\nmsys2-mingw64      MSYS2 2025-02-21           C:\\msys64\nmsys2-msys         MSYS2 2025-02-21           C:\\msys64\nmsys2-ucrt64       MSYS2 2025-02-21           C:\\msys64\nwsl                WSL 2.5.9.0                C:\\Program Files\\WSL\n\nTips:\n  - You can install a GNU toolkit to add it to the list:\n    https://gapt.ch/help/gnu-tk/install-toolkits\n  - You can use 'GNU_TK_TOOLKIT_PATH' environment variable to specify the\n    directory paths of portable GNU toolkits\n  - GNU toolkits supported on Windows: BusyBox, Cygwin, Git, MSYS2, WSL\n```\n\nTo simplify usage, GNU-TK automatically selects the most suitable GNU toolkit\nbased on common-sense factors. You can verify the GNU toolkit selection and\navailability using `gnu-tk check` command:\n\n```\nGNU Toolkit Check\n\nName: msys2-ucrt64\nDescription: MSYS2 2025-02-21\nLocation: C:\\msys64\nSemantics: GNU\nIsolation: none\n\nCheck status: PASS\n\nTips:\n  - To change the selected toolkit, specify '--toolkit' command-line option or\n    its shorthand '-t'\n  - Alternatively, you can set 'GNU_TK_TOOLKIT' environment variable to the\n    name of a GNU toolkit to use by default\n```\n\nYou can affect GNU toolkit selection during command invocation. For example, you\ncan pass `-s` (or `--strict`) command-line option to `gnu-tk`, indicating that a\ntoolkit with strict GNU semantics is required:\n\n```\ngnu-tk -s -l sed --help\n```\n\nThis can be vital on Unix operating systems like macOS that have built-in\nversions of Unix utilities. By specifying the `-s` command-line option, you\nexplicitly assert that only a GNU version of `sed` utility should be ever used.\nWithout that option, `gnu-tk` works in relaxed mode allowing built-in Unix OS\ncommands to work as close-enough substitutes when no corresponding GNU utilities\nare found.\n\n## Examples\n\nGNU-TK is an adaptable tool that can work with a variety of technologies. In\nthis section, we'll explore a few integration examples.\n\n### Node.js\n\nNode.js projects use a `package.json` file to define project configuration. One\nkey feature of this file is the ability to specify custom scripts, which can be\nexecuted using the `npm run \u003cscript\u003e` command.\n\nBy default, custom scripts defined in `package.json` are executed using the\ncommand shell of the host operating system. This is sufficient for basic tasks,\nbut more complex scenarios may require commands like `cp`, `mv`, `sed`, and\nothers. While some of these commands have OS-specific equivalents, relying on\nthem can reduce the portability of your project across different environments.\n\nIn that case, you can use `gnu-tk` to make your scripts provably portable across\ndifferent platforms. Let's examine a sample `package.json` file:\n\n```json\n{\n  \"scripts\": {\n    \"rebuild\": \"npm run clear \u0026\u0026 npm run build\",\n    \"build\": \"docusaurus build \u0026\u0026 gnu-tk -l rm -rf public \u0026\u0026 gnu-tk -l mkdir public \u0026\u0026 gnu-tk -l cp -r build public/content \u0026\u0026 gnu-tk -l mv public/content/_* public \u0026\u0026 gnu-tk -l mv public/content/*.txt public \u0026\u0026 gnu-tk -s -l sed -i public/content/sitemap.xml -f src/patches/sitemap.xml.sed\",\n    \"clear\": \"docusaurus clear \u0026\u0026 gnu-tk -l rm -rf public\"\n  }\n}\n```\n\nNote how the `gnu-tk` tool is used in the script definitions. In this mode, you\ncan seamlessly switch between native shell commands and GNU tools as needed.\n\nFor this to work, `gnu-tk` must be installed either [globally](#installation),\nor locally within the Node.js project that uses `gnu-tk`:\n\n```sh\nnpm install --save-dev @gapotchenko/gnu-tk\n```\n\n### Just\n\n[`just`](https://github.com/casey/just) is a cross-platform script runner.\n\nBy default, `just` executes scripts using the command shell of the host\noperating system. This approach works well for trivial cases but falls apart on\nmore complex scenarios. Let's examine a sample `justfile`:\n\n```just\nrun:\n    echo Just hello\n    cp --help\n```\n\nIf you try to run this script with `just run` command on a Unix system, you will\nget the expected correct result. On Windows, you'll encounter an error because\nthe `cp` command is not available on this OS.\n\nOne way to solve that problem is to use `gnu-tk` in place:\n\n```just\nset windows-shell := [\"cmd\", \"/c\"]\n\nrun:\n    echo Just hello\n    gnu-tk -l cp --help\n```\n\nThis gives us the desired result.\n\nWhile the above approach works, repeatedly invoking `gnu-tk` can become tedious.\nTo simplify things, we can configure `gnu-tk` as the default command shell for\n`justfile`:\n\n```just\nset windows-shell := [\"gnu-tk\", \"-i\", \"-c\"]\n\nrun:\n    echo Just hello\n    cp --help\n```\n\nNow, `just run` command will produce the correct results on all supported\nplatforms.\n\nSetting `windows-shell` to `gnu-tk` for an entire `justfile` can sometimes be\ntoo aggressive. In such cases, a more gradual approach using the `[script]`\nattribute may be preferable\n([docs](https://just.systems/man/en/script-recipes.html)):\n\n```just\nset windows-shell := [\"cmd\", \"/c\"]\nset script-interpreter := [\"gnu-tk\", \"-i\", \"-l\", \"/bin/sh\", \"-eu\"]\n\n[script]\nrun:\n    echo Just hello\n    cp --help\n```\n\nAnd if you would like to write your cross-platform `just` recipes in another\nlanguage – say, Python:\n\n```just\n[script(\"gnu-tk\", \"-i\", \"-l\", \"/usr/bin/env\", \"python3\")]\nrun:\n    print(\"Hello from Python script\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgapotchenko%2Fgnu-tk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgapotchenko%2Fgnu-tk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgapotchenko%2Fgnu-tk/lists"}