#13003·fish-shell

Docs for `return` do not specify what happens when optional status is ommitted

Author: drsybrenCreated Sep 15, 2026Updated Sep 17, 2026

The documentation for the return statement (https://fishshell.com/docs/current/cmds/return.html) states:

The exit status is set to N if it is given.

However, it does not specify what happens if N is not given. I can see a few plausible behaviours:

  1. It is equivalent to return 0, i.e. the function call is considered 'successful'.
  2. It does not modify $status, i.e. the return value is set to the exit status of the last-run command in that function.

A quick test with the script I'll put below shows that it's the 2nd option, and that this is equivalent to having no return statement at all.

At the moment of writing, the documentation was for fish-shell 4.9.3.

fish

function return_42
    return 42
end

function return_implicit
    return_42
    return
end

function no_return
    return_42
end

return_42
echo "return_42 returned $status"

return_implicit
echo "return_implicit returned $status"

no_return
echo "no_return returned $status"

Anecdote: these kind of cases, where only part of the behaviour is documented, always remind me of good old Doom. It had an option for the graphics, a checkbox "8-bit textures". Of course it's clear what happens when you enable it, but what happend when it's disabled was completely unclear. Would it give you 4-bit or 16-bit textures? Would enabling the checkbox cause a rendering speedup or a quality improvement? To this day I still don't know.