diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md index f8ebd2c0..5b714fa3 100644 --- a/docs/docs/changelog.md +++ b/docs/docs/changelog.md @@ -1,6 +1,6 @@ --- slug: /changelog/ -sidebar_position: 6 +sidebar_position: 7 --- # Changelog diff --git a/docs/docs/community.md b/docs/docs/community.md index 8435f81e..98739f21 100644 --- a/docs/docs/community.md +++ b/docs/docs/community.md @@ -1,6 +1,6 @@ --- slug: /community/ -sidebar_position: 6 +sidebar_position: 8 --- # Community diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index db9c9708..875992fd 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -1,6 +1,6 @@ --- slug: /contributing/ -sidebar_position: 7 +sidebar_position: 9 --- # Contributing diff --git a/docs/docs/donate.md b/docs/docs/donate.md index 9d098ded..b5ad5e2a 100644 --- a/docs/docs/donate.md +++ b/docs/docs/donate.md @@ -1,6 +1,6 @@ --- slug: /donate/ -sidebar_position: 10 +sidebar_position: 12 --- # Donate diff --git a/docs/docs/faq.md b/docs/docs/faq.md new file mode 100644 index 00000000..b9697587 --- /dev/null +++ b/docs/docs/faq.md @@ -0,0 +1,54 @@ +--- +slug: /faq/ +sidebar_position: 5 +--- + +# FAQ + +This page contains a list of frequently asked questions about Task. + +- [Why won't my task update my shell environment?](#why-wont-my-task-update-my-shell-environment) +- ['x' builtin command doesn't work on Windows](#x-builtin-command-doesnt-work-on-windows) + +## Why won't my task update my shell environment? + +This is a limitation of how shells work. Task runs as a subprocess of your +current shell, so it can't change the environment of the shell that started it. +This limitation is shared by other task runners and build tools too. + +A common way to work around this is to create a task that will generate output +that can be parsed by your shell. For example, to set an environment variable on +your shell you can write a task like this: + +```yaml +my-shell-env: + cmds: + - echo "export FOO=foo" + - echo "export BAR=bar" +``` + +Now run `eval $(task my-shell-env)` and the variables `$FOO` and `$BAR` will be +available in your shell. + +## 'x' builtin command doesn't work 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: + +- Use the `{{OS}}` function to run an OS-specific script. +- Use something like `{{if eq OS "windows"}}powershell {{end}}` 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] or [WSL]. + +We want to make improvements to this part of Task and the issues below track +this work. Constructive comments and contributions are very welcome! + +- [#197](https://github.com/go-task/task/issues/197) +- [mvdan/sh#93](https://github.com/mvdan/sh/issues/93) +- [mvdan/sh#97](https://github.com/mvdan/sh/issues/97) + +[Git Bash]: https://gitforwindows.org/ +[WSL]: https://learn.microsoft.com/en-us/windows/wsl/install diff --git a/docs/docs/releasing.md b/docs/docs/releasing.md index c5705d62..b1e81614 100644 --- a/docs/docs/releasing.md +++ b/docs/docs/releasing.md @@ -1,6 +1,6 @@ --- slug: /releasing/ -sidebar_position: 8 +sidebar_position: 10 --- # Releasing diff --git a/docs/docs/styleguide.md b/docs/docs/styleguide.md index 7da84bc3..808894e3 100644 --- a/docs/docs/styleguide.md +++ b/docs/docs/styleguide.md @@ -1,6 +1,6 @@ --- slug: /styleguide/ -sidebar_position: 5 +sidebar_position: 6 --- # Styleguide diff --git a/docs/docs/taskfile_versions.md b/docs/docs/taskfile_versions.md index 23a04f2e..bf5e34f9 100644 --- a/docs/docs/taskfile_versions.md +++ b/docs/docs/taskfile_versions.md @@ -1,6 +1,6 @@ --- slug: /taskfile-versions/ -sidebar_position: 9 +sidebar_position: 11 --- # Taskfile Versions