New env merger and if_exists conditions

[williarin]

Parameter	Type	Comments
if_exists	string	Used if type is text or env. Choices: For type type append Adds content to the end of an existing file, or creates a new one. overwrite Overwrites existing content, or creates a new file. ignore Doesn't alter an existing file, or creates a new file. For type env comment Comments same name env vars delete Delete same name env vars Default: append for text type. comment for env type. Optional

Text

The text merger can be used to extend any text-based file such as:

• .gitignore
• Makefile

As it's the default merger, you can simply use the destination: source format in the recipe.

Example 1: append to an existing file

Given yourrepo/recipe/.gitignore with this content:

# Ignore the .env file
.env

With this recipe:

files:
    .gitignore: recipe/.gitignore

The created .gitignore file will look like this:

###> yourname/yourrepo ###
# Ignore the .env file
.env
###< yourname/yourrepo ###

The ###> yourname/yourrepo ### opening comment and ###< yourname/yourrepo ### closing comment are used by Cook to identify the recipe in the file.
If you're familiar with Symfony Flex, the syntax is the same.

Example 2: overwrite an existing file

If you want to overwrite the existing file, you can use the if_exists parameter.

files:
    .gitignore:
        source: recipe/.gitignore
        if_exists: overwrite

This will replace the entire content of the .gitignore file with the content of recipe/.gitignore.

Example 3: ignore an existing file

If you want to ignore the existing file, you can use the if_exists parameter.

files:
    .gitignore:
        source: recipe/.gitignore
        if_exists: ignore

This will not alter the existing .gitignore file, and will not create a new one if it doesn't exist.

Env

The env merger is used to add new environment variables to an existing .env file or create a new one if it doesn't exist.

Example 1: merge or create a .env file with a given source file

Given yourrepo/recipe/.env with this content:

SOME_ENV_VARIABLE='hello'
ANOTHER_ENV_VARIABLE='world'

And an existing .env file in the project with this content:

# Existing environment variables
SOME_ENV_VARIABLE='foo'

With this recipe:

files:
    .env:
        type: env
        source: recipe/.env

The created .env file will look like this:

# Existing environment variables
#SOME_ENV_VARIABLE='foo'

###> yourname/yourrepo ###
SOME_ENV_VARIABLE='hello'
ANOTHER_ENV_VARIABLE='world'
###< yourname/yourrepo ###

The existing SOME_ENV_VARIABLE is commented out to avoid conflicts with the new value, this is the default behavior of the env merger.

Example 2: merge or create a .env file with a string input

Alternatively, you can use content instead of source, to avoid creating a file in your repository.

files:
    .env:
        content: |-
            SOME_ENV_VARIABLE='hello'
            ANOTHER_ENV_VARIABLE='world'