# Linux Workspace - Project Documentation

## Overview

**Linux Workspace** is a comprehensive shell configuration and utility toolkit designed to quickly configure new Linux machines with development tools, environment initialization, and useful utility scripts. It provides a modular, source-able bootstrap system for both bash and fish shells.

This is a **dotfiles & configuration management system** combined with a rich collection of utility scripts for system administration, development workflows, and daily convenience tasks.

## Quick Start

### Installation

```bash
# Clone the repository
git clone <repository-url> ~/linux-workspace

# Run the installer
cd ~/linux-workspace
./install.sh
```

The installer automatically:

- Detects the workspace directory location
- Adds sourcing configuration to `~/.bashrc`
- Creates Fish shell configuration at `~/.config/fish/conf.d/lws.fish`

### Manual Installation

Add to your `~/.bashrc`:

```bash
source /path/to/linux-workspace/bashrc
```

## Project Structure

### Root Files

- [bashrc](bashrc) - Main bootstrap file that initializes the entire workspace
- [fishrc](fishrc) - Fish shell configuration entry point
- [functions.sh](functions.sh) - Core utility functions used throughout the system
- [install.sh](install.sh) - Installation script for automated setup
- [.editorconfig](.editorconfig) - EditorConfig formatting standards

### Key Directories

#### [bin/](bin/) - Utility Scripts & Tools (45+ scripts)

Collection of executable shell and Python scripts for various tasks:

**Docker & Containers:**

- [dcm](bin/dcm) - Advanced Docker Compose manager with dependency and health check features
- [docker-bridge](bin/docker-bridge), [docker-noroot](bin/docker-noroot) - Docker helpers

**Development Tools:**

- [gws](bin/gws) - Gradle wrapper shortcuts for Kotlin development
- [git-dif1](bin/git-dif1), [git-swl](bin/git-swl), [git-reset-master](bin/git-reset-master) - Git workflow utilities

**System Utilities:**

- [network-bandwidth](bin/network-bandwidth), [myip](bin/myip), [weather](bin/weather) - System info
- [lock-screen](bin/lock-screen), [suspend.sh](bin/suspend.sh), [battery](bin/battery) - System control
- [cs.sh](bin/cs.sh), [cheatsheet](bin/cheatsheet) - Cheatsheet lookup tools

**Cloud & Infrastructure:**

- [aws-login](bin/aws-login) - AWS authentication helper
- [vpn-home.sh](bin/vpn-home.sh) - VPN configuration

**Remote Tools:**

- [xmosh](bin/xmosh), [xcat](bin/xcat), [xvim](bin/xvim) - Remote execution helpers

#### [rc/](rc/) - Shell Configuration Modules (23 files)

Modular initialization scripts loaded during shell startup:

**Core Setup:**

- [01-init.fish](rc/01-init.fish) - Fish shell initialization
- [01-path.sh](rc/01-path.sh) - PATH initialization
- [02-aliases.sh](rc/02-aliases.sh) - Common command aliases
- [env.sh](rc/env.sh) - Environment variables (PAGER, EDITOR, MANPAGER)
- [bash-prompt.sh](rc/bash-prompt.sh) - Colored bash prompt

**Language/Framework Initialization:**

- [nvm.sh](rc/nvm.sh) - Node Version Manager
- [pyenv.sh](rc/pyenv.sh) - Python environment manager
- [cargo.sh](rc/cargo.sh) - Rust Cargo
- [dotnet.sh](rc/dotnet.sh) - .NET runtime
- [sdkman.sh](rc/sdkman.sh) - SDKMAN Java/Kotlin tooling
- [linuxbrew.sh](rc/linuxbrew.sh) - Homebrew for Linux

**Development Tools:**

- [ssh-agent.sh](rc/ssh-agent.sh) - SSH agent with WSL support
- [git-prompt.sh](rc/git-prompt.sh) - Git prompt decoration
- [direnv.sh](rc/direnv.sh) - Directory environment switching
- [docker.sh](rc/docker.sh) - Docker initialization
- [kubernetes.sh](rc/kubernetes.sh) - kubectl/k8s setup
- [claude-code.sh](rc/claude-code.sh) - Claude Code integration

**Other Tools:**

