if config appears in project folder, configs in home directory can't be seen totally

[roneyrao]

Tell us about your environment
Linux version 3.6.32-431.11.2.el6.x86_64 (mockbuild@c6b8.bsys.dev.centos.org) (gcc version 4.4.7 20120313 (Red Hat 4.4.7-4) (GCC) ) #1 SMP Tue Mar 25 19:59:55 UTC 2014

• ESLint Version:
  v3.11.1

• Node Version:
  v7.2.0

• npm Version:
  3.10.9
  What parser (default, Babel-ESLint, etc.) are you using?
  espree
  Please show your full configuration:

in .eslintrc in ~/:
{
	"env":{
		"browser":true
		,"node":true
		,"es6":true
	}
	,"extends":"eslint:recommended"
}

-----------------------------------------------------------------------------------------------
the next cause problem(if removed works as expected):
-----------------------------------------------------------------------------------------------
in project directory:

either place the following in package.json:
eslintConfig:{}

or file .eslintrc with following content exists
{}

What did you do? Please include the actual source code causing the issue.

in app.js
const a=1;

What did you expect to happen?
config cascading and hierarchy take effect.

run: eslint --print-config app.js
long config list shows, with the same content with when no empty config appears in project folder;

run: eslint app.js
error 'a' is assigned a value but never used no-unused-vars

What actually happened? Please include the actual, raw output from ESLint.
run: eslint --print-config app.js
{
"globals": {},
"env": {},
"rules": {},
"parserOptions": {}
}

run: eslint app.js
error Parsing error: The keyword 'const' is reserved

[platinumazure]

Per the documentation, this behavior is intentional and working as designed.

Generally, it's better to just put your entire configuration in your project, because that way if you work with other people, you'll all have the same configuration in source control within the project directory.

If you want to avoid creating the same config for multiple projects, you can create a plugin or a shareable config and publish that to npm.

[roneyrao]

intentional? then what does "config cascading and hierarchy" mean sir?

[platinumazure]

It means that configurations in ancestor directories (relative to the location of the file to be linted) do get factored in as part of a cascade, except that a configuration in a user's home directory is special-cased to only be used if literally no other configuration is found. I'm not 100% sure what is supposed to happen if your project is in a descendant of your home directory, so that the home directory is also part of the ancestor directories.

As I said earlier, it usually makes more sense to have all of your config files in your project directory. If you rely on a configuration in your home directory and you start sharing a project on GitHub or similar, then part of the linting configuration you've been using won't get to any of your fellow collaborators and your codebase will become inconsistent.

[roneyrao]

Thank you for your patience.
Yes, it's a good practice to have all configs in project folder. I'm just confused by the docs at http://eslint.org/docs/user-guide/configuring, which says:

The configuration cascade works by using the closest .eslintrc file to the file being linted as the highest priority, then any configuration files in the parent directory, and so on. When you run ESLint on this project, all files in lib/ will use the .eslintrc file at the root of the project as their configuration. When ESLint traverses into the tests/ directory, it will then use your-project/tests/.eslintrc in addition to your-project/.eslintrc. So your-project/tests/test.js is linted based on the combination of the two .eslintrc files in its directory hierarchy, with the closest one taking priority. In this way, you can have project-level ESLint settings and also have directory-specific overrides.

what do you think?

[platinumazure]

@roneyrao Thanks for including a documentation snippet. The part you have emphasized is generally correct, except when one of the two .eslintrc files is in a home directory because that is intentionally given lowest priority. You may be right that the documentation could be made clearer.

Personally, though, I find it weird that the home directory .eslintrc is deprioritized when the home directory is actually an ancestor of your project directory. I wonder if it should be treated as a normal ancestor directory file, when the home directory is an ancestor of the project directory. Maybe only if the home directory is not an ancestor of the project directory should it be included as a fallback if literally no other configuration file is found.

@eslint/eslint-team Can anyone speak to what rationale we might have behind the current config cascade/resolution logic, where a home directory config file is ignored entirely even if the home directory is an ancestor of the project directory?

[roneyrao]

Yes, my project is a descendant of home. now, the two rules for 'home' and 'ancestor' collide. which one to choose, and even the 'home' rule itself, is better to placed in the docs, in case new comers get confused. Anyway, thanks for team's hard work!

[platinumazure]

@roneyrao No worries, thanks for your patience. I'm hoping my previous comment will pull in some team members who can explain the current logic. If we decide not to change the current logic, then we can make a documentation change.

Either way, this is no longer just a question, so I've relabeled the issue.

[ilyavolodin]

If I'm not mistaken, last one to change/rewrite config cascading logic (including home directory special case), was @btmills

[btmills]

It looks like this behavior has been around since the original commit that implemented the hierarchy. The specific case of a project within the home directory when the home directory contains a config file wasn't covered in the spec, which was an oversight on my part. Then in the implementation, @nzakas decided to exclude the home directory from traversal toward the root. It doesn't look like that distinction is documented anywhere. So which is the correct behavior in the case above? Should it include or exclude a home directory config as part of the root traversal for projects within the home directory?

[roneyrao]

The exclusion takes effect. The problem is that the docs doesn't mention that, so I considered it as a bug and filed this issue.
Personally I prefer no this exception.

[nzakas]

I think the current behavior is correct. the home directory is a special case because it can unintentionally affect a lot of projects (iirc this was an early complaint). I think changing that now would be confusing and possibly damaging to the current user base.

I'm all for updating the docs to make this special case clearer.

[simenbrekken]

I ran into this today as I attempted to run tests via Heroku CI which deploys your app's source to the home-directory of the user running the test. This causes any configuration cascade to fail without warning.

A project config is usually located at /Users/foo/my-project/.eslintrc or similar, but when deployed to Heroku this becomes ~/.eslintrc preventing cascading.

Would it be possible to allow ~/.eslintrc to be a valid target for cascading if the {root: true} option is present?

[ljharb]

That would break a lot of things if it's by default; I explicitly rely on root: true not cascading to ~/.eslintrc, all over the place.

[kaicataldo]

@ljharb I believe the accepted resolution here is to update the docs to make it clear that the home directory is a special case. I agree with others that this is too big a breaking change to introduce now.

[not-an-aardvark]

Closing because this was fixed in eca01ed.