Skip to content

Commit da4a8ed

Browse files
authored
Merge pull request #2341 from seefood/feature/doctor-summary-diagnostics
2 parents 8084cbb + 9b2fbb0 commit da4a8ed

File tree

3 files changed

+227
-36
lines changed

3 files changed

+227
-36
lines changed

.github/ISSUE_TEMPLATE/bug_report.yml

Lines changed: 17 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -36,48 +36,32 @@ body:
3636
Provide a link to a live example, or an unambiguous set of steps to reproduce this bug. Include code to reproduce, if relevant.
3737
validations:
3838
required: true
39-
- type: input
40-
attributes:
41-
label: Bash-it version
42-
placeholder: "How to get: bash-it version"
43-
validations:
44-
required: true
45-
- type: input
46-
attributes:
47-
label: List of enabled plugins, themes and aliases
48-
placeholder: "How to get: bash-it show plugins|themes|aliases (it is not a pipe)"
49-
validations:
50-
required: true
51-
- type: input
52-
attributes:
53-
label: Bash version
54-
placeholder: "How to get: bash --version"
55-
validations:
56-
required: true
57-
- type: input
58-
attributes:
59-
label: Operating system and version
60-
placeholder: "How to get: neofetch (or another command)"
61-
validations:
62-
required: true
6339
- type: textarea
6440
attributes:
65-
label: "bash-it doctor output"
41+
label: "Diagnostic Information"
42+
description: >
43+
**Please run `bash-it doctor` and paste the complete output below.**
44+
This single command provides all the diagnostic information we need including:
45+
bash-it version, enabled components, bash version, OS version, and configuration.
46+
placeholder: "Run: bash-it doctor"
6647
value: |
6748
```
68-
# How to get: bash-it doctor
49+
# Paste the output of: bash-it doctor
50+
51+
6952
```
7053
validations:
71-
required: false
54+
required: true
7255
- type: textarea
7356
attributes:
74-
label: Your ~/.bashrc
75-
value: |
76-
```bash
77-
# How to get: cat ~/.bashrc
78-
```
57+
label: "Additional Context (Optional)"
58+
description: >
59+
Any additional information that might help diagnose the issue.
60+
This could include specific error messages, relevant parts of your ~/.bashrc,
61+
or other configuration details not captured by `bash-it doctor`.
62+
placeholder: "Paste any additional relevant information here"
7963
validations:
80-
required: true
64+
required: false
8165
- type: textarea
8266
attributes:
8367
label: Notes

