Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Team Workflows

Sharing a Vagrantfile in Git

Commit a Vagrantfile and its provisioning scripts to Git, ignore the .vagrant folder, handle line endings on Windows, and keep secrets and local overrides out of the repo.

The big promise of Vagrant is "clone, run vagrant up, start working". That only holds if you share the right files and keep the wrong ones out of the repository. This lesson shows what belongs in Git, what does not, and the traps that bite teams on mixed operating systems.

What to commit

Treat the environment as code that lives beside the application.

TEXT
myproject/
โ”œโ”€โ”€ Vagrantfile
โ”œโ”€โ”€ provision/
โ”‚   โ”œโ”€โ”€ bootstrap.sh
โ”‚   โ”œโ”€โ”€ nginx.conf
โ”‚   โ””โ”€โ”€ app.service
โ”œโ”€โ”€ machines.yml
โ”œโ”€โ”€ .gitignore
โ”œโ”€โ”€ .gitattributes
โ”œโ”€โ”€ README.md
โ””โ”€โ”€ src/

Commit:

  • the Vagrantfile, with sensible defaults for everyone;
  • provisioning scripts and the config files they copy (nginx, systemd units);
  • a small README.md with the commands a newcomer types;
  • .gitattributes for line endings (see below).

What to ignore

Vagrant stores per-machine state in a hidden .vagrant/ folder. It contains the machine's identifier, SSH keys and provider metadata. It is specific to your computer and must never be committed.

TEXT
# .gitignore
.vagrant/
*.box
machines.local.yml
.env
*.log
  • .vagrant/: local machine state and private keys.
  • *.box: packaged boxes are large; host them elsewhere (see packaging and private boxes).
  • machines.local.yml and .env: personal overrides and secrets.

If .vagrant/ is committed, a teammate who pulls it gets a machine ID that does not exist on their computer. Vagrant then reports a confusing state or tries to use someone else's SSH key. Add it to .gitignore in the first commit.

A README that actually helps

The README is the contract with new teammates. Keep it short and exact.

TEXT
## Development environment
Requirements: Vagrant 2.4+, VirtualBox 7.0+

    git clone [email protected]:team/myproject.git
    cd myproject
    vagrant up            # first run takes about 5 minutes
    vagrant ssh
    cd /vagrant && make test

Web app:  http://localhost:8080
Database: localhost:15432 (user app, password app)

Reset everything:  vagrant destroy -f && vagrant up

State the Vagrant and provider versions you tested, and the single command to reset. A README that is wrong is worse than none, so update it in the same pull request that changes the Vagrantfile.

Line endings across operating systems

The classic Windows problem: Git for Windows converts shell scripts to CRLF line endings on checkout. The scripts then run inside a Linux guest and fail with errors such as /bin/bash^M: bad interpreter or $'\r': command not found.

Fix it at the repository level with .gitattributes, so every clone behaves the same regardless of each developer's Git settings.

TEXT
# .gitattributes
*.sh            text eol=lf
*.conf          text eol=lf
*.service       text eol=lf
Vagrantfile     text eol=lf
*.rb            text eol=lf
*.bat           text eol=crlf

eol=lf forces LF on checkout for everyone. Run git add --renormalize . once after adding the file if scripts are already in the repository.

Keeping secrets out

Never put real passwords, API tokens or private keys in a Vagrantfile. Even a development password gets copied into other places. Use one of these:

  1. Environment variables: ENV["DB_PASSWORD"] || "devpassword", with a documented harmless default.
  2. An ignored .env file read by the Vagrantfile (with the vagrant-env plugin or a few lines of Ruby).
  3. A secrets prompt on first run: ask the user once and save it to an ignored file.
Ruby
db_password = ENV.fetch("DB_PASSWORD", "dev-only-password")

config.vm.provision "shell",
  env: { "DB_PASSWORD" => db_password },
  path: "provision/bootstrap.sh"

The env option passes the value to the script as an environment variable instead of interpolating it into a command line, which keeps it out of process listings and logs.

Branch-aware environments

Because the Vagrantfile lives in the repository, switching branches changes the environment definition. Two consequences:

  • A branch that adds a package to bootstrap.sh does not change machines that already exist. After switching, run vagrant provision (or vagrant destroy -f && vagrant up for large changes).
  • A branch that changes the Vagrantfile in an incompatible way (new IP addresses, new box) may need a rebuild. Mention that in the pull request description.

A stand-in: lint a Vagrantfile before committing

Teams often run a small script in a Git hook or CI job to catch common mistakes. This Ruby program scans text for several of the problems in this lesson. It is a stand-in, not part of Vagrant; adapt it to read your real file.

Ruby A Vagrantfile linter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The box-version finding leads straight into the next lesson on version constraints.

Onboarding checklist

A good Vagrant repository passes these checks on a clean computer:

  1. git clone then vagrant up produces a working machine with no manual steps.
  2. vagrant destroy -f && vagrant up repeats it from scratch.
  3. Nothing in the repository mentions a personal path, user name or password.
  4. The README lists versions and the reset command.

Common mistakes

  • Committing .vagrant/.
  • CRLF line endings in provisioning scripts.
  • Hard-coded personal paths such as C:\Users\me\... in synced folders. Use __dir__ or relative paths.
  • An undocumented prerequisite, like a plugin, that makes vagrant up fail on a fresh computer.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must .vagrant/ be listed in .gitignore?

    The folder is local state; sharing it confuses other users' Vagrant and leaks keys.
  2. 2. A shell provisioner fails with '/bin/bash^M: bad interpreter'. What is the likely cause?

    The carriage return becomes part of the interpreter name. Force LF endings with .gitattributes.
  3. 3. How should a Vagrantfile receive a database password?

    Keep secrets out of version control; use the environment or ignored files.
  4. 4. You switch to a branch whose bootstrap.sh installs a new package. Your machine already exists. What do you run?

    Provisioners run on first up; re-run them explicitly with vagrant provision.

Summary

  • Commit the Vagrantfile, provisioning scripts, README and .gitattributes; ignore .vagrant/, boxes, secrets and local overrides.
  • Force LF line endings for scripts to protect Windows users.
  • Keep secrets in the environment and document the exact commands a newcomer types.
  • After changing branches, re-run provisioning or rebuild.

Next: Version constraints