Better document differences from bash

[faho]

We should better document fish's differences with bash (and to a lesser degree zsh, because knowledge of bash is common even among zsh users), maybe even to the point of having an entire section in our documentation dedicated to it.

Some of this is already in the FAQ ("!!"), but some isn't.

In #2379 we see that process expansion is one thing (an equivalent to "$!").

There's of course more, but a slight difficulty here is deciding what goes into "different from bash", and what goes into "general tutorial" (which is already geared at converts) - where does "set X Y" vs "X=Y" go? Both? One of them? What about "$argv"?

So the questions are (in a somewhat overlapping manner):

• Which differences haven't we adequately covered?

and

• How do we better draw attention to the fact which of fish's slightly different constructs is an equivalent to bash's $thing?

[alphapapa]

I suggest having a "Fish vs. X" or a "X-to-Fish Translation Dictionary" section in the docs. One of the things I think it should have is a translation table something like this:

Action/Thing	Bash	Fish
Command substitution	$(command)	(command)
Exit code of last command	$?	$status
Logical AND between commands	command1 && command2	command1; and command2
PID of self	$$	%self
PID of last command	$!	%last
Redirect STDERR	command 2>/dev/null	command ^/dev/null
	command 2>&1	command 2>&1
Redirect STDOUT	command >/dev/null	command >/dev/null
Run command in background	command &	command &
Unset variable	unset foo	set -e foo
Variable assignment	foo=bar	set foo bar

Note that it not only lists obvious differences, but also some significant features which are the same. I think this is also very important, e.g. the way Fish also uses command 2>&1 to redirect STDERR to STDOUT.

I think this should complement a general tutorial by being a reference, a resource designed to be quick to scan through and refer to often. The way I imagine people using it is, someone is converting a script from Bash to Fish, and he knows how to do something in Bash, but not in Fish; so he goes to this translation reference, looks for what he would type in Bash, and immediately finds what to do in Fish.

Good work @alphapapa.

I would love to see this and more work go into here as well.

[alphapapa]

Well, how about that, I had no idea that was on the Wikipedia page.

[zanchey]

The other good reference is http://hyperpolyglot.org/unix-shells

[faho]

One of the things I think it should have is a translation table something like this:

There's also some differences that don't quite fit into that table - how about quoting, word-splitting (e.g. for working with arrays/lists)? Or how about the fact that fish currently has no command substitution inside quotes? How about cross-products (i.e. set -l fish flounders catfish; echo $fish" are tasty") where an added space or added quote is very significant?

A table can certainly be included, but it needs some text to go along with it.

[pickfire]

I suggest something like the https://wiki.archlinux.org/index.php/Pacman_rosetta

[JoshCheek]

Another one that took me a long time to figure out, bash lets you set env vars on a per-command basis with A=B command and fish lets the env command do it with env A=B command I also hit that command-substitution inside quotes thing, eventually asked. I didn't realize the %self, was delegating to subprocesses and asking for parent pid (so yeah, this list seems necessary, esp b/c I just put fish on ~20 newbies computers, and their mentors very well might need to troubleshoot such things with very little knowledge of fish).

[faho]

Any thoughts on where this doc should be inserted? I'm thinking of making a section in the tutorial for it, though those experienced with a shell may be likely to skip such things.

The tutorial is where I would look for this table if I was just getting started with fish.

[faho]

Okay, I've now made a larger table and added it to the tutorial, but I've then started fighting doxygen - in particular it doesn't want to show "$(command)" and "||" in the table, and will break if a cell in the "Remarks" column is empty

This is what I have now:

If you know Bash , you'll want to know what is different in Fish. So here's the section for you! Note that while this is about bash, much of it will also apply for related shells such as zsh or ksh or dash.

Action/Thing	Bash	Fish	Remarks
Command substitution	"$(command)"	(command)	...
Command substitution in a string	"foo bar $(command)"	"foo bar "(command)	...
Process substitution	command <(command)	command (command \\| psub)	...
Logical AND between commands	command1 && command2	command1; and command2	...
Exit code of last command	$?	$status	...
Logical NOT	! command	not command	...
PID of self	$$	\%self	...
PID of last job	$!	\%last	...
Redirect STDERR	command 2>/dev/null	command ^/dev/null or command 2>/dev/null	...
Redirect STDERR	command 2>&1	command 2>&1	...
Redirect STDOUT	command >/dev/null	command >/dev/null	...
Run command in background	command &	command &	...
Variable assignment	foo=bar	set foo bar	By default bash variables are global, fish variables are function-scoped
Unset variable	unset foo	set -e foo	...
Check if a variable is defined	[[ ${var+_} ]] or [[ -v var ]] (since bash 4.2)	set -q foo	...
Check if a function is defined	typeset -f function >/dev/null	functions -q function	...
Export a variable	export foo	set -x foo $foo	...
Expand an n-element array/list to n arguments	"${var[@]}"	$var	Bash does wordsplitting again on unquoted array, fish does not
Expand an n-element array/list to 1 argument	"${var[*]}"	"$var"	...
Remove element from array/list	unset foo[1]	set -e foo[2]	...
Count the number of elements in an array/list	"${#var[@]}"	count $var	...
Return the first array/list element	"${var[0]}" or $var	$var[1]	Fish lists start from 1, bash arrays start from 0
if	if CONDITION; then COMMAND; fi	if CONDITION; COMMAND; end	...
for	for VAR in LIST; do COMMAND; done	for VAR in LIST; COMMAND; end	...
while	while CONDITION; do COMMAND; done	while CONDITION; COMMAND; end	...
Arguments to function	$* or $@	$argv	...

function definition | | |
Multi-condition if | | |

[GReagle]

I have submitted several updates, corrections, and additions to http://hyperpolyglot.org/unix-shells in order to make its information about fish more correct and comprehensive, and all of my submissions were accepted. I suggest that we not duplicate its content at all. We can hyperlink to it in fish docs.

[faho]

Well, I don't like the idea of linking people to other sites (that may or may not go down or bad or something), and that site still has a few questionable parts.

E.g. "sublist separators" don't mention and in the table, only later on in the full text, which for some reason mentions "pipelines". Now, I'm not sure if zsh does something regarding pipes and conditional execution, but I'm pretty sure in bash ls && ls does not connect stdout of the former to stdin of the latter.

"Interpolating quotes" mentions that command substitutions inside double quotes aren't executed by fish, but in fact no expansion but variable expansion ($var) is performed in double quotes. Then there's plenty of places where the fish entry says "none" because fish doesn't have any built-in syntax to handle it but then it doesn't mention how to do it (like sequences with seq 0 10 instead of {0..10}).

There's other things missing, but my main point stands: I'd rather we have a table that is installed with our docs than link to an external site. (Not that I dislike what they are doing)

[GReagle]

http://hyperpolyglot.org/unix-shells has a creative commons attribution-sharealike 3.0 license. So if it ever goes down, a copy can be taken over by fish or some other host, but on the other hand, I understand not wanting to rely on an external resource.