## File: docs/commands/doctor.rst

.. _doctor:

Bash-it doctor
^^^^^^^^^^^^^^

If you encounter problems with any part of Bash-it, run the following command:

.. code-block:: bash

   bash-it doctor

This will reload your bash profile and print out logs of various parts in Bash-it.
Note that this command at default will print all logs, including debug logs.
You can call it like this:

.. code-block:: bash

   bash-it doctor [errors/warnings/all]

In order to get wanted verbosity.

---

## File: docs/commands/index.rst

.. _commands:

Bash-it Commands
================

**Bash-it** boasts a wide range of available commands.
You should be familiar with them in order to fully utilize Bash-it.

.. toctree::
   :maxdepth: 1

   update
   search
   reload
   doctor
   profile

---

## File: docs/commands/profile.rst

.. _profile:

Bash-it Profile
---------------

Have you ever wanted to port your *Bash-it* configuration into another machine?

If you did, then ``bash-it profile`` is for you!

This command can save and load custom *"profile"* files, that can be later
used to load and recreate your configuration, in any machine you would like |:smile:|

When porting your configuration into a new machine, you just need to save your current profile, copy the resulting *"profile"* file, and load it in the other machine.

Example
^^^^^^^

.. code-block:: bash

     # Saves your current profile
     bash-it profile save my_profile
     # Load the default profile, which is the one used in the default installation.
     bash-it profile load default

     # Do whatever you want:
     # Disable stuff
     bash-it disable ...
     # Enable stuff
     bash-it enable ...
     # If you want to get back into your original configuration, you can do it easily
     bash-it profile load my_profile

---

## File: docs/commands/reload.rst

.. _reload:

Bash-it reload
^^^^^^^^^^^^^^

Bash-it creates a ``reload`` alias that makes it convenient to reload
your Bash profile when you make changes.

Additionally, if you export ``BASH_IT_AUTOMATIC_RELOAD_AFTER_CONFIG_CHANGE`` as a non-null value,
Bash-it will automatically reload itself after activating or deactivating plugins, aliases, or completions.

.. warning::
  When changing theme, do not use ``bash-it reload``. Instead, use :ref:`restart`.

.. _restart:

Bash-it restart
^^^^^^^^^^^^^^^

Similar to :ref:`reload`, ``bash-it restart`` can be used to restart your shell.
Instead of reloading your Bash profile, this command re-runs Bash (using exec).

This is stronger than simple reload, and is similar to the effect of closing and reopening your terminal.

---

## File: docs/commands/search.rst

.. _searching:

Bash-it search
--------------

If you need to quickly find out which of the plugins, aliases or completions are available for a specific framework, programming language, or an environment, you can *search* for multiple terms related to the commands you use frequently.
Search will find and print out modules with the name or description matching the terms provided.

Syntax
^^^^^^

.. code-block:: bash

     bash-it search term1 [[-]term2] [[-]term3]....

As an example, a ruby developer might want to enable everything related to the commands such as ``ruby``\ , ``rake``\ , ``gem``\ , ``bundler``\ , and ``rails``.
Search command helps you find related modules so that you can decide which of them you'd like to use:

.. code-block:: bash

   ❯ bash-it search ruby rake gem bundle irb rails
         aliases:  bundler rails
         plugins:  chruby chruby-auto ruby
     completions:  bundler gem rake

Currently enabled modules will be shown in green.

Searching with Negations
^^^^^^^^^^^^^^^^^^^^^^^^

You can prefix a search term with a "-" to exclude it from the results.
In the above example, if we wanted to hide ``chruby`` and ``chruby-auto``\ ,
we could change the command as follows:

.. code-block:: bash

   ❯ bash-it search ruby rake gem bundle irb rails -chruby
         aliases:  bundler rails
         plugins:  ruby
     completions:  bundler gem rake

Using Search to Enable or Disable Components
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By adding a ``--enable`` or ``--disable`` to the search command, you can automatically enable all modules that come up as a result of a search query.
This could be quite handy if you like to enable a bunch of components related to the same topic.

Disabling ASCII Color
^^^^^^^^^^^^^^^^^^^^^

To remove non-printing non-ASCII characters responsible for the coloring of the search output, you can set environment variable ``NO_COLOR``.
Enabled components will then be shown with a checkmark:

.. code-block:: bash

   ❯ NO_COLOR=1 bash-it search ruby rake gem bundle irb rails -chruby
         aliases  =>   ✓bundler ✓rails
         plugins  =>   ✓ruby
     completions  =>   bundler gem rake

---

## File: docs/commands/update.rst

.. _update:

Bash-it update
^^^^^^^^^^^^^^

To update Bash-it to the latest stable version, simply run:

.. code-block:: bash

   bash-it update stable

If you want to update to the latest dev version (directly from master), run:

.. code-block:: bash

   bash-it update dev

If you want to update automatically and unattended, you can add the optional
``-s/--silent`` flag, for example:

.. code-block:: bash

   bash-it update dev --silent

