
Explain Shell - auton1
http://explainshell.com/
======
lelandbatey
I totally love this, it's already incredibly helpful! It's super-functional,
and frankly it's very, very nice looking. To Mr. Idan Kamara, the creator of
this, I have nothing but the highest praise!

Now, I hate to get side-tracked, but for much larger commands, like this one:

    
    
         ps x -o  "%r %c " | grep "someScript.sh" | awk -F' ' '{print $1}' | xargs -I % /bin/kill -TERM -- -%
    

that has a lot of parts, it can be hard to connect the different options to
the various explanations[0], since there are so many lines and they frequently
have similar colors and you have to keep scrolling up and down the page. Being
able to do something like click on a command/option and have the page jump to
the corresponding explanation would be very helpful.

[0] -
[http://explainshell.com/explain?cmd=ps+x+-o++%22%25r+%25c+%2...](http://explainshell.com/explain?cmd=ps+x+-o++%22%25r+%25c+%22+|+grep+%22webLauncher.sh%22+|+awk+-F%27+%27+%27{print+%241}%27+|+xargs+-I+%25+%2Fbin%2Fkill+-TERM+--+-%25)

~~~
idank
Hi! Happy to see explainshell on HN again, thanks for all the compliments!

I agree about large commands being hard to follow. I tried solving this by
adding the ability to navigate between commands. Right now clicking the
command takes you to a page that displays that command options, but I can
change it to the equivalent of navigating to it with the arrows at the top.
There might be something better to do UI wise, though.

~~~
brandall10
Hi, I love this. I bookmarked it and plan to use this often.

Possible additions:

\- Something that users of the service could add commands to and the community
could up vote for grading on technical difficulty.

\- Also a "shell command of the day" type of mailer service would be amazing
:)

~~~
idank
I can scan the access logs for the top explained commands, and show those on
the home page (although that will probably only further increase their
popularity ;).

~~~
robryk
You can also count how often they are requested from the links on the home
page. Granted, the additional popularity will probably cause people to share
those more often.

------
jfasi
Gorgeous. Amazing. Absolutely fantastic. Easy the coolest and most useful
thing I've seen on hacker news in a while.

Enough gushing, now some bug reports:

"read -r random_line < <(sort -R file)" yields "syntax: expecting filename or
fd (position 22)"

"nc HOST PORT | tee movie.mp4 | mplayer -" I can hover over movie.mp4, but I
can't scroll down the see the description without losing the emphasis on that
path. I'd suggest letting the user click on the portion, or perhaps a long-
hover effect?

~~~
idank
Thanks, that's really fun to hear.

ACK on the command substitution not working, with the current lexer that I
have in place fixing this isn't easy and might take a while. But it's
definitely up there on my todos.

Yeah, long pipelines are somewhat of a problem. You can currently navigate the
commands with the buttons at the top, maybe they're not visible enough.

But I like the idea of being able to pin a particular line by pressing it, but
I fear it might be a bit subtle and easy to miss.

~~~
drothlis
Do you have any thoughts, or writings that you could point me to, regarding
shell's parseability? For example, is it possible to parse a shell script
without running it? Would it be possible to extract Bash's lexer+parser into a
stand-alone library to be used by IDEs?

~~~
idank
Yes, you can parse without executing. I think shell is easier to parse than it
seems, there are definitely some nuances that might be tricky to emulate, but
I guess it's a matter of effort and how far you're willing to go. For syntax
highlighting in IDEs, you probably don't need much, and maybe even a few
regexs can get you close enough.

I actually spent a considerable amount of time going over bash's parser [0],
and also zsh's [1]. Bash uses lex/yacc with some custom code. zsh seems to
have a custom written lexer/parser.

Unfortunately none of them were written to be used as a library, as evident by
global state, and a lot of hooks for prompts while parsing, etc. It might be
possible to somehow make it work, but it seems like a lot of work to me. You
might have an easier time looking at the parser I wrote, and extending that,
or rewriting it in another language (as it's fairly small compared to the ones
you find in shells). There's also libbash [2], haven't looked closely though.

