docs: Add more examples for toml tasks #3491

hverlin · 2024-12-12T04:48:16Z

No description provided.

jdx · 2024-12-12T10:25:25Z

docs/tasks/toml-tasks.md

@@ -143,10 +141,60 @@ run = 'echo {{flag(name=("myflag")}}'
 # runs: echo true
 ```

+```toml
+[tasks.maybeClean]
+run = """if [ '{{flag(name='clean')}}' = 'true' ]; then echo 'cleaning' ; fi""",


seems like a missed opportunity to show how multiline strings work in toml. The comma at the end is also a syntax error

jdx · 2024-12-12T10:27:47Z

docs/tasks/toml-tasks.md

+
+[tasks.download_task]
+description = "Shows that you can use deno in a task"
+shell = 'deno eval'


while this works, it can also be done with a shebang:

run = """ #!/usr/bin/env -S deno run --allow-env """

which I prefer even though users need to understand env -S (which I don't see as a downside, env -S is great). I think we should show both methods.

I don't know this for sure, but I suspect a shebang would also be easier for IDEs to syntax highlight, so I think that should be our preferred method here

I was thinking that this solution is more portable, maybe? Need to try on windows to see what happens.

I am not sure if it makes a diff for syntax highlighting for languages that don't have # comments

Ah wait, this is mise parsing the script actually, so it should work on window then.

mise/src/task/task_script_parser.rs

Lines 312 to 314 in d5781be

let shell_type: Option<ShellType> = shell_from_shebang(script)

.or(task.shell())

.unwrap_or(SETTINGS.default_inline_shell()?)[0]

I think that is only partially done, the shell_type there is only used for knowing whether or not it should escape args but I plan to soon make it actually parse and execute the shebang directly instead of going through sh -c. I would still document it this way, the windows issue I'll fix soon.

if only I knew the mise-vscode maintainer ;)

I do think syntax highlighting with shebangs would be a killer feature, or even if you got it to default to multiline strings as bash

btw we should add your extension to the docs

Sure, I will make a PR next week. Want to check the windows support first

might be worth waiting until I get the shebang parsing fully in place—right now it almost certainly will fail with any shebang—though a user could work around that with run_windows

jdx · 2024-12-12T12:25:45Z

docs/tasks/toml-tasks.md

+shell = 'deno eval' # or use a shebang: #!/usr/bin/env -S deno run
+run = """
+import ProgressBar from "jsr:@deno-library/progress";


sorry, this is what I meant

Suggested change

shell = 'deno eval' # or use a shebang: #!/usr/bin/env -S deno run

run = """

import ProgressBar from "jsr:@deno-library/progress";

run = """

#!/usr/bin/env -S deno run

import ProgressBar from "jsr:@deno-library/progress";

jdx · 2024-12-12T13:00:30Z

this is just a note, but there actually is a scenario where you may prefer shell = to the shebang, the shebang only works on a single run command, e.g.:

[tasks.foo]
run = [
"""
#!/usr/bin/env node
console.log("node")
""",
"""
#!/usr/bin/env bash
echo "foo"
""""

but of course shell would work on all of them. Why would someone want multiple run commands with different shells? no idea, but it's permitted.

I don't think it's worth documenting this

hverlin · 2024-12-12T13:16:55Z

Added a code group with various examples

jdx · 2024-12-12T13:20:46Z

docs/tasks/toml-tasks.md

+
+[tasks.python_task]
+run = """
+#!/usr/bin/env -S python


we should reserve env -S for shebangs that have multiple args (like deno run). We should also document on this page what the heck env -S does in a callout of some kind. I suspect most users won't have a clue what it means. I think I already do that in the tips and tricks doc but this page is going to be far more heavily trafficked.

Sounds good, I will update 👍

jdx · 2024-12-12T13:24:01Z

sorry for a bit of back and forth on this, but I think I know what I want to do in regards to documenting shell vs shebang. I think it's great to have multiple languages but I think for a few reasons shebangs should be the golden path. One is that it's more flexible, another is we should (at some point) get syntax highlighting for it, so I think we shouldn't document shell at all in the sort of introduction part of this.

What we do need on this page though is an exhaustive list of all the properties you can pass to tasks like we have for settings. That's where shell should go. That could be done here (even if it's just shell right now) or in a follow-up at some point.

jdx · 2024-12-12T13:26:44Z

the tricky thing about that list though is almost all properties are associated with file and toml tasks. So I'm not sure where it should live.

hverlin · 2024-12-12T13:28:34Z

I would document them in the toml task documentation. In the file task, given that there are a few examples already, we can just add a link indicating that the same properties are supported (https://mise.jdx.dev/tasks/file-tasks.html#arguments)

jdx · 2024-12-12T13:30:41Z

one more thing, I've been using """, but I think we actually want to use '''

jdx · 2024-12-12T13:33:16Z

oh whoops, seems I am not using sh -c when there is a shebang:

mise/src/cli/run.rs

Line 375 in 224a0b5

if script.starts_with("#!") {

I forgot about that. idk what this means for windows but it may work? probably not though

hverlin · 2024-12-12T15:41:41Z

Still had one commit to make 😅

syhol · 2024-12-13T12:40:03Z

docs/tasks/toml-tasks.md

+
+## quiet
+
+Set `quiet = false` to supress mise additional output.


@hverlin should this be quiet = true?

wait I think I missed this, we don't actually have this lol, this was a feature idea

maybe I'll just implement it so we don't need to remove it

fixed in #3514

yeah, this is why I was asking in the discord

Other fixes: #3501

hverlin and others added 3 commits December 11, 2024 21:47

docs: Add more examples for toml tasks

b4523cc

update

c70356d

[autofix.ci] apply automated fixes

1a2236b

jdx reviewed Dec 12, 2024

View reviewed changes

fix

4f72f90

jdx reviewed Dec 12, 2024

View reviewed changes

hverlin and others added 3 commits December 12, 2024 05:33

update

4402938

update

d3e43f7

[autofix.ci] apply automated fixes

3503311

code group

8b8e6ea

jdx reviewed Dec 12, 2024

View reviewed changes

hverlin and others added 2 commits December 12, 2024 07:37

wip

ac1d845

[autofix.ci] apply automated fixes

6685c06

jdx merged commit 8551448 into jdx:main Dec 12, 2024
19 checks passed

mise-en-dev mentioned this pull request Dec 12, 2024

chore: release 2024.12.8 #3498

Merged

hverlin mentioned this pull request Dec 12, 2024

docs: add explanation about shebang #3501

Merged

mise-en-dev mentioned this pull request Dec 12, 2024

mise 2024.12.8 Homebrew/homebrew-core#200999

Merged

syhol reviewed Dec 13, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add more examples for toml tasks #3491

docs: Add more examples for toml tasks #3491

hverlin commented Dec 12, 2024

jdx Dec 12, 2024

jdx Dec 12, 2024

jdx Dec 12, 2024

hverlin Dec 12, 2024

hverlin Dec 12, 2024

jdx Dec 12, 2024

jdx Dec 12, 2024

jdx Dec 12, 2024

jdx Dec 12, 2024

hverlin Dec 12, 2024

jdx Dec 12, 2024

jdx Dec 12, 2024

jdx commented Dec 12, 2024 •

edited

Loading

hverlin commented Dec 12, 2024 •

edited

Loading

jdx Dec 12, 2024

hverlin Dec 12, 2024

jdx commented Dec 12, 2024 •

edited

Loading

jdx commented Dec 12, 2024

hverlin commented Dec 12, 2024

jdx commented Dec 12, 2024

jdx commented Dec 12, 2024 •

edited

Loading

hverlin commented Dec 12, 2024

syhol Dec 13, 2024

jdx Dec 13, 2024 •

edited

Loading

jdx Dec 13, 2024

jdx Dec 13, 2024

hverlin Dec 13, 2024

hverlin Dec 13, 2024

	let shell_type: Option<ShellType> = shell_from_shebang(script)
	.or(task.shell())
	.unwrap_or(SETTINGS.default_inline_shell()?)[0]


		## quiet

		Set `quiet = false` to supress mise additional output.

docs: Add more examples for toml tasks #3491

docs: Add more examples for toml tasks #3491

Conversation

hverlin commented Dec 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdx commented Dec 12, 2024 • edited Loading

hverlin commented Dec 12, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdx commented Dec 12, 2024 • edited Loading

jdx commented Dec 12, 2024

hverlin commented Dec 12, 2024

jdx commented Dec 12, 2024

jdx commented Dec 12, 2024 • edited Loading

hverlin commented Dec 12, 2024

Choose a reason for hiding this comment

jdx Dec 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdx commented Dec 12, 2024 •

edited

Loading

hverlin commented Dec 12, 2024 •

edited

Loading

jdx commented Dec 12, 2024 •

edited

Loading

jdx commented Dec 12, 2024 •

edited

Loading

jdx Dec 13, 2024 •

edited

Loading