A lightweight, POSIX-oriented shell implementation in C.
Features • Getting Started • Usage • Development • Documentation • License
C-Shell is a compact, educational shell implementation designed to demonstrate the core concepts of a POSIX shell. It bridges the gap between simple command runners and fully-featured shells like Bash or Zsh.
It is built with modern C standards (C23) and focuses on clean architecture, making it an excellent reference for understanding how shells work under the hood.
| Feature | Description |
|---|---|
| Interactive REPL | Robust command-line interface with prompt and input handling. |
| Line Editing | Arrow key navigation, history traversal, and basic editing. |
| Builtins | Essential commands: cd, pwd, echo, exit, type, history. |
| Pipelines | Connect commands via pipes: `cmd1 |
| Redirections | Full support for >, >>, 2>, 2>> file descriptors. |
| Tab Completion | Context-aware autocompletion for commands and paths. |
| Path Resolution | Executes external binaries found in your $PATH. |
Ensure you have the following installed:
- C Compiler: GCC or Clang (supporting C23 features)
- CMake: Version 3.20 or higher
- Build System: Ninja (recommended) or Make
-
Clone the repository
git clone https://github.com/yourusername/c-shell.git cd c-shell -
Configure and Build We recommend an out-of-source build using Ninja:
cmake -S . -B build -G Ninja cmake --build build -
Run the Shell
./build/c-shell
Once inside C-Shell, you can use it just like your standard terminal.
cd <dir>- Change the current working directory.pwd- Print the current working directory.echo [args...]- Display a line of text.type <name>- Display information about command type.history- View command history.exit- Exit the shell.
File Redirection
# Redirect output to a file
echo "Hello World" > hello.txt
# Append to a file
echo "Another line" >> hello.txt
# Redirect stderr
ls /non-existent 2> error.logPipelines
# Count files in current directory
ls | wc -l
# Search for a string in a file
cat README.md | grep "Shell"C-Shell/
├── src/ # Source code (*.c)
│ ├── builtins/
│ ├── completion/
│ ├── exec/
│ ├── history/
│ ├── line_edit/
│ ├── parser/
│ ├── path/
│ ├── redir/
│ ├── repl/
│ └── tokenizer/
├── include/ # Header files (*.h)
│ └── shell/
│ ├── builtins/
│ ├── completion/
│ ├── exec/
│ ├── history/
│ ├── line_edit/
│ ├── parser/
│ ├── path/
│ ├── redir/
│ ├── repl/
│ └── tokenizer/
├── tests/ # Unit and integration tests
├── docs/ # Documentation and design notes
├── scripts/ # Helper scripts for build/test
└── CMakeLists.txt # Build configuration
Note: Headers are now organized under include/shell/<component>/ and source files under src/<component>/. Top-level headers such as compat.h and context.h remain in include/shell/.
The project uses CTest for testing.
ctest --test-dir build --output-on-failureKeep the codebase clean using clang-format:
# Format all source files
git ls-files '*.c' '*.h' | xargs -r clang-format -style=file -iCheck the scripts/ directory for convenience wrappers:
./scripts/build.sh- Configure and build./scripts/run.sh- Run the shell./scripts/test.sh- Run the test suite./scripts/format.sh- Format tracked C sources (--checkto only detect changes)
For contribution workflow and PR guidance, see the Contributing Guide.
For deeper dives into the codebase:
- Architecture Overview - High-level design and component interaction.
- Implementation Notes - Step-by-step build guide and technical details.
- Contributing Guide - How to contribute, PR workflow, and formatting rules.
- Roadmap - Planned features and priorities.
This project was inspired by the CodeCrafters "Build your own Shell" roadmap — many thanks to the CodeCrafters team for the clear, practical guidance and exercises: https://app.codecrafters.io/courses/shell/overview
This project is licensed under the MIT License — see the LICENSE file for details.