docs/README.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Stop polluting your `~/bin` directory and your `.bashrc` file, fork/clone Bash-i
2121
- [via Docker](https://bash-it.readthedocs.io/en/latest/installation/#install-using-docker)
2222
- [Updating](https://bash-it.readthedocs.io/en/latest/installation/#updating)
2323
- [Help](https://bash-it.readthedocs.io/en/latest/misc/#help-screens)
24+
- [Diagnostics](#diagnostics)
2425
- [Search](https://bash-it.readthedocs.io/en/latest/commands/search)
2526
- [Syntax](https://bash-it.readthedocs.io/en/latest/commands/search/#syntax)
2627
- [Searching with Negations](
@@ -54,10 +55,30 @@ If this is undesirable, you can create another file, by run the installer:
5455
BASH_IT_CONFIG_FILE=path/to/my/custom/location.bash ~/.bash_it/install.sh
5556
```
5657

58+
## Diagnostics
59+
60+
If you're experiencing issues with Bash-it or need to report a bug, use the built-in diagnostics tool:
61+
62+
```bash
63+
bash-it doctor
64+
```
65+
66+
This command provides a comprehensive summary including:
67+
- Environment information (OS, Bash version)
68+
- Bash-it version and update status
69+
- Configuration file locations and how Bash-it is loaded
70+
- List of enabled components (aliases, plugins, completions)
71+
72+
**When reporting bugs**, please include the full output of `bash-it doctor` in your issue report.
73+
74+
The doctor command can also help you update Bash-it - if you're behind the latest version and it's safe to update, you'll be prompted to merge the latest changes.
75+
5776
## Contributing
5877

5978
Please take a look at the [Contribution Guidelines](https://bash-it.readthedocs.io/en/latest/contributing) before reporting a bug or providing a new feature.
6079

80+
**When reporting bugs**, always run `bash-it doctor` and include its output in your issue report to help maintainers diagnose the problem quickly.
81+
6182
The [Development Guidelines](https://bash-it.readthedocs.io/en/latest/development) have more information on some of the internal workings of Bash-it,
6283
please feel free to read through this page if you're interested in how Bash-it loads its components.
6384

lib/helpers.bash

Lines changed: 189 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ function bash-it() {
7272
example '$ bash-it reload'
7373
example '$ bash-it restart'
7474
example '$ bash-it profile list|save|load|rm [profile_name]'
75-
example '$ bash-it doctor errors|warnings|all'
75+
example '$ bash-it doctor errors|warnings|all|summary'
7676
local verb=${1:-}
7777
shift
7878
local component=${1:-}
@@ -414,11 +414,197 @@ function _bash-it-doctor-errors() {
414414
_bash-it-doctor "${BASH_IT_LOG_LEVEL_ERROR?}"
415415
}
416416

417+
function _bash-it-doctor-summary() {
418+
_about 'shows a comprehensive diagnostic summary for bug reports'
419+
_group 'lib'
420+
421+
local component_type enabled_count enabled_list f component_name
422+
423+
# Color definitions
424+
local BOLD CYAN GREEN YELLOW RESET
425+
BOLD=$(tput bold 2> /dev/null || echo "")
426+
CYAN=$(tput setaf 6 2> /dev/null || echo "")
427+
GREEN=$(tput setaf 2 2> /dev/null || echo "")
428+
YELLOW=$(tput setaf 3 2> /dev/null || echo "")
429+
RESET=$(tput sgr0 2> /dev/null || echo "")
430+
431+
echo "${BOLD}${CYAN}Bash-it Doctor Summary${RESET}"
432+
echo "${CYAN}======================${RESET}"
433+
echo ""
434+
435+
# Environment Information
436+
echo "${BOLD}## Environment${RESET}"
437+
echo "${GREEN}OS:${RESET} $(uname -s) $(uname -r)"
438+
echo "${GREEN}Bash Version:${RESET} ${BASH_VERSION}"
439+
echo "${GREEN}Bash-it Location:${RESET} ${BASH_IT}"
440+
441+
# Check which config file is used
442+
local config_file
443+
if [[ -n "${BASH_IT_BASHRC:-}" ]]; then
444+
config_file="${BASH_IT_BASHRC}"
445+
elif [[ -f "${HOME}/.bashrc" ]]; then
446+
config_file="${HOME}/.bashrc"
447+
elif [[ -f "${HOME}/.bash_profile" ]]; then
448+
config_file="${HOME}/.bash_profile"
449+
else
450+
config_file="unknown"
451+
fi
452+
echo "${GREEN}Config File:${RESET} ${config_file}"
453+
echo ""
454+
455+
# Bash-it Version Information
456+
echo "${BOLD}## Bash-it Version${RESET}"
457+
pushd "${BASH_IT}" > /dev/null 2>&1 || {
458+
echo "Error: Cannot access Bash-it directory"
459+
return 1
460+
}
461+
462+
local current_commit current_tag commits_behind latest_tag commits_since_tag
463+
current_commit="$(git rev-parse --short HEAD 2> /dev/null || echo 'unknown')"
464+
current_tag="$(git describe --exact-match --tags 2> /dev/null || echo 'none')"
465+
466+
if [[ -z "${BASH_IT_REMOTE:-}" ]]; then
467+
BASH_IT_REMOTE="origin"
468+
fi
469+
470+
# Get version info relative to tags
471+
latest_tag="$(git describe --tags --abbrev=0 2> /dev/null || echo 'none')"
472+
commits_since_tag="$(git rev-list --count "${latest_tag}..HEAD" 2> /dev/null || echo '0')"
473+
474+
if [[ "${current_tag}" != "none" ]]; then
475+
echo "${GREEN}Current Version:${RESET} ${current_tag} (${current_commit})"
476+
elif [[ "${latest_tag}" != "none" && "${commits_since_tag}" != "0" ]]; then
477+
echo "${GREEN}Current Version:${RESET} ${latest_tag} +${commits_since_tag} (${current_commit})"
478+
else
479+
echo "${GREEN}Current Commit:${RESET} ${current_commit}"
480+
fi
481+
482+
# Check how far behind we are
483+
git fetch "${BASH_IT_REMOTE}" --quiet 2> /dev/null
484+
if [[ -z "${BASH_IT_DEVELOPMENT_BRANCH:-}" ]]; then
485+
BASH_IT_DEVELOPMENT_BRANCH="master"
486+
fi
487+
commits_behind="$(git rev-list --count HEAD.."${BASH_IT_REMOTE}/${BASH_IT_DEVELOPMENT_BRANCH}" 2> /dev/null || echo 'unknown')"
488+
489+
if [[ "${commits_behind}" == "0" ]]; then
490+
echo "${GREEN}Status:${RESET} Up to date with ${BASH_IT_REMOTE}/${BASH_IT_DEVELOPMENT_BRANCH}"
491+
elif [[ "${commits_behind}" != "unknown" ]]; then
492+
echo "${YELLOW}Status:${RESET} ${commits_behind} commits behind ${BASH_IT_REMOTE}/${BASH_IT_DEVELOPMENT_BRANCH}"
493+
494+
# Offer to update if behind and it's safe to do so
495+
local git_status untracked_files merge_base can_ff
496+
git_status="$(git status --porcelain 2> /dev/null)"
497+
untracked_files="$(echo "$git_status" | grep -c '^??' || true)"
498+
499+
# Check if we can fast-forward
500+
merge_base="$(git merge-base HEAD "${BASH_IT_REMOTE}/${BASH_IT_DEVELOPMENT_BRANCH}" 2> /dev/null)"
501+
can_ff=false
502+
if [[ "$(git rev-parse HEAD 2> /dev/null)" == "$merge_base" ]]; then
503+
can_ff=true
504+
fi
505+
506+
# Only offer merge if:
507+
# 1. No modified/staged files (untracked are OK)
508+
# 2. Can fast-forward OR no untracked files that would conflict
509+
if ! echo "$git_status" | grep -v '^??' -q; then
510+
if [[ "$can_ff" == "true" ]] || [[ "$untracked_files" == "0" ]]; then
511+
echo ""
512+
echo "Would you like to update now? This will merge ${BASH_IT_REMOTE}/${BASH_IT_DEVELOPMENT_BRANCH} into your current branch."
513+
read -r -p "Update? [y/N] " response
514+
case "$response" in
515+
[yY] | [yY][eE][sS])
516+
echo "Updating bash-it..."
517+
if git merge "${BASH_IT_REMOTE}/${BASH_IT_DEVELOPMENT_BRANCH}" --ff-only 2> /dev/null; then
518+
echo "✓ Successfully updated to latest version!"
519+
echo ""
520+
echo "Please restart your shell or run: source ~/.bashrc"
521+
else
522+
echo "✗ Fast-forward merge failed. Please run 'bash-it update' for a guided update."
523+
fi
524+
;;
525+
*)
526+
echo "Skipping update. You can update later with: bash-it update"
527+
;;
528+
esac
529+
else
530+
echo ""
531+
echo "Note: Cannot safely auto-update (untracked files may conflict). Use: bash-it update"
532+
fi
533+
else
534+
echo ""
535+
echo "Note: Cannot auto-update (uncommitted changes present). Use: bash-it update"
536+
fi
537+
fi
538+
539+
popd > /dev/null 2>&1 || true
540+
echo ""
541+
542+
# Bash-it Loading Configuration
543+
echo "${BOLD}## Bash-it Loading${RESET}"
544+
local config_files_to_check=()
545+
local config_file_path
546+
547+
# Check all common config files
548+
for config_file_path in "${HOME}/.bashrc" "${HOME}/.bash_profile" "${HOME}/.profile"; do
549+
[[ -f "$config_file_path" ]] && config_files_to_check+=("$config_file_path")
550+
done
551+
552+
if [[ ${#config_files_to_check[@]} -gt 0 ]]; then
553+
for config_file_path in "${config_files_to_check[@]}"; do
554+
if grep -i "bash.it\|bash_it" "$config_file_path" > /dev/null 2>&1; then
555+
echo "From ${config_file_path}:"
556+
grep -n -i "bash.it\|bash_it" -B2 -A2 "$config_file_path" 2> /dev/null
557+
echo ""
558+
fi
559+
done
560+
else
561+
echo "No config files found (.bashrc, .bash_profile, .profile)"
562+
fi
563+
564+
# Enabled Components Summary
565+
echo "${BOLD}## Enabled Components${RESET}"
566+
567+
# Process each component type
568+
for component_type in aliases plugins completion; do
569+
enabled_count=0
570+
enabled_list=()
571+
572+
# Get singular form for display
573+
local display_type="${component_type}"
574+
if [[ "$component_type" == "aliases" ]]; then
575+
display_type="Aliases"
576+
elif [[ "$component_type" == "plugins" ]]; then
577+
display_type="Plugins"
578+
else
579+
display_type="Completions"
580+
fi
581+
582+
# Count and collect enabled components
583+
for f in "${BASH_IT?}/$component_type/available"/*.*.bash; do
584+
[[ -f "$f" ]] || continue
585+
component_name="$(_bash-it-get-component-name-from-path "$f")"
586+
if _bash-it-component-item-is-enabled "$f"; then
587+
enabled_list+=("$component_name")
588+
((enabled_count++))
589+
fi
590+
done
591+
592+
# Display the summary with colors
593+
if [[ $enabled_count -eq 0 ]]; then
594+
printf '%s%s%s (%s): %s\n' "$CYAN" "$display_type" "$RESET" "$enabled_count" "${YELLOW}none${RESET}"
595+
else
596+
printf '%s%s%s (%s): %s\n' "$CYAN" "$display_type" "$RESET" "$enabled_count" "${enabled_list[*]}"
597+
fi
598+
done
599+
echo ""
600+
echo "${YELLOW}Tip:${RESET} To copy this report: ${CYAN}bash-it doctor${RESET} | pbcopy (macOS) or xclip (Linux)"
601+
}
602+
417603
function _bash-it-doctor-() {
418-
_about 'default bash-it doctor behavior, behaves like bash-it doctor all'
604+
_about 'default bash-it doctor behavior, shows component summary'
419605
_group 'lib'
420606

421-
_bash-it-doctor-all
607+
_bash-it-doctor-summary
422608
}
423609

424610
function _bash-it-profile-save() {

0 commit comments

Comments
 (0)