.. _migrate:

Bash-it migrate
^^^^^^^^^^^^^^^

If you are using an older version of Bash-it, it's possible that some functionality has changed, or that the internal structure of how Bash-it organizes its functionality has been updated.
For these cases, we provide a ``migrate`` command:

.. code-block:: bash

   bash-it migrate

This command will automatically migrate the Bash-it structure to the latest version.
The ``migrate`` command is run automatically if you run the ``update``\ , ``enable`` or ``disable`` commands.

---

## File: docs/plans/bash-it-issues-comprehensive-analysis.md

# Bash-it Open Issues - Comprehensive Analysis & Action Plan
**Analysis Date**: 2025-10-05
**Last Updated**: 2025-10-07
**Total Open Issues**: 32 → 27 (5 fixed)
**Analyzed By**: Claude Code

---

## Executive Summary

Out of 32 open issues:
- **5 Quick Wins** - ✅ **ALL FIXED** (2025-10-07)
- **6 Require Your Decision** - 3 implemented, 3 still need input
- **18 Stale/Redundant** - Old issues (>2 years) that need closure decisions
- **3 Long-term Roadmap** - Strategic features for future planning

**Recent Progress**: 5 issues fixed in 1 day with PRs #2349, #2350, #2351, #2352, #2353
**Critical Finding**: 78% of issues are stale (>2 years old). Recommend aggressive issue gardening to improve project health.

---

## 1. QUICK WINS - ✅ ALL COMPLETED (5/5 issues)

### ✅ Issue #2317: Auto-infer remote name
**Status**: ✨ **FIXED** - PR #2345 created 2025-10-05
- Simple helper function to detect git remote name
- No more hardcoded "origin" assumption
- **Action**: None needed

### ⚡ Issue #2314: Interactive install fails for todo aliases
**Effort**: 5 minutes
**Status**: TODO - Still needs fixing
**Fix**: Rename `todo.txt-cli.aliases.bash` → `todo.aliases.bash`
- Clear bug, clear solution already identified in issue
- Just a file rename to match naming convention
- **Action**: Can be fixed next

### ✅ Issue #2296: down4me function broken
**Status**: ✨ **FIXED** - PR #2350 created 2025-10-07
- Fixed URL malformation when passing full URLs with protocols
- Strips http:// and https:// from input
- Uses `command` prefix to bypass aliases
- **Action**: None needed

### ✅ Issue #2260: SSH completion removes @ symbol
**Status**: ✨ **FIXED** - PR #2351 created 2025-10-07
- Removed @ from COMP_WORDBREAKS to preserve user@host format
- Now correctly completes ssh root@server instead of ssh rootserver
- **Action**: None needed

### ✅ Issue #2238: Uninstall script deletes bashrc incorrectly
**Status**: ✨ **FIXED** - PR #2352 created 2025-10-07
- Now backs up current config before restoring old backup
- Saves to ~/.bashrc.pre-uninstall.bak (or ~/.bash_profile.pre-uninstall.bak)
- Users can review and merge changes if needed
- **Action**: None needed

---

## 2. DECISION REQUIRED - Need Your Input (6 issues)

### ✅ Issue #2248: Add Laravel Artisan completion
**Status**: ✨ **IMPLEMENTED** - PR #2349 created 2025-10-07
- Added dynamic completion for Laravel artisan commands
- Works with both `artisan` and `art` aliases
- Only activates when artisan file exists in directory
- **Action**: None needed

### 🤔 Issue #2245: Add tmux -c completion
**Decision Needed**: Accept feature or close?
- Small enhancement to tmux completion
- **Question**: Accept incremental tmux improvements?
- **Recommendation**: Accept if clean PR submitted
- **Your Call**: Yes/No?

### ✅ Issue #2216: Show node version only in package.json directories
**Status**: ✨ **IMPLEMENTED** - PR #2353 created 2025-10-07
- Added NODE_VERSION_CHECK_PROJECT environment variable (default: false)
- When enabled, only shows node version in directories with package.json
- Fully backwards compatible (disabled by default)
- **Action**: None needed

### 🤔 Issue #2214: Do you need maintainers?
**Decision Needed**: Project governance
- Open question about adding maintainers
- **Action**: You need to respond about maintainer status/needs
- **Your Call**: Are you looking for co-maintainers?

### 🤔 Issue #1819: Package bash-it with package manager
**Decision Needed**: Distribution strategy
- Request to get bash-it into Homebrew, apt, etc.
- **Major effort** but would improve adoption
- **Question**: Is packaging worth the maintenance burden?
- **Your Call**: Worth pursuing or close?

### 🤔 Issue #825: Aliases shadowing program names
**Decision Needed**: Philosophy on aliases
- Some aliases override common commands (e.g., `ll`)
- **Question**: Should bash-it be more conservative with alias names?
- **Recommendation**: Document clearly, let users choose
- **Your Call**: Change default alias behavior or close?

---

## 3. STALE/REDUNDANT - Need Closure Decisions (18 issues)

