How to display shell built-in help → help

How to Display Shell Built-in Help → help Table of Contents - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Understanding Shell Built-ins](#understanding-shell-built-ins) - [Basic Help Command Usage](#basic-help-command-usage) - [Advanced Help Command Options](#advanced-help-command-options) - [Practical Examples and Use Cases](#practical-examples-and-use-cases) - [Comparing Help Sources](#comparing-help-sources) - [Common Issues and Troubleshooting](#common-issues-and-troubleshooting) - [Best Practices and Professional Tips](#best-practices-and-professional-tips) - [Integration with Other Documentation Tools](#integration-with-other-documentation-tools) - [Conclusion](#conclusion) Introduction The shell `help` command is an essential tool for any command-line user, providing instant access to documentation for shell built-in commands. Unlike external programs that use manual pages (`man`), shell built-ins require a different approach to access their documentation. This comprehensive guide will teach you everything you need to know about using the `help` command effectively, from basic syntax to advanced usage patterns. Whether you're a beginner learning the command line or an experienced system administrator looking to optimize your workflow, understanding how to access built-in help will significantly improve your productivity and command-line proficiency. The `help` command serves as your first line of defense when you need quick reference information without leaving your current shell session. In this article, you'll learn how to use the `help` command in various scenarios, understand its options and parameters, troubleshoot common issues, and integrate help usage into your daily workflow. We'll cover everything from basic command syntax to advanced filtering techniques, ensuring you have a complete understanding of this fundamental shell feature. Prerequisites Before diving into the `help` command, ensure you have the following: System Requirements - A Unix-like operating system (Linux, macOS, or WSL on Windows) - Access to a bash shell (version 3.0 or higher recommended) - Basic familiarity with command-line navigation - Terminal or shell access with appropriate permissions Knowledge Prerequisites - Understanding of basic shell concepts - Familiarity with command-line syntax - Basic knowledge of shell built-ins versus external commands - Understanding of command options and arguments Verification Steps To verify your system is ready, run these commands: ```bash Check your shell version echo $BASH_VERSION Verify help command availability type help Test basic help functionality help help ``` If these commands execute successfully, you're ready to proceed with the comprehensive exploration of the `help` command. Understanding Shell Built-ins What Are Shell Built-ins? Shell built-in commands are functions that are compiled directly into the shell program itself, rather than existing as separate executable files on the filesystem. These commands are executed directly by the shell without spawning a new process, making them faster and more efficient than external commands. Common Built-in Commands Here are some frequently used built-in commands that you can access help for: ```bash Navigation and directory commands cd, pwd, dirs, popd, pushd Variable and environment commands export, set, unset, declare, local Control flow commands if, then, else, fi, case, while, for, until Job control commands jobs, bg, fg, kill, wait History commands history, fc I/O and file commands read, echo, printf, source, exec ``` Identifying Built-ins You can determine whether a command is a built-in using the `type` command: ```bash Check if a command is built-in type cd Output: cd is a shell builtin type ls Output: ls is aliased to `ls --color=auto' or: ls is /bin/ls type help Output: help is a shell builtin ``` Basic Help Command Usage Simple Help Command Syntax The most basic usage of the `help` command follows this syntax: ```bash help [command_name] ``` Getting General Help Running `help` without any arguments displays a list of all available built-in commands: ```bash help ``` This command produces output similar to: ``` GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu) These shell commands are defined internally. Type `help' to see this list. Type `help name' to find out more about the function `name'. Use `info bash' to find out more about the shell in general. Use `man -k' or `info' to find out more about commands not in this list. A star (*) next to a name means that the command is disabled. job_spec [&] history [-c] [-d offset] [n] or hist> (( expression )) if COMMANDS; then COMMANDS; [ elif C> . filename [arguments] jobs [-lnprs] [jobspec ...] or jobs > : kill [-s sigspec | -n signum | -sigs> [ arg... ] let arg [arg ...] [[ expression ]] local [option] name[=value] ... ``` Getting Help for Specific Commands To get detailed help for a specific built-in command, specify the command name: ```bash help cd ``` This displays comprehensive information about the `cd` command: ``` cd: cd [-L|[-P [-e]] [-@]] [dir] Change the shell working directory. Change the current directory to DIR. The default DIR is the value of the HOME environment variable. The variable CDPATH defines the search path for the directory containing DIR. Alternative directory names in CDPATH are separated by a colon (:). A null directory name is the same as the current directory. If DIR begins with a slash (/), then CDPATH is not used. If the directory is not found, and the shell option `cdable_vars' is set, the word is assumed to be a variable name. If that variable has a value, its value is used for DIR. Options: -L force symbolic links to be followed: resolve symbolic links in DIR after processing instances of `..' -P use the physical directory structure without following symbolic links: resolve symbolic links in DIR before processing instances of `..' -e if the -P option is supplied, and the current working directory cannot be determined successfully, exit with a non-zero status -@ on systems that support it, present a file with extended attributes as a directory containing the file attributes The default is to follow symbolic links, as if `-L' were specified. `..' is processed by removing the immediately previous pathname component back to a slash or the beginning of DIR. Exit Status: Returns 0 if the directory is changed, and if $PWD is set successfully when -P is used; non-zero otherwise. ``` Advanced Help Command Options Help Command Options The `help` command supports several options to modify its behavior: ```bash help -d [command] # Display short description only help -m [command] # Display usage in pseudo-manpage format help -s [command] # Display only short usage synopsis ``` Short Description Mode Using the `-d` option provides concise descriptions: ```bash help -d cd Output: cd - Change the shell working directory. help -d export Output: export - Set export attribute for shell variables. ``` Manual Page Format The `-m` option formats output similar to traditional manual pages: ```bash help -m cd ``` This produces detailed output formatted like a man page, including sections for NAME, SYNOPSIS, DESCRIPTION, and OPTIONS. Synopsis Mode The `-s` option shows only the command syntax: ```bash help -s cd Output: cd: cd [-L|[-P [-e]] [-@]] [dir] help -s export Output: export: export [-fn] [name[=value] ...] or export -p ``` Pattern Matching You can use pattern matching to find commands: ```bash help -s '*' # Show synopsis for all commands help -d 'p*' # Show descriptions for commands starting with 'p' help 'ex*' # Show help for commands starting with 'ex' ``` Practical Examples and Use Cases Scenario 1: Learning New Commands When encountering an unfamiliar built-in command, use help to understand its purpose: ```bash Discover what 'declare' does help declare Learn about 'local' variable scope help local Understand 'read' command options help read ``` Scenario 2: Refreshing Memory on Command Options For commands you use occasionally, help serves as a quick reference: ```bash Remind yourself of export options help -s export Check available options for history command help history Review printf formatting capabilities help printf ``` Scenario 3: Scripting and Development When writing shell scripts, help provides essential syntax information: ```bash Check conditional syntax help if help test help [[ Review loop constructs help for help while help until Understand function definition help function ``` Scenario 4: System Administration Tasks For administrative tasks, help clarifies command behavior: ```bash Understand job control help jobs help bg help fg Review process management help kill help wait Check I/O redirection help exec ``` Scenario 5: Debugging and Troubleshooting When debugging scripts or commands, help clarifies expected behavior: ```bash Understand set options for debugging help set Review trap command for error handling help trap Check return and exit behavior help return help exit ``` Comparing Help Sources Help vs. Man Pages Understanding when to use `help` versus `man` is crucial: | Aspect | help command | man command | |--------|--------------|-------------| | Target | Built-in commands | External programs | | Speed | Very fast | Slower (file access) | | Availability | Always available in shell | Requires man pages installed | | Format | Shell-specific | Standardized format | | Examples | Limited | Often extensive | Help vs. Info Pages The `info` system provides another documentation source: ```bash General bash information info bash Specific topic information info bash "Bash Builtins" Compare with help help cd info bash cd ``` Help vs. Command --help Many commands support the `--help` option, but this doesn't work for built-ins: ```bash This works for external commands ls --help grep --help This doesn't work for built-ins cd --help # Error: cd doesn't recognize --help export --help # Error: export doesn't recognize --help Use help instead help cd help export ``` Common Issues and Troubleshooting Issue 1: Help Command Not Available Problem: The `help` command returns "command not found." Cause: You're not using bash, or using a very old version. Solution: ```bash Check your current shell echo $SHELL Switch to bash if needed bash Verify bash version bash --version ``` Issue 2: No Help for External Commands Problem: `help ls` or `help grep` returns no information. Cause: These are external commands, not built-ins. Solution: ```bash Use man for external commands man ls man grep Or use --help option ls --help grep --help Identify command type first type ls type grep ``` Issue 3: Incomplete or Missing Help Text Problem: Some built-ins show minimal or no help information. Cause: Minimal bash installation or custom compilation. Solution: ```bash Try alternative documentation sources info bash man bash Check bash compilation options bash --version Install full bash documentation sudo apt-get install bash-doc # Debian/Ubuntu sudo yum install bash-doc # RHEL/CentOS ``` Issue 4: Help Output Too Long Problem: Help output scrolls off screen. Solution: ```bash Use pagination help cd | less help set | more Use short format help -s cd help -d set Redirect to file for later reading help set > set_help.txt ``` Issue 5: Pattern Matching Not Working Problem: `help 'p*'` doesn't show expected results. Cause: Shell expansion or quoting issues. Solution: ```bash Use proper quoting help 'p*' # Correct help p* # May not work as expected Escape special characters help \* # Show help for all commands ``` Issue 6: Permission or Access Issues Problem: Help command fails with permission errors. Cause: Restricted shell environment or damaged installation. Solution: ```bash Check shell restrictions echo $- Try different shell /bin/bash /bin/sh Verify file permissions ls -l $(which bash) ``` Best Practices and Professional Tips Efficient Help Usage Strategies 1. Quick Reference Workflow Develop a systematic approach to using help: ```bash Step 1: Identify command type type command_name Step 2: Use appropriate help source help built_in_command # For built-ins man external_command # For external programs command_name --help # For quick reference Step 3: Use specific help options help -s command_name # For syntax only help -d command_name # For brief description ``` 2. Integration with Daily Workflow Incorporate help usage into your regular command-line work: ```bash Create aliases for common help patterns alias helpall='help -s "*"' alias helpsearch='function _helpsearch() { help -d "$1"; }; _helpsearch' Use help before experimenting help set # Before modifying shell options help trap # Before setting up error handling help read # Before processing user input ``` 3. Documentation and Learning Use help for continuous learning: ```bash Daily learning routine help $(help | grep -o '\b[a-z][a-z]*\b' | shuf -n 1) Create personal reference files help set > ~/docs/bash_set_reference.txt help printf > ~/docs/bash_printf_reference.txt ``` Performance Optimization 1. Fast Access Patterns Optimize your help usage for speed: ```bash Use tab completion with help help # Shows available commands help ex # Completes to 'export' Combine with other tools efficiently help cd | grep -i option # Find specific information quickly help set | head -20 # Show just the beginning ``` 2. Memory Aids Create mental shortcuts for common help patterns: ```bash Remember the "big three" help options help -s # Synopsis (syntax) help -d # Description (brief) help -m # Manual (detailed) Common command categories help cd pwd dirs # Navigation help export set unset # Variables help if while for # Control flow ``` Advanced Integration Techniques 1. Scripting with Help Incorporate help into your scripts for self-documentation: ```bash #!/bin/bash show_usage() { echo "This script uses these built-ins:" help -s cd help -s read help -s export } Call show_usage when script is run with --help [[ "$1" == "--help" ]] && show_usage && exit 0 ``` 2. Help in Functions Create utility functions that combine help with other tools: ```bash Function to show help and examples explain() { local cmd="$1" echo "=== Help for $cmd ===" help "$cmd" 2>/dev/null || man "$cmd" 2>/dev/null || echo "No help available" echo echo "=== Type information ===" type "$cmd" } Function to search help text help_grep() { local pattern="$1" help -d "*" | grep -i "$pattern" } ``` 3. Educational Workflows Use help for teaching and learning: ```bash Create learning exercises learn_builtins() { local commands=(cd export set read printf) for cmd in "${commands[@]}"; do echo "=== $cmd ===" help -d "$cmd" echo "Try: help $cmd" echo done } ``` Professional Development Tips 1. Building Expertise Systematically explore built-in commands: ```bash List all built-ins help | grep -E '^\s*[a-z]' | awk '{print $1}' | sort Study one built-in per day TODAY_BUILTIN=$(help | grep -E '^\s*[a-z]' | awk '{print $1}' | sort | sed -n "$(date +%j)p") help "$TODAY_BUILTIN" ``` 2. Cross-Shell Compatibility Understand help differences across shells: ```bash Check shell-specific help bash -c 'help cd' # Bash help zsh -c 'help cd' 2>/dev/null # Zsh (may not work) dash -c 'help cd' 2>/dev/null # Dash (may not work) Use portable alternatives when needed man bash | grep -A 10 "cd \[" # Portable reference ``` 3. Documentation Standards Follow professional documentation practices: ```bash Document your scripts with built-in references Usage: Uses 'read' built-in (help read) Configuration: Uses 'export' built-in (help export) Error handling: Uses 'trap' built-in (help trap) ``` Integration with Other Documentation Tools Combining Help with Man Pages Create comprehensive documentation workflows: ```bash Function to show all available documentation show_all_help() { local cmd="$1" echo "=== Built-in help ===" help "$cmd" 2>/dev/null && echo || echo "Not a built-in" echo echo "=== Man page ===" man "$cmd" 2>/dev/null && echo || echo "No man page" echo echo "=== Info page ===" info "$cmd" 2>/dev/null && echo || echo "No info page" } ``` Help with Online Resources Integrate local help with online documentation: ```bash Function to open online bash manual bash_online() { local cmd="$1" echo "Local help:" help "$cmd" echo echo "For more information, visit:" echo "https://www.gnu.org/software/bash/manual/bash.html" } ``` Creating Personal Documentation Build your own reference system: ```bash Create comprehensive help database create_help_db() { local output_dir="$HOME/bash_help" mkdir -p "$output_dir" # Generate help for all built-ins for cmd in $(help | grep -oE '\b[a-z][a-z]*\b' | sort -u); do help "$cmd" > "$output_dir/${cmd}.txt" 2>/dev/null done echo "Help database created in $output_dir" } ``` Conclusion The shell `help` command is an indispensable tool for anyone working with the command line. Throughout this comprehensive guide, we've explored everything from basic usage to advanced integration techniques, providing you with the knowledge needed to leverage this powerful documentation system effectively. Key Takeaways 1. Built-in Focus: Remember that `help` is specifically designed for shell built-in commands, not external programs 2. Multiple Options: Utilize the various help options (`-s`, `-d`, `-m`) to get the right level of detail for your needs 3. Integration Strategy: Combine `help` with other documentation tools like `man` and `info` for comprehensive reference 4. Workflow Optimization: Incorporate help usage into your daily command-line workflow for continuous learning and improved productivity 5. Troubleshooting Awareness: Understand common issues and their solutions to avoid frustration when accessing help Next Steps To continue building your command-line expertise: 1. Practice Regularly: Make `help` usage a habit when encountering unfamiliar built-in commands 2. Explore Systematically: Work through the list of built-in commands methodically, learning one or two per week 3. Create References: Build your own documentation and reference materials based on your specific needs 4. Share Knowledge: Help others by sharing your understanding of built-in commands and help usage 5. Stay Updated: Keep your bash installation current to ensure access to the latest help information Final Recommendations The `help` command represents just the beginning of effective command-line documentation usage. As you become more proficient, consider exploring advanced topics such as: - Custom help function development - Integration with shell completion systems - Advanced pattern matching and filtering techniques - Cross-platform compatibility considerations - Automated documentation generation for your own scripts By mastering the `help` command and integrating it into your workflow, you'll significantly improve your command-line efficiency and reduce the time spent searching for syntax and usage information. The investment in learning these fundamentals will pay dividends throughout your career in system administration, software development, and general computing tasks. Remember that effective use of built-in help is not just about memorizing commands—it's about developing the skills and habits that make you a more capable and confident command-line user. The `help` command is always there when you need it, providing instant access to the information required to use bash built-ins effectively and efficiently.