- [gocryptfs.sh](rc/gocryptfs.sh) - Encrypted filesystem
- [thefuck.sh](rc/thefuck.sh) - Command correction
- [enhancd.sh](rc/enhancd.sh) - Directory navigation enhancement

#### [install/](install/) - Installation Scripts (24 files)

Automated setup scripts for various tools:

**Development:**

- [git-prompt.sh](install/git-prompt.sh), [awscli.sh](install/awscli.sh)
- [docker-ce.sh](install/docker-ce.sh), [docker-compose-2.sh](install/docker-compose-2.sh)
- [go-tools.sh](install/go-tools.sh), [rust.sh](install/rust.sh)
- [npm.sh](install/npm.sh), [uv.sh](install/uv.sh)

**Services:**

- [k3s.sh](install/k3s.sh) - Lightweight Kubernetes
- [lazygit.sh](install/lazygit.sh) - Git UI
- [syncthing.sh](install/syncthing.sh) - File synchronization

**Applications:**

- [packages.sh](install/packages.sh) - Debian packages
- [sublime.sh](install/sublime.sh), [vivaldi.sh](install/vivaldi.sh)
- [pwsh.sh](install/pwsh.sh) - PowerShell

#### [scripts/](scripts/) - Helper Scripts (16 files)

Administrative and one-off scripts:

- [git-config.sh](scripts/git-config.sh) - Git user/email configuration
- [bash-template.sh](scripts/bash-template.sh) - Script template
- [gnome-configuration.sh](scripts/gnome-configuration.sh) - GNOME settings automation
- [gradle-init-kotlin.sh](scripts/gradle-init-kotlin.sh) - Gradle Kotlin project setup
- [update-desktop-apps.sh](scripts/update-desktop-apps.sh) - Application updates

#### [doc/](doc/) - Documentation (21 files)

Reference guides and cheatsheets:

- [bash.md](doc/bash.md) - Bash scripting guide
- [git.md](doc/git.md) - Git workflows
- [vim.md](doc/vim.md) - Vim editor tips
- [cheatsheet.md](doc/cheatsheet.md) - General commands
- [fzf.md](doc/fzf.md) - Fuzzy finder
- [kotlin-coding-guideline.md](doc/kotlin-coding-guideline.md) - Kotlin style guide
- [gnome.md](doc/gnome.md) - GNOME customization

#### [conf/](conf/) - Configuration Files

- [gnome-shortcuts.conf](conf/gnome-shortcuts.conf) - Keyboard shortcuts
- [gradle.properties](conf/gradle.properties) - Gradle build config
- [wsl.conf](conf/wsl.conf) - WSL settings
- [wg-home.conf](conf/wg-home.conf) - WireGuard VPN
- [packages.txt](conf/packages.txt) - Recommended Debian packages
- [applications/](conf/applications/) - Application configs
- [dircolors/](conf/dircolors/) - Directory coloring schemes
- [vim/](conf/vim/) - Vim configurations

#### [src/](src/) - Source Projects

- [battery/](src/battery/) - Python project for reading notebook battery information

## Key Features

### Bootstrap System

- **Single-entry point**: [bashrc](bashrc) sources [functions.sh](functions.sh) and loads all `.sh` files from `rc/`
- **Modular design**: Each tool has its own configuration file
- **Performance optimization**: `LWS_FAST=1` environment variable for fast initialization
- **Debug mode**: `LWS_DEBUG=1` for troubleshooting
- **Reloadable**: `reload-workspace` alias to refresh configuration

### Core Functions

The [functions.sh](functions.sh) file provides essential utilities:

- `append_path()`, `prepend_path()` - PATH manipulation with duplicate prevention
- `source_directory()`, `source_directory_sh()` - Smart recursive sourcing
- `is_fast_init()`, `is_slow_init()` - Performance-based initialization
- `can_run()`, `is_alias()` - Command availability checks
- `is_wsl()` - Windows Subsystem for Linux detection
- `xlog()` - Conditional debug logging

### Common Aliases

Defined in [rc/02-aliases.sh](rc/02-aliases.sh):

- Directory: `ll`, `la` (enhanced listing)
- Docker: `dc` (docker-compose), `dcl` (logs)
- Navigation: `..`, `...`, `....`, `cdd` (Downloads)
- Time: `now`, `nowsql`, `sqldate`
- Kubernetes: `kl`, `kld`, `klg`
- System: `ssha` (ssh-agent)

