Bash – How to document the custom bash functions and aliases

aliasbashdocumentationfunction

Problem:

I have multiple bash functions and aliases. I can't remember all of them off the top of my head, so I usually end up opening my .bash_functions and .bash_aliases files to find what I need.

Question(s):

How can I list functions/aliases available from the bash prompt?

Is it possible for me to document my bash functions/aliases using comments (kinda like PHPDoc)?

I'd just like a simple/nice way to output what's available without having to open the files. It would be cool to run a command and have it spit out a dynamic list of my functions/aliases (usage examples would be a plus). 🙂

Best Answer

To list active aliases, run:

alias

To see names of all active functions, run:

declare -F

To see the names and definitions of all active functions, run:

declare -f

The information on aliases is also available is a script-friendly format with:

declare -p BASH_ALIASES

man bash provides more info on the alias builtin:

   alias [-p] [name[=value] ...]
          Alias with  no  arguments  or  with  the  -p
          option  prints  the  list  of aliases in the
          form alias name=value  on  standard  output.
          When  arguments  are  supplied,  an alias is
          defined for each name whose value is  given.
          A  trailing  space in  value causes the next
          word to be checked  for  alias  substitution
          when  the  alias is expanded.  For each name
          in the argument list for which no  value  is
          supplied, the name and value of the alias is
          printed.  Alias returns true unless  a  name
          is   given  for  which  no  alias  has  been
          defined.

Regarding functions, man bash explains that declare can provide still more information is available if the extdebug option is set:

   Function  names  and definitions may be listed with
   the -f option to the  declare  or  typeset  builtin
   commands.  The -F option to declare or typeset will
   list the function names only  (and  optionally  the
   source  file and line number, if the extdebug shell
   option is enabled).

Links

Related Solutions

Bash – How to Refresh Aliases and Functions After Defining New Ones

Sourcing the changed file will provide access to the newly written alias or function in the current terminal, for example:

source ~/.bashrc

An alternative syntax:

. ~/.bashrc

Note that if you have many instances of bash running in your terminal (you mentionned multiple tabs), you will have to run this in every instance.

How to enable `sudo` with custom functions

In the general case what you're trying to do doesn't really work.

With aliases, there is pretty much just a string rewrite before the line is passed for execution.

So, for example, if you have

alias sudo='sudo '
alias foo='bar baz'

then when you enter sudo foo the command line is rewritten to sudo bar baz and that is then what is run. This is simple command line rewriting.

Now functions are harder. They're not simple rewrites, but a complete evaluation; they can set variables, change directories, open files... pretty much do anything the shell can do. And, importantly, they're run in the context of the current shell. When you run sudo myfunction then none of this is possible; in particular sudo commands are run as a sub-process and so can't affect the current shell.

The work-around used for things like the sudowrap mentioned above is to try and automatically work out sudo bash -c 'myfunction() {...} ; myfunction'. This explicitly calls a new bash subshell and then runs the function in that subshell. The explicit call makes it clear that things like setting variables and the like won't work :-) It allows for a limited subset of functionality.

The sort of functions you can call this way may be better rewritten as shell scripts rather than functions; then sudo can call them directly. The example given at http://w00tbl0g.blogspot.com/2007/05/using-bash-functions-under-sudo.html would be easier by having duk converted to an executable

#!/bin/bash
exec du -k "$@" | sort -n

That'll then work as expected!

Bash – How to document the custom bash functions and aliases

Problem:

Question(s):

Best Answer

More

Links

Related Question