These are all >2 years old with minimal activity. **Recommend closing most** with option to reopen if someone volunteers.

### 🗑️ Ancient Issues (>4 years old) - Recommend CLOSE

#### Issue #517 (2015): Plugin load times
- Created 9 years ago
- Generic performance concern, no specific action items
- **Recommendation**: Close - performance is acceptable now

#### Issue #825 (2016): Aliases shadowing programs
- Already listed above in "Decision Required"

#### Issue #922 (2017): Support for enhancd
- 7 years old, labeled "seems abandoned"
- External tool integration request
- **Recommendation**: Close - no activity, unclear if still needed

#### Issue #1053 (2017): Evaluate kcov code coverage
- 7 years old, technical improvement
- **Recommendation**: Close - we use BATS now, coverage not critical

#### Issue #1207 (2018): Prompt wrap-around glitches
- 6 years old, prompt theme visual bugs
- **Recommendation**: Close - likely fixed in modern terminals, needs repro

### 🗑️ Old Issues (2-4 years) - Recommend CLOSE unless someone volunteers

#### Issue #1640 (2020): Cleanup "base" and "general"
- Vague organizational request
- **Recommendation**: Close - or convert to specific actionable issue

#### Issue #1680 (2020): Add documentation for all commands
- Massive undertaking, no volunteers
- **Recommendation**: Close - accept incremental doc improvements instead

#### Issue #1693 (2020): todo plugin doesn't use $TODO variable
- Related to #2314 (todo aliases)
- **Recommendation**: Close as duplicate or fix alongside #2314

#### Issue #1696 (2020): Help us clean up Bash-it!
- Meta tracking issue for cleanup
- **Recommendation**: KEEP OPEN - useful for coordinating cleanup efforts
- **Action**: Update with current status (pre-commit hooks working!)

#### Issue #1818 (2021): Moving external libraries to vendor/
- Technical debt cleanup
- **Recommendation**: Close - already done, verify and close

#### Issue #1943 (2021): Performance of bash-preexec DEBUG trap
- Performance concern about DEBUG trap
- **Recommendation**: Close - needs reproduction, likely non-issue

#### Issue #2080 (2022): Structure all aliases
- Organizational improvement
- **Recommendation**: Close - too vague, accept specific alias improvements

#### Issue #2084 (2022): Platform dependent config file selection
- Question about macOS vs Linux config differences
- **Recommendation**: Close - working as designed, or needs specific fix proposal

#### Issue #2149 (2022): pyenv plugin breaks over SSH
- SSH + pyenv interaction issue
- **Recommendation**: Close - needs reproduction, likely user config issue

#### Issue #2150 (2022): Help information for preview command
- Documentation request
- **Recommendation**: Close - command is self-explanatory, or add quick docs

#### Issue #2174 (2022): System alias breaks completion
- Completion conflict with user's system alias
- **Recommendation**: Investigate - might be legit bug or user config issue

#### Issue #2184 (2022): Show plugin source URI
- Feature request for plugin metadata
- **Recommendation**: Close - not worth complexity, plugins are in repo

#### Issue #2197 (2023): bash-it preview not working
- Preview command bug
- **Recommendation**: Close - needs reproduction on current version

#### Issue #2202 (2023): Why does install add shebang to bash_profile?
- Question about install behavior
- **Recommendation**: Answer and close - likely incorrect assumption

### 🕐 Recent but inactive (1-2 years) - Investigate before closing

#### Issue #2254 (2024): Syntax error in alias_completion
- Bash syntax error in generated completion file
- **Recommendation**: Try to reproduce, fix or close

#### Issue #2264 (2024): Alias completion doesn't complete
- Already listed in Quick Wins above

#### Issue #2297 (2025): Powerline multiline SSH padlock miscalculation
- Recent bug (Mar 2025), active (Sept update)
- **Recommendation**: KEEP OPEN - legitimate bug, needs fix

---

## 4. LONG-TERM ROADMAP (3 issues)

### 📋 Issue #1696: Help us clean up Bash-it!
**Status**: Active coordination issue
- Good place to track pre-commit cleanup progress
- **Action**: Keep open, update regularly with progress
- **Next Steps**:
  - List remaining files not in `clean_files.txt`
  - Create "good first issue" labels for individual files

### 📋 Issue #1819: Package Bash-it with package managers
**Status**: Requires decision (see Decision Required section)
- Would significantly improve installation experience
- **Effort**: Epic (months)
- **Benefit**: High - easier adoption
- **Dependencies**: Need CI/CD, release process, semantic versioning

### 📋 Issue #1053: Code coverage with kcov
**Status**: Low priority technical improvement
- Would be nice to have coverage metrics
- **Effort**: Medium (weeks)
- **Benefit**: Low - we have tests, coverage is nice-to-have

---

## 5. WORK PLAN TO REDUCE TECH DEBT

### Phase 1: Immediate Wins ✅ COMPLETED (2025-10-07)
**All fixed without user input:**

1. ✅ Fix #2317 - Auto-detect git remote (PR #2345 - 2025-10-05)
2. ✅ Fix #2248 - Laravel artisan completion (PR #2349 - 2025-10-07)
3. ✅ Fix #2296 - down4me function URL malformation (PR #2350 - 2025-10-07)
4. ✅ Fix #2260 - SSH completion @ symbol (PR #2351 - 2025-10-07)
5. ✅ Fix #2238 - Improve uninstall script (PR #2352 - 2025-10-07)
6. ✅ Fix #2216 - Node version conditional display (PR #2353 - 2025-10-07)

**Remaining:**
- ⚡ Fix #2314 - Rename todo alias file (5 min)

**Total Completed**: 6 PRs, 5 issues can be closed once PRs merge

### Phase 2: Issue Gardening (Next Week)
**Need your approval, then I execute:**

1. Close stale issues (18 issues) with polite message:
   - "Closing due to age/inactivity. Please reopen with reproduction on latest version if still relevant."
2. Update #1696 (cleanup tracking) with current status
3. Label issues needing decisions with "needs-decision"
4. Label quick wins with "good-first-issue"

**Total Time**: 2 hours, 18 issues closed, improved issue hygiene

### Phase 3: Strategic Decisions (This Month)
**You decide, I can implement:**

1. **Decision**: Accept framework-specific completions? (#2248 Laravel)
2. **Decision**: Smart plugin behavior? (#2216 nvm auto-detect)
3. **Decision**: Need co-maintainers? (#2214)
4. **Decision**: Pursue packaging? (#1819)
5. **Decision**: Conservative aliases? (#825)

**Outcome**: Clear project direction, updated CLAUDE.md with decisions

### Phase 4: Continued Cleanup (Ongoing)
**Sustaining momentum:**

1. Continue `clean_files.txt` expansion
   - Current: ~50 files clean
   - Goal: All files pass pre-commit hooks
2. Add tests for bugs as they're fixed
3. Improve documentation incrementally
4. Monthly issue triage (close stale, label new)

---

## 6. RECOMMENDATIONS

### Critical Actions
1. ✅ **Fix Quick Wins** - 5 issues, 4 hours work, big impact
2. 🧹 **Close Stale Issues** - Improve project health, reduce noise
3. 🎯 **Make Strategic Decisions** - Give project clear direction

### Nice to Have
4. 📦 **Consider Packaging** - Would improve adoption significantly
5. 📚 **Incremental Docs** - Fix docs as you touch code
6. 🧪 **Coverage Tracking** - Low priority, would be nice

### Don't Do
- ❌ Don't try to fix all old issues - most are stale
- ❌ Don't accept vague feature requests - require specific proposals
- ❌ Don't feel bad closing old issues - it's healthy

---

## 7. WHAT I CAN DO WITHOUT YOUR HELP

### Completed (2025-10-07)
- [x] Fix #2317 - git remote auto-detect (PR #2345)
- [x] Fix #2248 - Laravel artisan completion (PR #2349)
- [x] Fix #2296 - down4me function (PR #2350)
- [x] Fix #2260 - SSH completion (PR #2351)
- [x] Fix #2238 - uninstall script (PR #2352)
- [x] Fix #2216 - node version conditional display (PR #2353)

### This Week
- [ ] Fix #2314 - todo alias rename
- [ ] Draft issue closure messages for stale issues
- [ ] Update #1696 with cleanup progress
- [ ] Identify next 10 files for `clean_files.txt`

### Ongoing
- [ ] Continue pre-commit cleanup (add files to clean_files.txt)
- [ ] Write tests for bugs I fix
- [ ] Improve docs as I work

---

## 8. WHAT I NEED FROM YOU

### Decisions Needed
1. **Close stale issues?** - Should I close the 18 stale issues (>2 years old)?
2. **Framework completions?** (#2248) - Accept Laravel/Artisan completion?
3. **Smart plugins?** (#2216) - Should nvm only show in Node projects?
4. **Maintainer status?** (#2214) - Are you seeking co-maintainers?
5. **Packaging?** (#1819) - Worth pursuing package manager distribution?
6. **Alias philosophy?** (#825) - Stay aggressive or be more conservative?

### Approval Needed
- Approve me to start making PRs for Quick Wins
- Approve mass closure of stale issues (with template message)

---

## 9. PROPOSED ISSUE CLOSURE TEMPLATE

For stale issues, I recommend this message:

```markdown
Closing this issue due to inactivity (2+ years old).

If this is still relevant, please:
1. Test with latest bash-it version
2. Provide reproduction steps
3. Reopen or create new issue with updated details

Thanks for your contribution to bash-it! 🎉
```

---

## 10. SUCCESS METRICS

### Short Term (1 month)
- [ ] 5+ Quick Win PRs merged
- [ ] 18 stale issues closed
- [ ] Open issue count < 15
- [ ] All open issues labeled and categorized

### Medium Term (3 months)
- [ ] 100+ files in `clean_files.txt` (currently ~50)
- [ ] All quick wins fixed
- [ ] Strategic decisions made and documented
- [ ] Issue response time < 1 week

### Long Term (6 months)
- [ ] All files pass pre-commit hooks
- [ ] < 10 open issues at any time
- [ ] Clear contribution guidelines
- [ ] Possibly: Package manager distribution

---

## APPENDIX: Issue Reference

### Quick Wins (6)
- #2317 ✅ Auto-detect git remote (PR #2345)
- #2248 ✅ Laravel artisan completion (PR #2349)
- #2296 ✅ down4me broken (PR #2350)
- #2260 ✅ SSH completion @ issue (PR #2351)
- #2238 ✅ Uninstall script issue (PR #2352)
- #2216 ✅ Smart nvm plugin (PR #2353)
- #2314 ⚡ Todo alias install failure (TODO)

### Decision Required (3 remaining)
- #2245 tmux completion
- #2214 Need maintainers?
- #1819 Package managers
- #825 Alias philosophy

### Stale/Close (18)
- #517, #825, #922, #1053, #1207 (Ancient >4yr)
- #1640, #1680, #1693, #1818, #1943, #2080, #2084, #2149, #2150, #2174, #2184, #2197, #2202 (Old 2-4yr)
- #2254 (Recent but needs repro)

### Keep Open (3)
- #1696 Cleanup tracking issue
- #2297 Powerline bug (recent, active)
- Any issues with recent activity or clear action items

---

## File: docs/plans/bash-it-quick-reference.md

# Bash-it Issue Analysis - Quick Reference
**Date**: 2025-10-05
**Updated**: 2025-10-07

## TL;DR

📊 **32 open issues** → **27 remaining** (5 fixed!)

### ✅ Completed (2025-10-07)
1. ✅ Fix #2317 - git remote detection (PR #2345)
2. ✅ Fix #2248 - Laravel artisan completion (PR #2349)
3. ✅ Fix #2296 - down4me function (PR #2350)
4. ✅ Fix #2260 - SSH completion (PR #2351)
5. ✅ Fix #2238 - uninstall script (PR #2352)
6. ✅ Fix #2216 - node version conditional (PR #2353)

### What's Left
- Fix #2314 - todo alias rename (5 min)

**Progress**: 6 PRs created, 5 issues closed (pending PR merge)

### What I Need From You

#### Decision 1: Close Stale Issues?
Close 18 issues that are 2+ years old with no activity?
- ✅ **Recommend YES** - Improves project health
- Template message: "Closing due to inactivity. Reopen if still relevant."

#### Decision 2: Framework Completions?
~~Accept Laravel/Artisan completions (#2248)?~~
- ✅ **DONE** - Implemented in PR #2349

#### Decision 3: Smart Plugins?
~~Should nvm plugin auto-detect Node projects (#2216)?~~
- ✅ **DONE** - Implemented in PR #2353 (opt-in via NODE_VERSION_CHECK_PROJECT)

#### Decision 4: Need Co-Maintainers?
Response to #2214 about project governance?
- ⚖️ **Your call** - Want help maintaining?

#### Decision 5: Package Managers?
Worth effort to get into Homebrew (#1819)?
- ⚖️ **Recommend YES** - Big UX improvement, modest effort

#### Decision 6: Alias Philosophy?
Be more conservative with aliases like `ll`? (#825)
- ⚖️ **Recommend NO** - Keep current, improve docs

---

## Issue Breakdown

### ✅ Fixed (6 completed)
- #2317: git remote (PR #2345)
- #2248: Laravel completion (PR #2349)
- #2296: down4me (PR #2350)
- #2260: SSH completion (PR #2351)
- #2238: uninstall script (PR #2352)
- #2216: Smart nvm (PR #2353)

### ⚡ Quick Fix Remaining (1)
- #2314: todo alias rename

### 🤔 Need Your Decision (4)
- #2245: tmux completion
- #2214: Maintainers
- #1819: Packaging
- #825: Alias philosophy

### 🗑️ Recommend Closing (18)
All are 2+ years old with no activity:
- #517, #922, #1053, #1207 (Ancient >4yr)
- #1640, #1680, #1693, #1818, #1943, #2080, #2084, #2149, #2150, #2174, #2184, #2197, #2202 (Old 2-4yr)
- #2254 (Needs repro)

### 📌 Keep Open (3)
- #1696: Cleanup tracking issue (still active)
- #2297: Powerline bug (recent, active)
- Any new issues with activity

---

## Recommended Action Plan

### This Week
1. I fix 5 quick win bugs
2. You review and approve stale issue closure
3. You make strategic decisions

### Next Week  
1. Close stale issues
2. Start pre-commit cleanup
3. Label remaining issues

### This Month
1. Continue code cleanup
2. Improve documentation
3. Monthly issue triage

---

## Files Created

1. `/tmp/bash-it-issues-comprehensive-analysis.md` - Full detailed analysis
2. `/tmp/bash-it-roadmap-2025.md` - 6-month technical debt reduction plan
3. `/tmp/bash-it-quick-reference.md` - This file (TL;DR version)
4. `/tmp/bash-it-open-issues.json` - Raw issue data

---

## Key Metrics

| Metric | Original | Now (2025-10-07) | After Phase 2 | Target |
|--------|----------|------------------|---------------|--------|
| Open Issues | 32 | 27 | 9 | <10 |
| Stale Issues | 25 | 25 | 0 | 0 |
| Quick Wins Done | 0 | 6 | 7 | 7 |
| Clean Files | ~50 | ~50 | ~100 | 400+ |
| PRs Created | 0 | 6 | 6+ | Ongoing |

---

## Next Action

**Status Update (2025-10-07)**:
- ✅ 6 Quick Win PRs created and ready for review
- ✅ Issues #2248 and #2216 implemented (were in "Decision" category)
- ⚡ 1 more quick fix remaining (#2314)

**Remaining Decisions**:
1. Approve stale issue closure?
2. Make strategic decisions (#2214, #1819, #825, #2245)?
3. Review and merge PRs #2345, #2349, #2350, #2351, #2352, #2353

---

## File: docs/plans/bash-it-roadmap-2025.md

# Bash-it Technical Debt Reduction Roadmap 2025
**Created**: 2025-10-05
**Last Updated**: 2025-10-07
**Owner**: Maintainers
**Goal**: Reduce open issues from 32 to <10, improve code quality to 100% pre-commit clean

---

## Current State Assessment

### Health Metrics (2025-10-07 Update)
- 📊 **Open Issues**: 32 → **27** (5 closed pending PR merge)
- 🧹 **Clean Files**: ~50 files in `clean_files.txt`
- ✅ **Pre-commit Coverage**: ~15% of codebase
- ⏰ **Stale Issues**: 78% (>2 years old) - **25 remaining**
- 🐛 **Active Bugs**: ~~5~~ **1** fixable quickly (4 fixed!)
- 🎯 **Issue Response Time**: Variable (some years old)
- 🚀 **PRs Created**: **6** in 2 days

### Technical Debt Categories
1. **Code Quality**: Many files don't pass shellcheck/shfmt
2. **Issue Backlog**: 25 stale issues creating noise
3. **Documentation**: Inconsistent, incomplete
4. **Testing**: Good BATS coverage, but could expand
5. **Distribution**: Manual install only, no package managers

---

## Phase 1: Quick Wins Sprint ✅ COMPLETED (2025-10-07)
**Goal**: Fix bugs, close issues, build momentum
**Effort**: 2 days, 6 PRs created

### Tasks
- [x] #2317: Auto-detect git remote (PR #2345 - 2025-10-05)
- [x] #2248: Laravel artisan completion (PR #2349 - 2025-10-07)
- [x] #2296: Fix down4me function (PR #2350 - 2025-10-07)
- [x] #2260: Fix SSH completion @ removal (PR #2351 - 2025-10-07)
- [x] #2238: Improve uninstall script (PR #2352 - 2025-10-07)
- [x] #2216: Node version conditional display (PR #2353 - 2025-10-07)
- [ ] #2314: Rename todo alias file (TODO - 5 min)

### Success Criteria
- ✅ 6 PRs created (awaiting review/merge)
- ✅ 5 issues can be closed (pending PR merge)
- ⏳ Tests included where applicable
- ✅ Clean git history, all linting passed

### Deliverables
- Working fixes for real user problems
- Test coverage for fixed bugs
- Updated documentation where needed
- Template for future quick-win sprints

---

## Phase 2: Issue Garden Cleanup (Week 3-4)
**Goal**: Reduce noise, improve project health
**Effort**: ~4 hours

### Strategy: Aggressive Stale Issue Closure
Close issues that are:
- >2 years old with no recent activity
- Vague feature requests with no volunteers
- Questions that were never answered
- Fixed but not closed
- No longer relevant

### Execution Plan
1. **Week 3**: Draft closure messages for each issue
2. **Get maintainer approval** on closure list
3. **Week 4**: Close issues with polite template message
4. **Add labels**: "stale-closed", "reopen-if-relevant"

### Issues to Close (18 total)
**Ancient** (>4 years, likely irrelevant):
- #517: Plugin load times (2015)
- #922: Support for enhancd (2017)
- #1053: Evaluate kcov coverage (2017)
- #1207: Prompt wrap-around (2018)

**Old** (2-4 years, no activity):
- #1640: Cleanup base/general
- #1680: Document all commands
- #1693: todo plugin $TODO variable
- #1818: Move libs to vendor
- #1943: preexec performance
- #2080: Structure aliases
- #2084: Platform config question
- #2149: pyenv over SSH
- #2150: Preview help
- #2174: System alias breaks completion
- #2184: Show plugin source URI
- #2197: Preview not working
- #2202: Install shebang question

**Recent but stale** (needs repro):
- #2254: Syntax error in completion

### Success Criteria
- ✅ Open issues reduced from 32 to <15
- ✅ All remaining issues labeled appropriately
- ✅ Clear "why closed" rationale for each
- ✅ Template for future issue gardening

---

## Phase 3: Strategic Decisions (Month 2)
**Goal**: Establish clear project direction
**Effort**: Discussion + documentation

### Decisions Required

#### 1. Framework-Specific Completions (#2248, #2245)
**Question**: Accept framework-specific completions (Laravel, etc.)?
**Options**:
- A) Accept all quality completions (grow features)
- B) Only popular/maintained frameworks (selective)
- C) Reject (keep bash-it focused)

**Recommendation**: Option B - Selective acceptance
- Require: Good tests, maintained upstream, popular (>10k stars)
- Reject: Niche frameworks, unmaintained, poor code quality

#### 2. Smart Plugin Behavior (#2216)
**Question**: Should plugins auto-detect context (e.g., nvm only in Node projects)?
**Options**:
- A) Add smart detection (better UX, more complexity)
- B) Keep simple (user configures, less magic)

**Recommendation**: Option B - Keep simple
- Document how users can add conditional logic themselves
- Avoid complexity in core plugins

#### 3. Maintainer/Governance (#2214)
**Question**: Need co-maintainers? How to govern?
**Options**:
- A) Seek co-maintainers (share workload)
- B) Stay solo (full control)
- C) Create contributor tiers (core + trusted)

**Recommendation**: Option C - Tiered contributors
- Core maintainer(s): Can merge to master
- Trusted contributors: Can label, triage issues
- Contributors: Submit PRs

#### 4. Package Manager Distribution (#1819)
**Question**: Worth effort to get into Homebrew, apt, etc.?
**Options**:
- A) Full packaging effort (Homebrew, apt, yum)
- B) Homebrew only (most requested)
- C) Git install only (current)

**Recommendation**: Option B - Homebrew first
- Create Homebrew formula (2-4 hours work)
- Improves adoption significantly
- Low maintenance once set up
- Defer other package managers until demand proven

#### 5. Alias Philosophy (#825)
**Question**: How aggressive with default aliases?
**Options**:
- A) Very conservative (no common command shadowing)
- B) Current approach (some shadowing, documented)
- C) More aggressive (convenience > safety)

**Recommendation**: Option B - Current + better docs
- Keep current aliases (many users depend on them)
- Add BIG WARNING in docs about ll, la, etc.
- Add `bash-it doctor --check-conflicts` command
- Let users decide (enable/disable)

### Outcome
- All decisions documented in CLAUDE.md
- Issues closed or converted to tracked work
- Clear contributor guidelines

---

## Phase 4: Pre-commit Expansion (Month 2-3)
**Goal**: Get 80%+ of files passing pre-commit hooks
**Effort**: ~20 hours spread over 6 weeks

### Current State
- `clean_files.txt` has ~50 entries
- Remaining: ~450 bash files need cleanup
- Pre-commit hooks: shellcheck, shfmt, trailing whitespace, etc.

### Strategy: Chip Away Weekly
- **Weekly goal**: Add 10 files to `clean_files.txt`
- **Prioritize**: Most-used files first (lib/, install.sh, bash_it.sh)
- **Batch fixes**: Group similar files (all themes, all plugins of type X)

### Target Files (Priority Order)
1. **Core** (Week 1-2):
   - bash_it.sh
   - scripts/reloader.bash
   - All files in lib/
   
2. **Install/Uninstall** (Week 3):
   - install.sh (partially done)
   - uninstall.sh

3. **Popular Plugins** (Week 4-5):
   - plugins/available/base.plugin.bash
   - plugins/available/git.plugin.bash
   - plugins/available/docker.plugin.bash
   - plugins/available/nvm.plugin.bash

4. **Themes** (Week 6-7):
   - Focus on most popular themes first
   - bobby, powerline, atomic, etc.

5. **Completions** (Week 8-9):
   - System completions
   - Popular tool completions

6. **Aliases** (Week 10+):
   - Lower priority (users can disable)
   - Fix as time permits

### Success Criteria
- ✅ 80% of files in `clean_files.txt`
- ✅ All core files (lib/, scripts/) clean
- ✅ Install scripts clean
- ✅ Top 10 plugins/themes clean

---

## Phase 5: Documentation Refresh (Month 3-4)
**Goal**: Improve docs incrementally as we work
**Effort**: ~10 hours

### Key Documentation Needs
1. **README.md**: Update with current state
2. **CONTRIBUTING.md**: Clear guidelines for PRs
3. **CLAUDE.md**: Document decisions, patterns
4. **Wiki**: Troubleshooting common issues

### Approach: Doc-as-you-go
- Fix bug → Update relevant docs
- Add feature → Update examples
- Close stale issue → Document decision

### Priority Docs
1. Pre-commit hook usage (for contributors)
2. Plugin development guide
3. Theme development guide
4. Troubleshooting guide
5. Performance optimization guide

---

## Phase 6: Testing Expansion (Month 4-5)
**Goal**: Increase test coverage for critical paths
**Effort**: ~15 hours

### Current Testing
- BATS framework in place
- Good coverage of core functionality
- Some plugins/completions lack tests

### Testing Priorities
1. **Core Functions**: lib/helpers.bash functions
2. **Bug Fixes**: Every bug fix gets a test
3. **Plugins**: At least smoke tests for all
4. **Completions**: Test completion generation

### Success Criteria
- ✅ All functions in lib/ have tests
- ✅ All fixed bugs have regression tests
- ✅ CI runs tests on every PR
- ✅ Test coverage >70%

---

## Phase 7: Packaging & Distribution (Month 5-6)
**Goal**: Get bash-it into Homebrew (if decision approved)
**Effort**: ~8 hours initial + ongoing maintenance

### Homebrew Formula Steps
1. Create formula in homebrew-core
2. Define installation steps
3. Add update mechanism
4. Add uninstall support
5. Submit PR to Homebrew

### Requirements
- Semantic versioning (start tagging releases)
- Stable release process
- Update mechanism (bash-it update needs to work)
- CI to test formula

### Success Criteria
- ✅ Homebrew formula accepted
- ✅ Users can `brew install bash-it`
- ✅ Formula auto-updates with releases
- ✅ Documented in README

---

## Success Metrics & KPIs

### Issue Health
| Metric | Current | 1 Month | 3 Months | 6 Months |
|--------|---------|---------|----------|----------|
| Open Issues | 32 | <15 | <10 | <10 |
| Stale Issues | 25 | 0 | 0 | 0 |
| Response Time | Variable | <1 week | <3 days | <3 days |
| Issues with Labels | 50% | 100% | 100% | 100% |

### Code Quality
| Metric | Current | 1 Month | 3 Months | 6 Months |
|--------|---------|---------|----------|----------|
| Clean Files | 50 | 100 | 250 | 400+ |
| Pre-commit Coverage | 15% | 30% | 60% | 80%+ |
| Shellcheck Pass | ~15% | ~30% | ~60% | 80%+ |
| Test Coverage | Good | Good | Better | 70%+ |

### Project Health
| Metric | Current | 1 Month | 3 Months | 6 Months |
|--------|---------|---------|----------|----------|
| Documentation | Fair | Good | Good | Excellent |
| Contributor Guidelines | Basic | Clear | Clear | Comprehensive |
| Distribution | Git only | Git only | Git only | + Homebrew |
| Active Contributors | Few | Growing | Growing | Community |

---

## Risk Management

### Risks & Mitigations

#### Risk: Closing issues angers contributors
**Mitigation**: 
- Polite closure messages
- Clear "reopen if relevant" policy
- Respond promptly to reopens

#### Risk: Pre-commit slows down contributors
**Mitigation**:
- Clear docs on running pre-commit
- Auto-fix where possible (shfmt -w)
- Allow incremental improvement

#### Risk: Feature decisions split community
**Mitigation**:
- Be transparent about reasoning
- Accept feedback, be willing to reverse
- Plugins are optional - defaults matter less

#### Risk: Packaging creates maintenance burden
**Mitigation**:
- Start with Homebrew only
- Automate release process
- Only pursue if demand is real

---

## Timeline Summary

```
Month 1: Quick Wins + Issue Cleanup
  Week 1-2: Fix 5 bugs
  Week 3-4: Close 18 stale issues

Month 2: Decisions + Pre-commit Start
  Week 5-6: Make strategic decisions
  Week 7-8: Clean core files

Month 3: Pre-commit Expansion
  Week 9-12: Add 40+ files to clean_files.txt

Month 4: Documentation + Testing
  Week 13-16: Improve docs, add tests

Month 5-6: Polish + Optional Packaging
  Week 17-20: Continue cleanup
  Week 21-24: Homebrew formula (if approved)
```

---

## Resource Requirements

### Time Investment
- **Maintainer**: 2-4 hours/week decision-making, review
- **Contributor(s)**: 4-8 hours/week implementation
- **Total**: ~6-12 hours/week for 6 months

### Skills Needed
- Bash scripting (existing)
- Testing with BATS (existing)
- Git workflow (existing)
- GitHub Actions (light, for packaging)
- Homebrew packaging (learn, ~4 hours)

---

## Next Steps

1. **Review this roadmap** with maintainer(s)
2. **Approve Phase 1** Quick Wins sprint
3. **Decide on stale issue closure** approach
4. **Make strategic decisions** (Phase 3)
5. **Start executing** week by week

---

## Questions for Maintainer

1. Approve Quick Wins sprint? (5 bug fixes)
2. Approve stale issue closure? (18 issues)
3. Which strategic decisions need discussion?
4. What's the priority: features vs. cleanup?
5. Interest in co-maintainers/trusted contributors?
6. Should I start Phase 1 immediately?