### SSH Agent Integration

The [rc/ssh-agent.sh](rc/ssh-agent.sh) module provides:

- **WSL-aware**: Special handling for Windows Subsystem for Linux
- **Multi-key support**: Checks for both id_ecdsa and id_rsa
- **Auto-start**: Automatically starts ssh-agent if not running
- **Keychain fallback**: Uses keychain for non-WSL systems

### Docker Integration

The [bin/dcm](bin/dcm) script offers advanced Docker Compose management:

- Service dependency tracking
- Health check polling (HTTP, TCP, Redis, etc.)
- Parallel builds
- Logging filtering
- Service startup orchestration

### Gradle Integration

The [bin/gws](bin/gws) tool provides shortcuts for common Gradle tasks:

- Build shortcuts: `c` (clean), `b` (build), `t` (test)
- Combined: `cb` (clean+build), `cbt` (clean+build+test)
- Skip options: `-nd` (no detekt), `-nt` (no tests)
- Java-specific: `jar` (shadowJar), `br` (bootRun)

## Environment Variables

### Core Variables

- `$LWS` - Root directory of Linux Workspace
- `$WORKSPACE` - Alias for LWS

### Configuration Flags

- `LWS_DEBUG=1` - Enable debug logging
- `LWS_FAST=1` - Fast initialization (skip slow tools)

### Tool Customization

- `DC`, `DCF` - Docker Compose customization
- `EDITOR` - Default text editor
- `PAGER` - Default pager (less)

## Important Commands

- `reload-workspace` - Reload all configurations
- `clws` - Change directory to workspace
- `dcm` - Docker Compose manager
- `gws` - Gradle wrapper shortcuts

## Configuration Strategy

The project uses an **environment-first** approach:

1. **Staged initialization**: Tools load based on `LWS_FAST` flag
2. **Conditional loading**: Tools only initialize if directories exist
3. **WSL detection**: Special paths and behaviors for Windows Subsystem for Linux
4. **Path deduplication**: Removes duplicate PATH entries
5. **EditorConfig standardization**: Consistent coding standards

## Use Cases

1. **Rapid environment setup** for new Linux machines
2. **Consistent shell configuration** across multiple systems
3. **Development tool management** (Node, Python, Rust, Go, Java)
4. **Docker/Kubernetes workflows** with helper utilities
5. **Git workflow automation**
6. **System administration** utilities and scripts
7. **Personal workspace customization** with modular components

## Customization

### Adding New Modules

1. Create a new `.sh` file in [rc/](rc/)
2. Add your configuration or aliases
3. Reload with `reload-workspace`

### Adding New Scripts

1. Create executable script in [bin/](bin/)
2. Make it executable: `chmod +x bin/yourscript`
3. Script is automatically available in PATH

### Disabling Modules

Move unwanted modules from [rc/](rc/) to [rc.available/](rc.available/)

## Dependencies

The workspace intelligently detects and initializes available tools:

- **Required**: bash, git
- **Optional**: docker, kubectl, nvm, pyenv, cargo, direnv, etc.
- **Detection**: Each module checks for tool availability before initialization

## WSL Support

Special handling for Windows Subsystem for Linux:

- SSH agent integration with Windows
- Path adjustments for Windows interoperability
- WSL-specific configurations in [conf/wsl.conf](conf/wsl.conf)

## Performance

- **Fast mode**: Set `LWS_FAST=1` to skip heavy initializations
- **Lazy loading**: Tools only load when directories exist
- **Optimized PATH**: Deduplication prevents PATH bloat

## Contributing

This is a personal workspace configuration, but improvements are welcome:

1. Follow existing naming conventions
2. Keep scripts modular and self-contained
3. Test on fresh installations
4. Document new features in appropriate [doc/](doc/) files

## License

Personal project - use and modify as needed for your own workspace.

## Recent Changes

- Installation script improvements
- Enhanced `ll` and `la` aliases
- SSH agent fixes for WSL
- Fish shell integration
- Addition of new tools (Claude Code, Gemini CLI)

## Support

For issues or questions, refer to the documentation in [doc/](doc/) or examine the relevant configuration files in [rc/](rc/).