brew doctor's purpose changed; how about a flag for devs vs users?

[cweekly]

Hi all, First let me say: Brew is a fantastic tool, and its developers are under-appreciated.

For years "brew doctor" was recommended (per brew's docs) as a means for users to keep their brew house clean. It seems that recently, its purpose changed from (A) let users clean house and proactively avoid problems / maintain a brew-friendly env, to (B) show developer-level detail of possible sources of issues

Would it serve the needs of everyone best, to simply add a flag like $ brew doctor --dev and/or $ brew doctor --user (or $ brew doctor --warnlevel 1

to distinguish between -- and support both of -- these legitimate uses? I guess that would imply managing multiple categories of warnings. Many programs have warn levels... as an end user it'd be nice to be able to turn down the default verbosity.

I do see the "if everything you're using homebrew for is working fine... just ignore them" message, but w/ brew responsible for so many critical programs on my system, it's disconcerting to see warnings.

I am raising this in response to the new warnings about Unbrewed header files in /usr/local/include, which are in fact, I believe, in my case, harmless.

Just a suggestion. In any case thank you very much, brew maintainers! Keep up the great work! :)

[HughP]

For these harmless headers (I have some too) Is there a way to suppress that particular warning?

[jacknagel]

This has been discussed before. Frankly, I don't think brew doctor that omits certain warnings is useful at all. Everywhere that we recommend running brew doctor would have to change to brew doctor --whatever. The goal is not to have no warnings, but to provide information that has proven useful in debugging issues.

[DomT4]

I do see the "if everything you're using homebrew for is working fine... just ignore them" message, but w/ brew responsible for so many critical programs on my system, it's disconcerting to see warnings.

One might suggest, politely, that this is more an issue with human nature than the code itself :smile_cat:. The code itself in several places says to ignore it unless you're having issues, but people aren't very good at that. (Most certainly not exempting myself from that).

[cweekly]

Of course it's human factors! But what are these tools for, if not for humans? It's easy to lose sight of that in working closer and closer to the metal, so to speak, but accounting for human nature -- and accommodating its oddities -- is what great software design is all about. [Tangent: this concept may help explain why Apple and Microsoft's fates took such radically different trajectories over the last decade.]

Simply put, it's annoying to have a great tool I rely on so heavily start rendering warnings I can't dismiss relating to things that aren't problems.

I'd politely suggest that providing an alternate mechanism for brew users (not its developers) to check for meaningful config problems, is a reasonable thing to ask. I know it's been discussed ad nauseum and don't blame jacknagel and others a bit for being sick of it. But please, understand, it's not an inability to read and grok the "it's probably ok to ignore these warnings". It's the open loop and dissonance created by a warning in a healthy system that chafes, for those of us who insist on warning-free status for all the other projects we in turn work on. "Live with it" is not a very empathic response. IMHO.

For all I care, call it $ brew clinic or $ brew quack, which (unlike the "real" doctor arg, supports ignoring specific harmless warnings as spec'd by the user)...

Please? I know I speak for a lot of other brew users.

Finally: again -- THANK YOU for such a great tool and your too-often thankless work maintaining it.

[DomT4]

Honestly, at least from my point of view, half the problem is here that plenty of people complain about this but nobody is prepared to put in the work to change it. (And that's not a personal dig. It's a broad comment).

Is there a high chance someone could spend an hour on this and then the maintainers go "Nope, we're not going down this path"? Sure, absolutely. But simply asking others to find the time to create a new function they neither like nor see how it'll be useful to debugging anything is a hasty way to maintain the status quo.

The maintainers are ridiculously busy people. Like, I cannot emphasize enough how often I grab one of them and they're on the plane, or they've just got off the plane, or they're going through the 10-20 new PRs created each day and offering helpful feedback, or going through issues and helping debug them. I understand that it can be frustrating having an idea brushed off or a discussion shut down because they've had it a hundred times before, but they do have good reasons for doing so.

I think it's probably fair to say that the $55 Homebrew gets a week in tips isn't exactly paying anyone's bills, alas. The team here is a small one, there's only 6 of them and Homebrew can often be a full-time job just day-to-day, let alone when someone pushes major changes that inevitably need feedback, dealing with unintentional fallout, etc etc.

If you want something to change, take a crack at it, propose code changes. You might get turned away, but I've yet to see any examples of the maintainers here flat-out refusing to look at, discuss & feedback on the changes someone has taken the time to make.

[MikeMcQuaid]

So, I have family who work in hospitals and one of the things avoided is scanning people. This is because because you know it something shows up on a scan, people get worried or diverted and actually it was just a distraction that has nothing to do with any problems the person may have.

brew doctor is similar; it should be used in debugging problems and not just run regularly or you will see things that may be irrelevant. What you are requesting is equivalent to saying "well, something weird showed up on a shoulder MRI: either I need surgery or you need to never scan my shoulder ever again".

There are two solutions to your problem:

• don't run brew doctor unless you have an issue and are posting troubleshooting information for us to debug for you
• remove those headers or install them somewhere else

I opt towards the latter; I have stuff in my PATH that I remove only when running Homebrew to avoid Homebrew warning or picking stuff up.

[cweekly]

@DomT4 thanks for the thoughtful reply. I have looked at the source. If I had more time I'd try to implement a ~/.brewignore containing a list of paths for /Library/Homebrew/cmd/doctor.rb to reference and thus supplement its whitelists, e.g.

def check_for_stray_headers
  white_list = [
    "fuse.h", # MacFuse
    "fuse/**/*.h", # MacFuse
    "macfuse/**/*.h", # OSXFuse MacFuse compatibility layer
    "osxfuse/**/*.h", # OSXFuse
  ]

  # perhaps this method's white_list could be merged with a putative, user-maintained ~/.brewignore
  # ... which could simply be a flat list appended to the very short array above?
  user_white_list = [
    # contents from user-managed ~/.brewignore file, e.g.:
    # (SOME_METHOD_TO_READ_FS_AND_LOCATE_DOT_BREWIGNORE HERE) #
    ## example contents:
      "/usr/local/include/tcl.h", # known-good include
      # or:
      "**/*.h" # I want to opt out of the stray_headers check.
    ## Maybe 'brew doctor' could run a *one-time* warning saying "if you have a .brewignore, remove it before submitting diagnostics"?
  ]

  __check_stray_files "/usr/local/include", "**/*.h", white_list, <<-EOS.undent
    Unbrewed header files were found in /usr/local/include.
    If you didn't put them there on purpose they could cause problems when
    building Homebrew formulae, and may need to be deleted.

    Unexpected header files:
  EOS
end

or similar?

@mikemcquaid I appreciate your reply too, and understand your POV. But I don't think your analogy holds water. It's important to get a baseline before making changes to any system. An important starting point for doing a brew update or making other changes on top of my brew-managed system, is to run brew doctor BEFORE the changes, and then again AFTER. If there is a difference, the new problem was clearly introduced by the change. To return to your analogy, this is more akin to the situation where I get routine (for me) bimonthly MRI scans looking for signs of recurrence of a brain tumor. Whatever shows up in the very first scan after radiation treatment is not necessarily indicative of a problem; but it's used as a baseline against which to compare subsequent MRIs. This is made easier (and less stressful for human beings) if the starting point is in fact a clean slate and not loads of "safe to ignore" markers.

The pseudocode above and these comments are the most I can spare for this, and since I want this change more than you guys want to implement it, it'll probably just remain closed. I don't feel like forking homebrew and hardcoding a broader white_list bc it's more ongoing maintenance to keep up to date. But my rational plea, and the large number of users who feel similarly, surely signal something meaningful here. Right?

In any case have a great day guys and thanks again for homebrew.

[MikeMcQuaid]

Thanks for your kind words. I think we've exhausted the topic here. Have a great day too!