[Question] What files should be listed in .gitignore ?

[tkamenoko]

berry generates many files and directories like .yarn/cache/*, .pnp.js. Some of them seem better to be ignored, but I don't know what to ignore.

There are no examples in https://github.com/github/gitignore , so we need .gitignore example for a project using berry .

[arcanis]

Edit: I moved the content of my previous comment to the website, which will now be the reference for this answer. What follows is slightly outdated.

---

• .yarn/plugins and .yarn/releases contain the Yarn releases used in the current repository (as defined by yarn set version). You will want to keep them versioned (this prevents potential issues if, say, two engineers use different Yarn versions with different features).
• .yarn/unplugged should likely always be ignored, since it may contain native builds
• .yarn/build-state.yml should likely be ignored as well, as it contains the build infos
  • If for some reason you version unplugged, it may make sense to keep build-state as well
• .yarn/cache may be ignored, but you'll need to run yarn install to regenerate it
  • Versioning it unlocks what we call Zero-Installs - it's optional, though
• .pnp.js (and potentially .pnp.data.json) are in the same boat as the cache. Add it to your repository if you keep your cache in your repository, and ignore it otherwise.
• yarn.lock should always be stored within your repository (even if you develop a library)

---

So to summarize:

If you're using Zero-Installs:

.yarn/unplugged
.yarn/build-state.yml

If you're not using Zero-Installs:

.yarn/*
!.yarn/releases
!.yarn/plugins
.pnp.*

[lecstor]

I don't think you'd want to ignore .yarn/plugins or .yarn/releases or you'll end up in a broken state where you have to delete .yarnrc.yml if you had plugins installed and run yarn policies set-version v2 to download the berry release.

[arcanis]

Good point! I've updated my post to reference those.

[bbugh]

This seems like it might be be out of date, my install process is generating more files than are mentioned here: .pnp/ and .yarnrc. I didn't find anything in the documentation about this, and everything else lead to this issue.

How should the .pnp/ folder and the .yarnrc be handled with .gitignore? Thanks!

[arcanis]

I moved the content of my previous comment to the website, which will now be the reference for this answer.

To answer you @bbugh, the v2 shouldn't generate a .pnp folder at all - it's probably something that got generated by Yarn v1 (it got replaced by .yarn in the v2). The .yarnrc* files are configuration files that should be stored in the project.

[devinrhode2]

Since the list of ignored files could keep changing, maybe there should be a .yarn/gitignore, .yarn/cache (check in for zero installs) and then a .yarn/git-track folders (which is exclusively things that SHOULD be checked into git). I'd imagine the .yarnrc could be tucked into the .yarn/git-track folder. Basically, the goal is to have the .gitignore'd files never change, OR, yarn could simply check the projects .gitignore file. Anyone doing zero-installs can manually remove .yarn/cache from the .gitignore file.

Yarn could conservatively introduce the gitignore folder, developers wouldn't have to update anything, but new developers could forever have gitignore settings like this:

.yarn/gitignore
.pnp.*

I think parsing the .gitignore file and having yarn keep it updated might be the best DX

[samrith-s]

I had a question along this as none of the guides I found so far speak about the .pnp folder I have. Do we ignore that? It has two sub-folders:

• externals
• unplugged

I am using zero-installs.

[arcanis]

The .pnp folder was just in v1. In v2 it's .yarn.

[samrith-s]

Ah ok, I think it might have been a residual folder left behind when I just used installConfig.pnp: true in v1. Deleted it and everything works fine. Thanks! :)

[evanrlong]

What if we use enableScripts: false? Is it then safe to version .yarn/unplugged and .yarn/build-state.yml or is it still best to not?

I'd love to move to Zero-Installs, but my project still has fsevents, nan, node-gyp, and term-size in .yarn/unplugged. It runs fine with scripts disabled though.

[evanrlong]

Ah looks like dependenciesMeta might be my friend here.

[bertho-zero]

I'm adapting my publish process to https://yarnpkg.com/features/release-workflow, should .yarn/versions be added to the list of not ignored directories ? I would say yes.

[merceyz]

@bertho-zero It already is https://yarnpkg.com/getting-started/qa/#which-files-should-be-gitignored

[bertho-zero]

Sorry, thanks for your response.

[beorn]

This seems to be a rather complicated setup (many rules, and different versions for pnp/non-pnp versions). It's not a great developer experience for what is "critical path" for people to onboard onto yarn2.

To improve the developer experience and increase adoption, wouldn't it be an idea to have a simpler file structure with only one ignore rule that would work for both pnp and non-pnp versions? E.g., something like .yarn/cache is ignored, everything else is not, and put anything that should be 'cached' into this dir.

[arcanis]

At the very least we certainly could move the install state file into a subdirectory and change the recommended gitignore into:

Without zero-install:

.yarn/cache
.yarn/local
.pnp.*

With zero-install:

.yarn/local

If someone wants to give it a hand, I think it's mostly updating the default configuration and updating the doc (and perhaps adding a test, that would be nice to prevent regressions).

[beorn]

Is there any danger in recommending the more complete .gitignore for all cases? It’s simpler to have “eternal” config - one less thing to worry about, one less friction/barrier, for people to move to zero-install, and one less thing to explain about .gitignore rules and yarn2.

…

On Apr 14, 2021, at 13:47, Maël Nison ***@***.***> wrote: At the very least we certainly could move the install state file into a subdirectory and change the recommended gitignore into: Without zero-install: .yarn/cache .yarn/local .pnp.* With zero-install: .yarn/local If someone wants to give it a hand, I think it's mostly updating the default configuration and updating the doc (and perhaps adding a test, that would be nice to prevent regressions). — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.

[arcanis]

There will always be two rules since the concept of zero-install is that you check-in more things in your repository for the benefit of running much less installs than before (sometimes even zero, depending on the dependencies). By necessity those are things that would otherwise be gitignored.

[beorn]

I see - makes sense. I guess another thought is whether the zero-install should be more “default" or not. If so, you could perhaps have a rule like this (assuming local and other things could be re-arranged cache/ or some other sub-dir): .yarn/cache and with zero-install exclude the directory that contains the stuff zero-install would also check in: .yarn/cache !.yarn/cache/modules It seems to communicate intent quite clearly. OR - control whether zero-install is used through a config setting that puts the "modules" inside of `.yarn/local/modules` or `.yarn/modules`.

[elliotdavies]

Just to note, https://next.yarnpkg.com/getting-started/qa#which-files-should-be-gitignored is missing a mention of build-state.yml (but it sounds like the same rules apply as with install-state.gz?)

[merceyz]

The build-state.yml file was moved into install-state.gz in #2574.
https://github.com/yarnpkg/berry/blob/f29676e2333e418a0ff59eb1e272788296c0f2af/CHANGELOG.md#300-rc1

[tranvansang]

Shouldn't there be some command line, like yarn help gitignore to show this list? Or printing these line when setting up yarn 2 version is also helpful.

Every time I setup a new repo with yarn 2, I have to google, jump to this thread, and then to the yarn website.

Also, why doesn't yarn make this simpler? I think about 2-3 lines in gitignore is perfect, the current gitignore is too complicated, hard to remember.

Which files should be gitignored?

If you're not using Zero-Installs:

If you don't know which (zero vs non-zero), choose THIS!

.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

If you're using Zero-Installs:

.yarn/*
!.yarn/cache
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

[fulldecent]

Can we please maintain an authoritative, single, not-bikeshedded answer in https://github.com/github/gitignore