[0]:
[http://git.savannah.gnu.org/cgit/bash.git/tree/parse.y](http://git.savannah.gnu.org/cgit/bash.git/tree/parse.y)

[1]: [https://github.com/zsh-
users/zsh/blob/master/Src/parse.c](https://github.com/zsh-
users/zsh/blob/master/Src/parse.c)

[2]:
[http://www.gentoo.org/proj/en/libbash/](http://www.gentoo.org/proj/en/libbash/)

------
ivan_ah
The UI with the svg "wiring" is awesome. You should consider abstracting away
that functionality so that it can be reused by other projects.

Right now I'm imagining explainphys ;) where each term in a physics equation
is explained e.g. The magnetic force felt by a particle of charge q moving
with velocity \vec{v} in a magnetic field \vec{B} is

    
    
          \vec{F}_B =   q \vec{v} × \vec{B}
           |            |   |     |   |______magnetic field    
        magnetic force  |   |     |
                        |   |   cross
                   charge   |   prod.
                            |
                       velocity of particle

~~~
Splendor
Agreed. I would love to see this UI on a RegEx parser too.

~~~
AlwaysBCoding
Check out [http://www.regexper.com/](http://www.regexper.com/)

~~~
Splendor
I've used that but I think OP's UI is sexier. Thanks though.

------
staunch
Very well done. Now I just wish this was a shell program!

    
    
      user@server:~$ explain iptables -A INPUT -i eth0 -s ip-to-block -j DROP

~~~
jph
I'll donate $100 if the author wants to build this and open source it. [Ed: As
a shell application locally]

A new "explain" command could help me, my team, and save us an enormous amount
of time getting up to speed on some of our org's long-term system maintenance
scripts.

~~~
toomuchtodo
How about an API where you can POST your script with curl -X and a unique link
is returned that explains the script when you hit it with a browser?

#shutupandtakemymoney (DevOps is fun, teaching not always)

~~~
skeletonjelly
I would never install this in this format. I'm not going to POST my bash
history!

I'd prefer a model where you download a definition file (if it needs to be
"updated" at the start frequently)

------
tieTYT
This is pretty cool but what I found annoying was matching the snippet of code
and the description together. Take this for example:
[http://explainshell.com/explain?cmd=true+%26%26+%7B+echo+suc...](http://explainshell.com/explain?cmd=true+%26%26+%7B+echo+success%3B+%7D+%7C%7C+%7B+echo+failed%3B+%7D)

The command is: true && { echo success; } || { echo failed; }

But the top box description is for echo parameters. The next one is for echo.
Why can't it go from top to bottom in order of the command? EG: Start with
true, then &&, then {, then echo, etc.

The way it is, I spend a lot of mental energy matching things up.

~~~
idank
I agree it's a little counter-intuitive. But if it's top to bottom then all
the lines would cross each other which would ruin the UI. If there's a way to
make it top to bottom while keeping the UI useful, I'd love to hear!

~~~
calhoun137
> If there's a way to make it top to bottom while keeping the UI useful, I'd
> love to hear!

I understand that the UI looks very nice, but at least for me, having the
explanation boxes be in order would make it a _lot_ easier to use. So here is
my suggestion:

You can keep everything looking exactly like it is now, except get rid of the
lines altogether, and display all of the explanation boxes in order.

When the user scrolls down far enough, display the query at the top of the
page with fixed position so that it is always on screen. Then topmost
displayed explanation box will get highlighted, along with the relevant
portion of the query; unless the mouse is hovering over a certain box or
portion of the query, in which case that command/box pair becomes highlighted
instead.

If a user tries to scroll with the mouse wheel or keyboard, but there is no
more content to display on the page, then the scrolling causes the highlighted
box to change instead.

If a portion of the query is highlighted which is not on the page, then
clicking that portion will cause the page the jump so that the corresponding
box appears and becomes highlighted.

~~~
err4nt
I know I'll be lynched for suggesting an extraneous JavaScript library like
Bootstrap here on HN, but what if the command stayed visible at the top of the
screen once you scrolled past it on the page (just like how Bootstrap's Affix
plugin works) and the relevant part of the command you were reading about
became highlighted as you scroll down the description (just like Bootstrap's
ScrollSpy plugin).

That would be an intuitive UI without relying on wires to connect the content
to the sections of the command and it lends itself to responsive layout as
well because the command can easily wrap to multiple lines without losing
clarity as you read the explanation (where the wires might start to eat into
screen real estate at phone width and become much less clear if the command
had to be split to multiple lines to stay visible)

------
SimHacker
This is a wonderful idea and an upstanding social service, in the same vein of
giving heroin addicts access to free clean needles, pure heroin, and a safe
place to shoot up.

There is no perfect solution -- in the ideal world, everyone would use safe
healthy programming languages, and nobody would be addicted to shell
scripting.

But in the real world, many people still choose to use shell scripting as a
quick and easy short term solution to their problems.

Like the unhealthy temptation to use regexps for parsing html, shell scripting
just causes more problems, which snowball out of control until you have the
dire situation we're in today, with a whole generation of urban hipsters who
learned cargo-cult cut-n-paste shell scripting by typing "more ./configure".

So it's much better to treat shell scripting as a health problem rather than a
criminal problem.

My only suggestion is that you should sponsor links to "recovery programs,"
where people can learn to solve their problems with safe healthy programming
languages instead of shell scripts. For the popular rube-goldbergesque shell
incantations, you could show how to accomplish the same thing more
comprehensibly in Python, Ruby, JavaScript, Lisp, Forth, Mathematica, Quartz
Composer, etc. ;)

------
noonespecial
So I fed it : cat ./trunk/.config |awk ' /CONFIG_TARGET_BOARD/ {
gsub(/\"/,""); split($0,a,"="); print a[2] }'

A little one-liner I worked up a few days ago to quickly show me which
architecture my OpenWRT trunk was last built with. I'd really like it to
explain in much more detail _what_ each of the terms inside the awk command
do. Perhaps make "explain" modular so that people can add more detail to the
gazillion things that can happen inside awks, seds, greps, etc?

Fabulous idea. This should have been in unix all along as part of the man
system.

~~~
angersock
That'd be brilliant.

We should have a `wtf?` command, used like so:

    
    
      wtf? yes | sudo apt-get install libpq-dev
    

Results would be ncurses, top line of screen is command with current
subcommand highlighted, and rest of screen is less'ed explanation.

------
scott_karana
It unfortunately can't decode :(){ :|:& };:, a classic unintelligible
forkbomb. I suppose it's only lack of function support that's the issue!

Really neat program, nonetheless!

~~~
idank
I'm tempted to add a place holder for all the variations of this forkbomb,
until I teach the parser about functions.

You'll be amazed how many people try this (or other 'malicious' commands),
presumably thinking I'm executing the queries. ;)

~~~
akincisor
I tried this, but not because I believed that you would execute it, but
because a very important use of such a tool would be to explain potentially
dangerous commands and their implications.

~~~
redwall_hp
I searched the classic sudo rm -rf /, too. Just to see if it would adequately
explain it.

------
denizozger
[http://explainshell.com/explain?cmd=git](http://explainshell.com/explain?cmd=git)

Funny

~~~
ygra
It's what git's man page says:
[https://www.kernel.org/pub/software/scm/git/docs/](https://www.kernel.org/pub/software/scm/git/docs/)

------
JoshTriplett
This is quite impressive.

I'd love to see the argument explanations narrow down sub-arguments. For
instance, "find -type f" ought to just show the top-level description for
-type and the description for 'f', not all the other type characters.

------
njharman
Source
[https://github.com/idank/explainshell](https://github.com/idank/explainshell)

This is truly stunning. It's a small thing, and what it does is not
stupendous. But the design, aesthetics, ease of use, in a word elegance makes
the combined whole a superlative tool.

------
fernly
Impressive but I agree with all who said you can't read the callouts below the
2nd or 3rd, because you have to scroll, which loses the focus on the item. I
think it might work better if you just pop up one explanation box at a time,
directly below the command, as the mouse sweeps across.

Also missing some obvious things like on this basic zip command [0]. It can't
explain -9, probably because that's not in the man page as itself but as "-n".
But also has nothing to offer about the zip file target or the input folder,
which are in the man page as symbolic arguments.

[0]
[http://explainshell.com/explain?cmd=zip+-vr9+foo.zip+somefol...](http://explainshell.com/explain?cmd=zip+-vr9+foo.zip+somefolder)

------
pixelmonkey
Really cool. A suggestion. For long explains, it'd be great to be able to
click on the part to jump to that part of the explanation, and then offer some
way to "jump back to top".

Alternatively, I was thinking there might be a nice "swipe" or "carousel"
interface applicable here. e.g. you hit left/right arrows and it explains
every individual atom of the command-line.

That said, very nice as it is now. You deserve major kudos simply for bringing
most manpages online in a searchable, good-looking interface! Instantly added
as a "dev" bookmark for me.

------
TallboyOne
Lots more where that came from (great resource btw!):
[http://pineapple.io/resources/tagged/bash+terminal](http://pineapple.io/resources/tagged/bash+terminal)

------
b0rsuk
It's surprisingly good, overall, but there are some glaring omissions. For
instance:

sudo apt-get install tree Only sudo is explained. I understand apt-get is
distro-specific, but it's widespread enough to deserve a special case.
Interestingly, apt-get install tree (without sudo) works better.

Common, widely known system configuration files like /etc/issue, /etc/hosts,
/etc/hostname, /etc/fstab ... deserve to be special-cased, too. Many of them
actually have their man pages, so it's possible to script.

~~~
idank
True, it doesn't figure out that some commands should be matched recursively
since their arguments are other commands, xargs is also in the same boat.
There might be an open bug for this already.

I only scanned sections 1 and 8 of the man page archive, so that's why files
are missing.. but they can be added.

------
cheeseprocedure
This is brilliant. (I've forwarded it to novices and pros alike, and everyone
else's response has been much the same.)

If you were to open up donations to support development, I would HAPPILY
contribute.

~~~
idank
Thanks!

I work full-time right now, so money isn't really an issue. I'll gladly accept
commits though! ;)

------
Procrastes
I agree it's beautiful, and a really great idea. I'll also add my vote that
this would make an even better commandline tool.

It had difficulty with:

find . -name " _.cpp " | xargs -i grep -His "oops" "{}"

[http://explainshell.com/explain?cmd=find+.+-name+%22*.cpp%22...](http://explainshell.com/explain?cmd=find+.+-name+%22*.cpp%22+|+xargs+-i+grep+-His+%22oops%22+%22{}%22)

It seems to think the -His belongs to xargs rather than grep.

------
emeraldd
It's a nice toy, but seems to break down with more interesting stuff. For
instance:

    
    
       for FILE in `ls`; do echo $FILE ; done
    

[http://explainshell.com/explain?cmd=+for+FILE+in+%60ls%60%3B...](http://explainshell.com/explain?cmd=+for+FILE+in+%60ls%60%3B+do+echo+%24FILE+%3B+done)

That's a simpler equivalent of something I cooked up which probably didn't
belong in a single line of shell anyhow.

~~~
idank
You've hit the two top things on my to do list.. command substitution and
control flows. It says on the top of the home page that they're not
implemented yet.

~~~
emeraldd
That's what I get for trying to play with a new site after Thanks Giving
weekend! You already have a solid tool, that will make it even better ;)

------
publicfig
This is amazing! It's great for someone like me who, while knowing their way
around the shell, isn't as well versed as some of my more veteran co-workers.
While it's great to hear explanations of some of the more dense lines they
give me to run, that's not always possible and can be a bit annoying. This
could help take some of the pressure off of them to drag me through. :P

------
jff
I don't know what I was expecting, but one of my most-used command lines, "du
-a | grep foo" is pretty uninformative.

~~~
w1ntermute
If you're just trying to locate a file in the current directory, you should
probably be using find.

~~~
mturmon
Just for definiteness, the equivalent "find" idiom would be:

    
    
      % find . -path '*foo*'
    

You need -path, not just -name, to match the whole name as du does.

~~~
jff
I'll point out that the find command is 21 characters, while mine is only 17.
Efficiency!

~~~
mturmon
Yes, you have a point (plus, those stars, they burn the eyes).

But, your detractors will say yours is two processes and theirs is one.
Efficiency!

~~~
jff
The kernel could start 100 processes in the time it takes me to type those
extra four characters. We won't run out of processes. I did a test, finding
.txt files in /usr/share, it took about .25 seconds longer with du and grep,
which seems like less than it takes to type 4 more characters.

~~~
girvo
How long does it take you to type a character???

~~~
jff
Assume I type 80 wpm

A word is standardized as 5 keystrokes

80 wpm is therefore 400 keystrokes per minute.

Divide by 60 to get about 6.6 keystrokes per second, or about 0.15 seconds per
keystroke.

Therefore it would take about 0.6 seconds to type the four extra characters,
giving a net savings to use du+grep instead.

And 80 wpm is probably a rather fast estimate; I'd guess that I type slower
when I'm writing commands than when I'm entering English text.

~~~
girvo
I must've read it wrong, or you fixed it, 'cause I read it as 25 seconds,
hence my question! :)

------
un1xl0ser
Amazing tool for beginners, but also helpful for advanced users.

GREAT: find / -type f -print0 |xargs -0 grep heythere

I tried some sub-shells, and seemed to not work so well. $() and `` would be
nice.

ps -fp $(pgrep -d, krb5kdc)

ps -fp `pgrep -d, krb5kdc`

[http://explainshell.com/explain?cmd=ps+-fp+%24%28pgrep+-d%2C...](http://explainshell.com/explain?cmd=ps+-fp+%24%28pgrep+-d%2C+krb5kdc%29)

edit: newlines

------
ChuckMcM
Very nice. It was challenged by my go to command:

    
    
       tar cf - . | (cd /dest/dir ; tar xvf -)
    

Which uses tar to copy a directory tree. It didn't know '.' stood for the
current directory, it missed out that 'f -' was the file "standard in" /
"standard out"

~~~
gahahaha
Why do you use that instead of cp -R ? I would normally only use your version
if I was copying a directory tree over ssh.

~~~
ChuckMcM
Generally tar to tar transfers have a couple more options, one being not to
step across file systems, one being to keep symlinks intact (or not), and one
being to avoid filling in 'holey' files.

Of course those things might not be true any more, basically I got habituated
to using it when I was Sun and it continues to work, so my fingers haven't
tried to learn a new pattern.

------
mihok
I give out this link to all my developers that are just getting a feel for the
terminal. Thanks so much for this!

A nice to have: Having the command that was originally entered follow you down
at the top of the window so when I'm looking at a long piped command, it makes
it easier to follow

------
kfk
Hey, very nice! What about allowing users to take notes and tags on the search
results? I have a bunch of bash commands I run I always forget, this would
help me a lot to keep track of things (like all the ssh-ing stuff that I can't
seem to fit in my memory...).

------
hndl
Very cool! It would be great if you would provide common usages for a given
command if the user didn't provide any switches. That could be links like the
ones you have in the "examples" section on the landing page.

------
dzlobin
Holy moly, this might be one of the best things I've seen on HN in a long
time.

------
gocha9921
I am new to command line - but this is awesome! VERY helpful. Thanks and
congrats!

------
gjarkko
vpenis.sh also has trouble explaining. It's a bit of a challenge for anyone,
though.

echo `uptime|grep days|sed 's/. _up \\([0-9]_ \\) day.*/\1\/10+/'; cat \
/proc/cpuinfo|grep '^cpu MHz'|awk '{print $4"/30 +";}';free|grep \ '^Mem'|awk
'{print $3"/1024/3+"}'; df -P -k -x nfs | grep -v \ 1k | awk '{if ($1 ~
"/dev/(scsi|sd|md)"){ s+= $2} s+= $2;} END \ {print
s/1024/50"/15+70";}'`|bc|sed 's/\\(.$\\)/.\1cm/

------
aeykie
You can use `man test` for [ ] which it currently reports no man page for.

------
wila
Great tool. Would have preferred to use it locally without all of those
dependencies on a machine without networking. But OTOH having it online means
that it is easier to centrally manage and update.

------
eabruzzese
This is incredible.

One small change request: the longer commands make me scroll down the page,
and I can no longer see what each block is pointing to. Maybe you could fix
the command to a top-bar as you scroll down?

------
Riseed
This is beautiful! It will come in handy for filling in the vast holes in my
knowledge. I think it would also make a great resource for those just starting
to work with shell. Very well done indeed!

------
rbosinger
Wow. I've only tried a few queries but they worked well! This could be great
for breaking down some of the "copy paste to install this" commands you see
from open-source projects.

------
trurl42
It fails to parse the command if you start with a redirect.

[http://explainshell.com/explain?cmd=%3E+foo](http://explainshell.com/explain?cmd=%3E+foo)

------
DonGateley
I'd like it if hovering on a parsed item moved it's explanation to the top
rather than just highlighting it. Not so much scrolling required if any.

------
Theriac25
Doesn't seem to support backquotes? For example

    
    
        for x in `ls ~/foo`; do echo $x; done
    

doesn't yield anything remotely interesting.

~~~
nailer
New style subshells aren't supported (yet) either:

    
    
       for x in $(ls ~/foo); do echo $x; done

------
SmileyKeith
This is fantastic. Even with simple examples like `ls -la` it shows the
documentation and other flag synonyms for all of the passed flags. Very
impressed.

------
ape4
Its cool and good but gets into the syntax too quickly. To explain "tar xzvf
archive.tar.gz" I would say "extract the archive".

------
parallelist
Nothing useful said for:

    
    
      for word in foo bar baz; do echo $word; done
    

Seems to think COLUMNS is a command in:

    
    
      COLUMNS=20 ls

------
TorKlingberg
Very neat!

I did choke at the end of this little favorite:

    
    
      find -name "*.[hc]" -o -name "*.[hc]pp"|xargs grep -siP 'apa'

------
nailer
Good: it understands &>, which some Unix old-timers don't get.

To improve: it didn't provide any context to what $IFS is used for.

------
mathattack
You know you're on the right track when people are saying, "But why isn't this
in there already?"

------
willfiveash
Doesn't yield anything particularly useful for: [[ -f /tmp/foo ]] && echo yes

------
ErikRogneby
First of, I love the functionality and clean design.

Why are you using bootstrap if the site isn't responsive?

------
daGrevis
It says that `-h` in `shutdown` stands for help, not halt. Otherwise, seems as
a useful tool! :)

------
D9u
The site doesn't mention the !! command.

The !! command is used to repeat the previously issued command.

------
emiliobumachar
Great! This could serve as an example for help sites about other shell-like
environment.

------
harichinnan
Found a minor defect.

cat fil*.dat | head -100 | tail -20. Does not explain -100 in head and -20 in
tail.

------
kin
Yup, just shared with my whole office. Super useful for all levels. Thanks for
this.

------
fennecfoxen
:(){ :|:& };: or GTFO :)

~~~
poizan42
I tried that as well. It says "Missing man page" :(

------
nish1500
I started learning Shell last week. This couldn't have been better timed :)

------
Arnor
Awesome tool. Now can we have one that does the same thing for a regexps?

~~~
Nyubis
Check out [http://regex101.com/](http://regex101.com/)

~~~
Arnor
Awesome, Thanks!

------
k-mcgrady
Really cool project! I can already see myself using this a lot.

------
quickpost
This is awesome. Best post I've seen on HN in a while.

------
Xelom
Beautiful. Can't describe with words...

------
heldrida
Very interesting project, already using it!

------
gtallen1187
this is great - i have had a hard time learning shell and this is a huge help.
thank you!!!

------
social_monad
# this command fails to explain:

: abc $(xclock) def

------
samsosina
Straight to my bookmark bar!

------
garrettdreyfus
It's like shellgenius.

------
droid_w
Fantastic! I love your UI.

------
paulasmith
Fantastic tool, kudos!!!!

------
NovaS1X
Haha! This is brilliant!

------
mmgutz
Very useful. Good job.

------
bonemachine
Really liking this.

------
nichochar
This is super cool

------
deft0nes
Totally awesome!

------
pmattos
Stuff of dreams!

------
uonyx
Nice. Very nice.

------
ananth99
Insane stuff!

------
mumoksha
Nice!!!!!

------
jbverschoor
WOW!

