A fully-functional Unix shell interpreter written in C, implementing bash-compatible functionality including command execution, I/O redirections, pipes, and environment variable expansion.

Grade: 100/100 | 42 School Core Curriculum | Team Project

Contributors:

• Alise (chilituna)
• Luis (Numbersdontlie)

Overview

Minishell is a collaborative systems programming project that recreates core shell functionality from scratch. The goal was to deepen understanding of low-level systems concepts—particularly process management, file descriptors, and inter-process communication—while building a feature-complete command interpreter.

The project demonstrates proficiency in designing complex systems, managing state across multiple subsystems, and implementing a multi-stage pipeline architecture (lexing → parsing → execution).

Demo / Screenshots

Tester validation run (showing the project passing the minishell_tester suite referenced below):

Tech Stack

Category	Technologies
Language	C (POSIX-compliant)
Build System	Make
CLI Library	GNU Readline
Systems APIs	Fork/Exec, Pipes, File Descriptors, Signals

Architecture / Implementation

The project follows a modular three-stage pipeline:

1. Parsing Subsystem (src/parsing/)

• Lexer: Tokenizes input, handles quote escaping, and identifies command boundaries
• Parser: Recursive descent parser builds abstract syntax tree (AST) with command nodes
• Expander: Substitutes environment variables and handles special characters
• Validators: Check syntax for quotes, redirections, and command structure

2. Execution Subsystem (src/exec/)

• Executor: Manages process creation, pipes, and file descriptor manipulation
• Redirections: Handles >, >>, < operators with proper file handling
• Heredoc: Implements << multi-line input with variable expansion
• Path Resolution: Locates executable files in $PATH environment variable

3. Built-in Commands (src/builtin/)

Implemented commands: cd, echo, env, export, unset, pwd, exit

4. Supporting Infrastructure (src/utils/, src/error_and_clean/)

• Memory management with comprehensive cleanup routines
• Error handling and user-friendly error messages
• Signal handlers for SIGINT and SIGQUIT

Key Technical Decisions

• Fork/Exec Model: Each external command spawns a child process, maintaining shell state integrity
• Modular Parser: Separate lexer and parser stages enable complex syntax handling
• Dynamic Allocations: Careful memory management with cleanup functions to prevent leaks
• Signal Handling: Non-blocking signal handlers preserve shell responsiveness

Features

• ✅ Command Execution: Run external programs and built-in commands with proper argument parsing
• ✅ Built-in Commands: cd, echo, env, export, unset, pwd, exit
• ✅ I/O Redirections: Input/output operators (>, >>, <) with file creation/truncation
• ✅ Pipes: Chain multiple commands with | operator
• ✅ Heredoc Support: Multi-line input strings with << operator and variable expansion
• ✅ Environment Variables: Full $VAR expansion and substitution
• ✅ Quote Handling: Single and double quotes with proper escape sequence processing
• ✅ Signal Handling: Clean interruption with Ctrl+C and Ctrl+\ without crashing
• ✅ Interactive Prompt: Command history and readline editing capabilities

Getting Started

Prerequisites

• Linux or macOS
• cc/clang
• make

Installation & Setup

# Clone the repository
git clone https://github.com/chilituna/minishell.git
cd minishell

# Build the project
make

# Run the shell
./minishell

Available Commands

# Build targets
make          # Compile the project
make clean    # Remove object files
make fclean   # Remove executable and object files
make re       # Full rebuild

# Run
./minishell   # Start interactive shell

Project Structure

minishell/
├── src/
│   ├── main.c                 # Entry point and REPL loop
│   ├── signals.c              # Signal handlers
│   ├── parsing/
│   │   ├── lexer.c            # Tokenization and input splitting
│   │   ├── parser.c           # AST construction
│   │   ├── expander.c         # Variable and special char expansion
│   │   └── ...                # Quote/redirection validation
│   ├── exec/
│   │   ├── executor.c         # Main command execution engine
│   │   ├── heredoc.c          # Multi-line input handling
│   │   ├── redirections.c     # File descriptor manipulation
│   │   └── ft_get_path.c      # $PATH resolution
│   ├── builtin/
│   │   └── ft_*.c             # Individual built-in commands
│   ├── error_and_clean/
│   │   └── ...                # Error handling & memory cleanup
│   └── utils/
│       └── ...                # Helper functions & data structures
├── includes/
│   └── minishell.h            # Main header file
└── Makefile                   # Build configuration

Development Approach

This project was developed using structured collaboration:

• Agile Methodology: Task-based development with Trello for project management
• Separation of Concerns: One developer focused on the parsing pipeline while the other owned the execution engine
• Iterative Development: Each feature was fully tested before moving to the next
• Version Control: Professional git workflow with meaningful commit messages
• Code Quality: Comprehensive testing, error handling, and edge case validation

Future Improvements

• 🔸 Job Control: Background processes with & operator and jobs/fg/bg commands
• 🔸 Advanced Redirections: Support for >&, <>, and file descriptors n>file
• 🔸 Command Substitution: $(command) and backtick syntax
• 🔸 Globbing: Wildcard expansion (*, ?, [...]) for current working directory
• 🔸 Logical Operators: && and || operators with parentheses for command priorities
• 🔸 History Persistence: Save command history across sessions
• 🔸 Aliases: Custom command abbreviations with alias command
• 🔸 Performance Optimization: Cache PATH lookups and optimize parsing

What I Learned

This project deepened my expertise in several critical areas:

• Systems Programming: Low-level process management, file descriptors, and signal handling
• Parser Design: Building a multi-stage pipeline (lexing, parsing, semantic analysis)
• Memory Safety: Careful allocation/deallocation patterns, leak detection, and resource cleanup
• Collaborative Development: Code organization across multiple developers, git workflows, and code reviews
• Software Architecture: Modular design, separation of concerns, and managing complex state machines
• Debugging Low-Level Code: Using tools like strace, valgrind, and gdb for systems debugging
• Edge Case Handling: Managing corner cases in shell semantics (quoting, variable expansion, signal safety)

Testing

The project has been validated against standard bash functionality. Recommended testing resources:

• minishell_tester — Comprehensive test suite (note: the banners or our minishell ft_print_banner and ft_print_exit need to be commented out)
• Manual testing against bash for compatibility

---

License

This project is licensed under the MIT License. See LICENSE for details.