Templating support

[BetaHuhn]

With this action being used in a lot of different and increasingly advanced use cases I think it might be time to add support for file templates. @erezrokah already created a draft PR for an implementation, but I want to discuss the use cases and syntax for such a feature with more users first before moving to actual code.

What are file templates?

A file template in the context of this action would be a template file which contains some variables which get replaced with actual data during the syncing process. This would allow you to define a template for a commonly used file and have it be filled with different data depending on the repository the file is being synchronized to.

A very basic use case would be a LICENSE file where the author's name gets injected into it or a PR template where a link to a homepage gets changed based on the target repository. Templates could also be used with code files and for other more advanced use cases.

Proposed Syntax

Here is an idea for the syntax of a basic template feature:

.github/sync.yml

user/repo:
  - template: LICENSE.md
     data:
       author: "BetaHuhn"

group:
  repos: |
    user/repo1
    user/repo2
  files:
    - template: LICENSE.md
      data:
         author: "$TARGET_REPO_AUTHOR"

LICENSE.md

MIT License

Copyright (c) 2022 <%- author %>

The template key would specify which file to use and the data key what variables to replace with a specific value. The value can also use variables like the target repository name or other dynamic data.

If the config becomes too crowded, we could also add a data_file key which lets you specify a file with the data variables in different formats like yml or json.

Feedback

There are a lot of different ways to implement such a feature and I want to make it as useful as possible for all of you. This requires that I learn more about how you are using the action at the moment and what the ideal version of this feature would look like to you. I am open to different ideas for the syntax and scope of this feature.

Let me know what you think about the feature in general, if this is something you would find useful and if the proposed syntax would work for your use case.

Thanks,
@BetaHuhn (creator and maintainer of this action)

[erezrokah]

Thanks for starting this discussion @BetaHuhn!

The approach you suggested might get a bit verbose with many repos:

user/repo1:
  - template: LICENSE.md
    data:
       author: "author1"
user/repo2:
  - template: LICENSE.md
    data:
       author: "author2"
user/repo3:
  - template: LICENSE.md
    data:
       author: "author3"

Is it possible to support it via a group?
Also do you have any thoughts on how it will be configured for directories? Or this is something that will only be available for single files

[rummens1337]

For my use case it would be a nice addition to sync block(s) within a file. For instance, in my source repository I have a .gitignore file, which serves as the base for my projects. However, I would want the target repositories to be able to edit the .gitignore file and still be able to sync the 'base' block.

###> FILESYNC/START ###
...
###< FILESYNC/END ###

Configuration could be something like below. I am not sure as to how easily this could be implemented for different file types, but I'm just sharing my raw thoughts here :)

group:
    -   files:
            -   source: .gitignore
                dest: .gitignore
                replace: true
                template:
                    block-start: "###> FILESYNC/START ###"
                    block-end: "###< FILESYNC/END ###"

[BetaHuhn]

@dhruvkb added support for Jinja style templates using Nunjucks:

user/repo:
  - source: src/README.md
    template:
      user:
        name: 'Maxi'
        handle: '@BetaHuhn'

In the source file you can then use these variables like this:

# README.md

Created by {{ user.name }} ({{ user.handle }})

Result:

# README.md

Created by Maxi (@BetaHuhn)

More info the README.

[erezrokah]

Amazing! Thank you so much for following up on this