Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
tkamenoko opened this issue Sep 11, 2019 · 21 comments
Closed

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

tkamenoko opened this issue Sep 11, 2019 · 21 comments

Comments

@tkamenoko
Copy link
Contributor

@tkamenoko tkamenoko commented Sep 11, 2019

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
Copy link
Member

@arcanis arcanis commented Sep 11, 2019

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.*

@arcanis arcanis closed this as completed Sep 11, 2019
@lecstor
Copy link

@lecstor lecstor commented Sep 13, 2019

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
Copy link
Member

@arcanis arcanis commented Sep 13, 2019

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

@bbugh
Copy link

@bbugh bbugh commented Dec 4, 2019

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
Copy link
Member

@arcanis arcanis commented Dec 4, 2019

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
Copy link
Contributor

@devinrhode2 devinrhode2 commented Sep 5, 2020

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

@samrith-s samrith-s commented Nov 1, 2020

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
Copy link
Member

@arcanis arcanis commented Nov 1, 2020

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

@samrith-s
Copy link

@samrith-s samrith-s commented Nov 1, 2020

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

@evanrlong evanrlong commented Nov 20, 2020

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

@evanrlong evanrlong commented Nov 20, 2020

Ah looks like dependenciesMeta might be my friend here.

@bertho-zero
Copy link

@bertho-zero bertho-zero commented Dec 4, 2020

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
Copy link
Member

@merceyz merceyz commented Dec 4, 2020

@bertho-zero
Copy link

@bertho-zero bertho-zero commented Dec 4, 2020

Sorry, thanks for your response.

@beorn
Copy link

@beorn beorn commented Apr 14, 2021

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
Copy link
Member

@arcanis arcanis commented Apr 14, 2021

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

@beorn beorn commented Apr 14, 2021

@arcanis
Copy link
Member

@arcanis arcanis commented Apr 14, 2021

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

@beorn beorn commented Apr 14, 2021

@elliotdavies
Copy link

@elliotdavies elliotdavies commented May 6, 2021

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
Copy link
Member

@merceyz merceyz commented May 6, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests