bash-it Documentation

File: docs/commands/doctor.rst Copy Chapter

.. _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 Copy Chapter

.. _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 Copy Chapter

.. _profile:

Bash-it Profile Copy Chapter

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 Copy Chapter

.. _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 Copy Chapter

.. _searching:

Bash-it search Copy Chapter

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 Copy Chapter

.. _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 Copy Chapter

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 Copy Chapter

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) Copy Chapter

✅ Issue #2317: Auto-infer remote name Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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) Copy Chapter

✅ Issue #2248: Add Laravel Artisan completion Copy Section

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 Copy Section

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 Copy Section

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? Copy Section

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 Copy Section

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 Copy Section

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) Copy Chapter

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 Copy Section

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 Copy Section

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 Copy Section

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) Copy Chapter

📋 Issue #1696: Help us clean up Bash-it! Copy Section

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 Copy Section

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 Copy Section

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 Copy Chapter

Phase 1: Immediate Wins ✅ COMPLETED (2025-10-07) Copy Section

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) Copy Section

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) Copy Section

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) Copy Section

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 Copy Chapter

Critical Actions Copy Section

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 Copy Section

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 Copy Section

• ❌ 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 Copy Chapter

Completed (2025-10-07) Copy Section

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

This Week Copy Section

• 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 Copy Section

• 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 Copy Chapter

Decisions Needed Copy Section

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 Copy Section

• Approve me to start making PRs for Quick Wins
• Approve mass closure of stale issues (with template message)

9. PROPOSED ISSUE CLOSURE TEMPLATE Copy Chapter

For stale issues, I recommend this message:

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 Copy Chapter

Short Term (1 month) Copy Section

• 5+ Quick Win PRs merged
• 18 stale issues closed
• Open issue count < 15
• All open issues labeled and categorized

Medium Term (3 months) Copy Section

• 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) Copy Section

• All files pass pre-commit hooks
• < 10 open issues at any time
• Clear contribution guidelines
• Possibly: Package manager distribution

APPENDIX: Issue Reference Copy Chapter

Quick Wins (6) Copy Section

• #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) Copy Section

• #2245 tmux completion
• #2214 Need maintainers?
• #1819 Package managers
• #825 Alias philosophy

Stale/Close (18) Copy Section

• #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) Copy Section

• #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 Copy Chapter

Bash-it Issue Analysis - Quick Reference

Date: 2025-10-05
Updated: 2025-10-07

TL;DR Copy Chapter

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

✅ Completed (2025-10-07) Copy Section

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 Copy Section

• Fix #2314 - todo alias rename (5 min)

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

What I Need From You Copy Section

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 Copy Chapter

✅ Fixed (6 completed) Copy Section

• #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) Copy Section

• #2314: todo alias rename

🤔 Need Your Decision (4) Copy Section

• #2245: tmux completion
• #2214: Maintainers
• #1819: Packaging
• #825: Alias philosophy

🗑️ Recommend Closing (18) Copy Section

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) Copy Section

• #1696: Cleanup tracking issue (still active)
• #2297: Powerline bug (recent, active)
• Any new issues with activity

Recommended Action Plan Copy Chapter

This Week Copy Section

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

Next Week Copy Section

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

This Month Copy Section

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

Files Created Copy Chapter

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 Copy Chapter

Next Action Copy Chapter

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 Copy Chapter

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 Copy Chapter

Health Metrics (2025-10-07 Update) Copy Section

• 📊 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 Copy Section

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) Copy Chapter

Goal: Fix bugs, close issues, build momentum
Effort: 2 days, 6 PRs created

Tasks Copy Section

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

Success Criteria Copy Section

• ✅ 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 Copy Section

• 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) Copy Chapter

Goal: Reduce noise, improve project health
Effort: ~4 hours

Strategy: Aggressive Stale Issue Closure Copy Section

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 Copy Section

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) Copy Section

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 Copy Section

• ✅ 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) Copy Chapter

Goal: Establish clear project direction
Effort: Discussion + documentation

Decisions Required Copy Section

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 Copy Section

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

Phase 4: Pre-commit Expansion (Month 2-3) Copy Chapter

Goal: Get 80%+ of files passing pre-commit hooks
Effort: ~20 hours spread over 6 weeks

Current State Copy Section

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

Strategy: Chip Away Weekly Copy Section

• 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) Copy Section

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 Copy Section

• ✅ 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) Copy Chapter

Goal: Improve docs incrementally as we work
Effort: ~10 hours

Key Documentation Needs Copy Section

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 Copy Section

• Fix bug → Update relevant docs
• Add feature → Update examples
• Close stale issue → Document decision

Priority Docs Copy Section

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) Copy Chapter

Goal: Increase test coverage for critical paths
Effort: ~15 hours

Current Testing Copy Section

• BATS framework in place
• Good coverage of core functionality
• Some plugins/completions lack tests

Testing Priorities Copy Section

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 Copy Section

• ✅ 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) Copy Chapter

Goal: Get bash-it into Homebrew (if decision approved)
Effort: ~8 hours initial + ongoing maintenance

Homebrew Formula Steps Copy Section

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

Requirements Copy Section

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

Success Criteria Copy Section

• ✅ Homebrew formula accepted
• ✅ Users can brew install bash-it
• ✅ Formula auto-updates with releases
• ✅ Documented in README

Success Metrics & KPIs Copy Chapter

Issue Health Copy Section

Code Quality Copy Section

Project Health Copy Section

Risk Management Copy Chapter

Risks & Mitigations Copy Section

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 Copy Chapter

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 Copy Chapter

Time Investment Copy Section

• 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 Copy Section

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

Next Steps Copy Chapter

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 Copy Chapter

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?