Add docs for jobs by cosineblast · Pull Request #1826 · nushell/nushell.github.io

cosineblast · 2025-03-03T19:31:19Z

This adds a book entry for background job handling in nushell, with regard to how it is currently implemented.

Quick question: How do I generate the .md files for new commands such as job spawn?

fdncred · 2025-03-03T20:01:34Z

Quick question: How do I generate the .md files for new commands such as job spawn?

You don't need to do that. @hustcer generates all the commands shortly after each release.

132ikl · 2025-03-04T03:12:35Z

i'll take a look when i get the chance

132ikl

thanks for writing this up! sorry I just got around to this, I completely forgot about this one 😅

i have a few suggestions, let me know what you think

132ikl · 2025-03-20T02:06:33Z


-1. Using a third-party task management tools, like [pueue](https://github.com/Nukesor/pueue)
-2. Using a terminal multiplexer, like [tmux](https://github.com/tmux/tmux/wiki) or [zellij](https://zellij.dev/)
+Nushell currently presents experimental support for thread-based background jobs.


could you move this line to above the "Spawning Jobs" header?

also, nitpick, but not sure about "presents" here, I think just "has" works fine

132ikl · 2025-03-20T02:10:15Z

+::: tip Note
+Unlike many other shells, Nushell jobs are **not** separate processes, and are instead implemented
+as background threads. An important side effect of that, is that all background jobs terminate once the shell process exits.
+:::


could you expand this into a proper (but brief) section? things I think we should specifically cover:

interactive vs. non-interactive job killing behavior on Nushell exit

explain that this is the rationale behind no disown / eventually job dispatch

132ikl · 2025-03-20T02:12:08Z


-## Using Nu With Terminal Multiplexer
+Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing.
+Jobs can also be kiled/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:


Suggested change

Jobs can also be kiled/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:

Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:

132ikl · 2025-03-20T02:33:12Z

+## Unix Ctrl-Z
+
+In unix targets (namely Linux and MacOS), Nushell's background job support also integrates with the Ctrl-Z feature
+of terminals (more specifically, the `SIGTSTP` signal), which allows users to suspend foreground processes into background jobs.
+When a running process is suspended, it is turned into a background job of type `frozen`. A frozen job can be reanimated into foreground with the
+[`job unfreeze`](/commands/docs/job_unfreeze.md) command.
+
+```
+long_running_process
+# (Ctrl-Z is pressed)
+
+job list
+# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
+# => ┃ # ┃ id ┃  type  ┃      pids      ┃
+# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
+# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
+# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+
+job unfreeze 1
+# (process is brought back where it stopped)
+```
+
+If no job id is provided to `job unfreeze`, it will unfreeze the job id of the most recently frozen job.
+Therefore, one can use `alias fg = job unfreeze` to achieve a behavior similar to the one of existing unix shells.


Suggested change

## Unix Ctrl-Z

In unix targets (namely Linux and MacOS), Nushell's background job support also integrates with the Ctrl-Z feature

of terminals (more specifically, the `SIGTSTP` signal), which allows users to suspend foreground processes into background jobs.

When a running process is suspended, it is turned into a background job of type `frozen`. A frozen job can be reanimated into foreground with the

[`job unfreeze`](/commands/docs/job_unfreeze.md) command.

```

long_running_process

# (Ctrl-Z is pressed)

job list

# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓

# => ┃ # ┃ id ┃ type ┃ pids ┃

# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫

# => ┃ 0 ┃ 1 ┃ frozen ┃ [list 1 items] ┃

# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛

job unfreeze 1

# (process is brought back where it stopped)

```

If no job id is provided to `job unfreeze`, it will unfreeze the job id of the most recently frozen job.

Therefore, one can use `alias fg = job unfreeze` to achieve a behavior similar to the one of existing unix shells.

## Job suspension

On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using <kbd>Ctrl</kbd>+<kbd>Z</kbd>. When a running process is suspended, it is turned into a "frozen" background job:

```nu

long_running_process # this starts running, then Ctrl+Z is pressed

# => Job 1 is frozen

job list

# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓

# => ┃ # ┃ id ┃ type ┃ pids ┃

# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫

# => ┃ 0 ┃ 1 ┃ frozen ┃ [list 1 items] ┃

# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛

```

A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command:

```nu

job unfreeze

# process is brought back where it stopped

```

::: tip Tip

For those familiar with other Unix shells, you can create an alias to emulate the behavior of the `fg` command:

```nu

alias fg = job unfreeze

```

:::

By default, `job unfreeze` will unfreeze the most recently frozen job. However, you can also specify the id of a specific job to unfreeze:

```nu

vim

# => Job 1 is frozen

long_running_process

# => Job 2 is frozen

job unfreeze 1

# we're back in vim

```

I tweaked this section to make it flow better, let me know what you think.

I'm not sure if we need to specify SIGTSTP specifically, I thought of moving it to a note/tip but I couldn't think of what that would look like.

that looks good to me! (and I'm not even the reviewer)

132ikl · 2025-03-20T02:33:46Z

could we rename the file to background_jobs.md also?

132ikl · 2025-03-20T02:34:14Z


-Unlike terminal multiplexer, you don't need to attach to multiple tmux sessions, and get task status easily.
+job spawn { sleep 10sec; ' inevitable' | save --append status.txt }
+## => 1


Suggested change

## => 1

# => 1

132ikl · 2025-03-20T02:34:18Z


-Here we provide a [nushell module](https://github.com/nushell/nu_scripts/tree/main/modules/background_task) that makes working with pueue easier.
+open status.txt
+## => i am


Suggested change

## => i am

# => i am

132ikl · 2025-03-20T02:34:25Z

-4. Add a line to the `$nu.config-path` file: `use task.nu`
-5. Restart Nushell.
+open status.txt
+## => i am inevitable


Suggested change

## => i am inevitable

# => i am inevitable

132ikl · 2025-03-30T21:29:13Z

looks great, thanks!

cosineblast · 2025-04-05T02:30:39Z

i think this may have broken the link to the background tasks section sidebar

any ideas on how to solve this?

nushell#1826 (comment)

sholderbach · 2025-04-07T09:57:07Z

The sidebar config is under .vuepress/configs/sidebar which is sadly hidden from ripgrep by default. There the entries are named. (Due to the renaming the existing entry failed)

* Fix sidebar for background job article #1826 (comment) * Also fix the German sidebar This refers to the German translation of the old version Pre-builtin jobs

cosineblast · 2025-04-07T22:34:12Z

which is sadly hidden from ripgrep by default
Oh, that explains a lot, thx

Add docs for jobs

c8ec261

cosineblast marked this pull request as ready for review March 4, 2025 02:37

Minor example output modifications

84cda03

132ikl requested changes Mar 20, 2025

View reviewed changes

cosineblast added 2 commits March 29, 2025 16:58

Apply review suggestions to job docs

9c39841

Rename background_task.md to background_jobs.md

48d34e6

132ikl merged commit 1c66b39 into nushell:main Mar 30, 2025
2 checks passed

sholderbach mentioned this pull request Apr 7, 2025

Fix sidebar for background job article #1864

Merged

sholderbach added a commit to sholderbach/nushell.github.io that referenced this pull request Apr 7, 2025

Fix sidebar for background job article

178637c

nushell#1826 (comment)

sholderbach added a commit that referenced this pull request Apr 7, 2025

Fix sidebar for background job article (#1864)

153b926

* Fix sidebar for background job article #1826 (comment) * Also fix the German sidebar This refers to the German translation of the old version Pre-builtin jobs

	Jobs can also be kiled/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:
	Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job_kill.md) command, which interrupts the job's thread and kills all of the job's child processes:

Conversation

cosineblast commented Mar 3, 2025

Uh oh!

fdncred commented Mar 3, 2025

Uh oh!

132ikl commented Mar 4, 2025

Uh oh!

132ikl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

132ikl Mar 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

132ikl commented Mar 30, 2025

Uh oh!

Uh oh!

cosineblast commented Apr 5, 2025

Uh oh!

sholderbach commented Apr 7, 2025

Uh oh!

cosineblast commented Apr 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

132ikl Mar 20, 2025 •

edited

Loading