From 0edf69e8c8185ad805a26947366129ed5fa25767 Mon Sep 17 00:00:00 2001 From: arookieofc <2128194521@qq.com> Date: Sat, 6 Jun 2026 00:47:16 +0800 Subject: [PATCH] docs: clarify project scope --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++++ README.md | 15 +++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30951f1..0dd6ce3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,41 @@ Otherwise, you can of course always open an issue for us to look into. Please open a new issue for any feature requests you have in mind. Since most of the behavior comes from upstream (`deps/`), new features are usually best discussed (and landed) upstream first. +## Project scope + +This repository packages Unix-style command-line utilities for native Windows. +Most commands should come from one of the bundled upstream projects: + +* `deps/coreutils`: GNU coreutils-compatible utilities. +* `deps/findutils`: `find` and `xargs`. +* `deps/grep`: `grep`, `egrep`, and `fgrep`. + +We are not limited to GNU coreutils only. Small Windows-native commands can be +accepted when they make the Unix-like command set more useful on Windows. + +The usual bar is: + +* It has a close equivalent on Linux or macOS. +* That equivalent is commonly installed by default. +* People commonly use it in scripts or ordinary shell sessions. +* The Windows implementation is small enough to maintain here. +* Any Windows-specific behavior can be explained clearly. + +For example, a small command such as `which` may fit this repository. So may a +Windows backend for a command that already exists upstream but is currently +Unix-only. + +Commands are usually out of scope when they are not installed by default on +common Unix-like systems, are rarely used, depend on POSIX-only concepts that do +not translate to Windows, or require a large interactive terminal UI. `top`, for +example, is out of scope for now: it is mostly an interactive TUI, not a +scripting utility. + +When a utility already belongs to an upstream uutils project, prefer adding or +fixing the Windows backend upstream first. Code in this repository should be for +Windows-specific glue, packaging, the multi-call wrapper, or small native +commands that do not have a better upstream home. + ## Code changes This repository is a Microsoft-maintained Windows build of upstream coreutils. diff --git a/README.md b/README.md index d7241d5..0de4f9d 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@

Install · + Project scope + · Shell conflicts · Windows caveats @@ -26,6 +28,19 @@ Each command supports the standard `--help` flag for full syntax and options.
+## Project scope + +This project ships Unix-style command-line utilities for native Windows use, +mostly from `uutils/coreutils`, `uutils/findutils`, and `uutils/grep`. We may +also include small Windows-native commands when they match tools that are +commonly available by default on Linux or macOS and are useful in scripts or +normal shell use. Large interactive tools are out of scope for now. + +See [`CONTRIBUTING.md`](./CONTRIBUTING.md#project-scope) for the full scope +guidelines. + +
+ ## Install Install Coreutils for Windows with WinGet: