From fd83414074b7521f542cd09ac28820c6a7c14293 Mon Sep 17 00:00:00 2001
From: Andrey Nering <andreynering@users.noreply.github.com>
Date: Tue, 26 Aug 2025 22:16:52 -0300
Subject: [PATCH] docs: update docs and faq to mention the new core utils

---
 website/src/docs/faq.md                   | 49 ++++++++++++++---------
 website/src/docs/reference/environment.md |  8 ++++
 2 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/website/src/docs/faq.md b/website/src/docs/faq.md
index d957a8b3..1efdbda7 100644
--- a/website/src/docs/faq.md
+++ b/website/src/docs/faq.md
@@ -97,26 +97,39 @@ a=foo
 echo $a
 ```
 
-## 'x' builtin command doesn't work on Windows
+## Are shell core utilities available on Windows?
 
-The default shell on Windows (`cmd` and `powershell`) do not have commands like
-`rm` and `cp` available as builtins. This means that these commands won't work.
-If you want to make your Taskfile fully cross-platform, you'll need to work
-around this limitation using one of the following methods:
+The most common ones, yes. And we might add more in the future.
+This is possible because Task compiles a small set of core utilities in Go and
+enables them by default on Windows for greater compatibility.
 
-- Use the <span v-pre>`{{OS}}`</span> function to run an OS-specific script.
-- Use something like
-  <span v-pre>`{{if eq OS "windows"}}powershell {{end}}<my_cmd>`</span> to
-  detect windows and run the command in Powershell directly.
-- Use a shell on Windows that supports these commands as builtins, such as [Git
-  Bash][git-bash] or [WSL][wsl].
+It's possible to control whether these builtin core utilities are used or not
+with the [`TASK_CORE_UTILS`](/docs/reference/environment#task-core-utils)
+environment variable:
 
-We want to make improvements to this part of Task and the issues below track
-this work. Constructive comments and contributions are very welcome!
+```bash
+# Enable, even on non-Windows platforms
+env TASK_CORE_UTILS=1 task ...
 
-- #197
-- [mvdan/sh#93](https://github.com/mvdan/sh/issues/93)
-- [mvdan/sh#97](https://github.com/mvdan/sh/issues/97)
+# Disable, even on Windows
+env TASK_CORE_UTILS=0 task ...
+```
 
-[git-bash]: https://gitforwindows.org/
-[wsl]: https://learn.microsoft.com/en-us/windows/wsl/install
+This is the list of core utils that are currently available:
+
+* `base64`
+* `cat`
+* `chmod`
+* `cp`
+* `find`
+* `gzip`
+* `ls`
+* `mkdir`
+* `mktemp`
+* `mv`
+* `rm`
+* `shasum`
+* `tar`
+* `touch`
+* `xargs`
+* (more might be added in the future)
diff --git a/website/src/docs/reference/environment.md b/website/src/docs/reference/environment.md
index 3ff5ac6d..8c4d3b2d 100644
--- a/website/src/docs/reference/environment.md
+++ b/website/src/docs/reference/environment.md
@@ -26,6 +26,14 @@ checksums and temporary metadata. Can be relative like `tmp/task` or absolute
 like `/tmp/.task` or `~/.task`. Relative paths are relative to the root
 Taskfile, not the working directory. Defaults to: `./.task`.
 
+### `TASK_CORE_UTILS`
+
+This env controls whether the Bash interpreter will use its own
+core utilities implemented in Go, or the ones available in the system.
+Valid values are `true` (`1`) or `false` (`0`). By default, this is `true` on
+Windows and `false` on other operating systems. We might consider making this
+enabled by default on all platforms in the future.
+
 ### `TASK_REMOTE_DIR`
 
 Defines the location of Task's remote temporary directory which is used for