Proper .gitignore file for a Neos Flow project?

Question

I recently created a new project using composer create-project --keep-vcs neos/flow-base-distribution ProjectName and I'm a bit confused by the .gitignore file it produces:

/Build/
/Configuration/
/Data/
/Packages/
/Web/
/bin/
/Readme.rst
/Upgrading.rst
/flow
/flow.bat

It basically throws out almost every file from the VCS, including the entirety of the Packages/Application folder, where I assumed most of my code would go. So what gives? Why is the .gitignore file so broad?

Answer 1

I don't have previous experience in neos-flow but I installed it with the help of composer on two different computers with Ubuntu OS. My .gitignore file output is same like your output both time.

/Build/
/Configuration/
/Data/
/Packages/
/Web/
/bin/
/Readme.rst
/Upgrading.rst
/flow
/flow.bat

The Original structure of my project is

.  ..  .editorconfig  .git  .github  .gitignore  Build  Configuration  Data  Packages  Readme.rst  Web  bin  composer.json  composer.lock  flow  flow.bat

When i remove all folders and files as declared in .gitignore then my project structure is like this

.  ..  .editorconfig  .git  .github  .gitignore   composer.json  composer.lock

As you know, The purpose of the .gitignore file is to allow you to ignore files, such as editor backup files, build products or local configuration overrides that you never want to commit into a repository.
I think that neos-flow just need those files that are remaining after applying .gitignore. Those are composer.json and composer.lock
The purpose of composer.json is that it shows the details about the project like name, description, license information.
And composer.lock shows all packages, and dependencies for the project, their name, detail and url for downloading the package.

The content of composer.json

{
    "name": "neos/flow-base-distribution",
    "description": "Flow Base Distribution",
    "license": "MIT",
    "support": {
        "email": "[email protected]",
        "slack": "http://slack.neos.io/",
        "forum": "https://discuss.neos.io/",
        "wiki": "https://discuss.neos.io/c/the-neos-project/project-documentation",
        "issues": "https://github.com/neos/flow-development-collection/issues",
        "docs": "https://flowframework.readthedocs.io/",
        "source": "https://github.com/neos/flow-base-distribution"
    },
    "config": {
        "vendor-dir": "Packages/Libraries",
        "bin-dir": "bin"
    },
    "require": {
        "neos/flow": "~6.0.0",
        "neos/welcome": "~6.0.0"
    },
    "require-dev": {
        "neos/kickstarter": "~6.0.0",
        "neos/buildessentials": "~6.0.0",
        "neos/behat": "dev-master",
        "phpunit/phpunit": "~8.1",
        "mikey179/vfsstream": "~1.6"
    },
    "repositories": {
        "distributionPackages": {
            "type": "path",
            "url": "./DistributionPackages/*"
        }
    },
    "replace": {
        "typo3/flow-base-distribution": "self.version"
    },
    "suggest": {
        "ext-pdo_sqlite": "For running functional tests out-of-the-box this is required"
    },
    "scripts": {
        "post-update-cmd": "Neos\\Flow\\Composer\\InstallerScripts::postUpdateAndInstall",
        "post-install-cmd": "Neos\\Flow\\Composer\\InstallerScripts::postUpdateAndInstall",
        "post-package-update": "Neos\\Flow\\Composer\\InstallerScripts::postPackageUpdateAndInstall",
        "post-package-install": "Neos\\Flow\\Composer\\InstallerScripts::postPackageUpdateAndInstall"
    }
}

First 70 lines of composer.lock

{
    "_readme": [
        "This file locks the dependencies of your project to a known state",
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
        "This file is @generated automatically"
    ],
    "content-hash": "06d49a77babbafa5a03d726865e61dc3",
    "packages": [
        {
            "name": "composer/ca-bundle",
            "version": "1.2.4",
            "source": {
                "type": "git",
                "url": "https://github.com/composer/ca-bundle.git",
                "reference": "10bb96592168a0f8e8f6dcde3532d9fa50b0b527"
            },
            "dist": {
                "type": "zip",
                "url": "https://api.github.com/repos/composer/ca-bundle/zipball/10bb96592168a0f8e8f6dcde3532d9fa50b0b527",
                "reference": "10bb96592168a0f8e8f6dcde3532d9fa50b0b527",
                "shasum": ""
            },
            "require": {
                "ext-openssl": "*",
                "ext-pcre": "*",
                "php": "^5.3.2 || ^7.0 || ^8.0"
            },
            "require-dev": {
                "phpunit/phpunit": "^4.8.35 || ^5.7 || 6.5 - 8",
                "psr/log": "^1.0",
                "symfony/process": "^2.5 || ^3.0 || ^4.0"
            },
            "type": "library",
            "extra": {
                "branch-alias": {
                    "dev-master": "1.x-dev"
                }
            },
            "autoload": {
                "psr-4": {
                    "Composer\\CaBundle\\": "src"
                }
            },
            "notification-url": "https://packagist.org/downloads/",
            "license": [
                "MIT"
            ],
            "authors": [
                {
                    "name": "Jordi Boggiano",
                    "email": "[email protected]",
                    "homepage": "http://seld.be"
                }
            ],
            "description": "Lets you find a path to the system CA bundle, and includes a fallback to the Mozilla CA bundle.",
            "keywords": [
                "cabundle",
                "cacert",
                "certificate",
                "ssl",
                "tls"
            ],
            "time": "2019-08-30T08:44:50+00:00"
        }]}

The _readme key in composer.lock json shows the purpose of composer.lock

"_readme": [
        "This file locks the dependencies of your project to a known state",
        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
        "This file is @generated automatically"
    ],

So in short your .gitignore is absolutely fine and accurate. I also install it on both my ubuntu computers and both are same.

Answer 2

There are two models of .gitignore under their repository:

---

https://github.com/neos/flow/blob/master/Resources/Private/Installer/Distribution/Defaults/.gitignore

/Build/
/Configuration/
/Data/
/Packages/
/Web/
/bin/
/Readme.rst
/Upgrading.rst
/flow
/flow.bat

---

https://github.com/neos/flow-development-distribution/blob/master/.gitignore

/Build/Behat/*
/Build/BuildEssentials
/Build/Reports
/Build/Resources
/Configuration/
/Data/
/Packages/
/Web/
/bin/
/Readme.txt
/Upgrading.txt
/Readme.rst
/Upgrading.rst
/flow
/flow.bat

Answer 3

As I am an avid Flow user, I can explain why the Packages/ directory is excluded:

As you can see in the composer.json, there is this section:

    "repositories": {
        "distributionPackages": {
            "type": "path",
            "url": "./DistributionPackages/*"
        }
    },

This tells composer to look for your own packages in the DistributionPackages/ directory. This is much cleaner than mixing own packages and dependencies in the Packages/ directory and also helps a bit with dependency management itself (since only the composer.json in your package directory needs to contain the package dependencies - i.e. no need to duplicate them in the root composer.json). See https://docs.neos.io/cms/manual/dependency-management#the-path-repository-setup and https://www.neos.io/blog/project-repository-best-practice.html for more info about that (this not only applies to Neos site packages, but every project specific package).

As for the other excluded files: Since those get created by composer install, those don't need to be tracked by git.

Exception: You often want to include the Web/ directory (but exclude non-specific contents like Web/_Resources/ or Web/index.php) i.e. for the favicons or other static files needed in the web root.