Can you ignore files/folders when making a Repo from a template?

[Andre601]

I set up a GitHub Repository as a template so that other people can use it to create documentation or similar.

That said would I like to make it, so that when people click the “Use this template” button, that the copied Repo won’t contain certain files or folders like the README.md.

Is there a way to set a file or similar to define files/folders that should not be copied from the template repository?

(If not, then I hope it could be considered as a feature in the future.)

[AndreaGriffiths11]

Hi @andre601,

Thank you for being here. At the moment there isn’t a way to ignore files when creating from repository templates. Ideally there will be an implemented  dot ignore file for repository templates, and I’ve passed that suggestion to the team for consideration. Although I can’t guarantee when or if this feature would be implemented please know your feedback is in the right hands.

[HealthyPear]

+1

[jimbrig]

+1

[katapultcloud]

+1

[erexer]

+1

[TWiStErRob]

+1

[schroef]

So excluding files or folder being added to the zip also isn’t possible then?

I got this repo which has template files, these are added in the zip when the repo is downloaded. I would like to exclude those.

https://github.com/schroef/Extra-Image-List

[jonnitto]

I hope this feature will be included soon…

[jamesratcliffe]

+1 for this! Specifically, when making a repository from a template, I don’t want to include package manager lockfiles.

[vincerubinetti]

It’d probably make sense to put it in /.github because templates are a github-specific concept. Maybe something like /.github/.template-ignore.

Just to add to how useful this would be… I’m making a website template, and it’d be great to only give users the files they really need. There’s a test bed page for my own development purposes that they don’t need. And there’s a bunch of documentation that should stay in the same repo (because it’s for the template), but doesn’t need to be duplicated to every clone of the template.

[andrewvaughan]

This sounds like a great solution.

[Andre601]

I think having it as a dot-file in the root, similar to .gitignore would make a bit more sense, in case that any other git repo-site (bitbucket, gitlab, gittea, etc) would want to adobt this idea in the future. I for myself see a new potential feature alongside the .gitignore file that could help improve any future git repositories…

But that’s just my thinking.

[andrewvaughan]

Possibly - however, that assumes that each provider handles templates the same way, which can't be guaranteed. For that reason, at least as an initial iteration, it makes sense to live in the .github folder as it is, specifically, a .github template tool.

That said, I'm replying to a comment that was made 3 years ago, so I'm probably yelling my opinion into a hole in the ground :)

[jackkoenig]

There is a way of solving this (somewhat manually) by using workflows that trigger on: create or on the first push. When the user creates a repo from the template, the workflow can edit and delete files at will and then push a commit. A good example is this repository: https://github.com/JetBrains/intellij-platform-plugin-template
with the workflow: https://github.com/JetBrains/intellij-platform-plugin-template/blob/deb171483598ee8a5d7621154db880e87b4db4ef/.github/workflows/template-cleanup.yml

This approach is pretty nice, but has 2 major cons:

1. It’s not interactive. It would be nice if the user could set fields like “organization name” instead of forcing projects to guess from the Github org.
2. It has a delay. It takes a minute or two for the workflow to push the commit, so instructions on templates that use this approach are basically like “please wait a moment and refresh the page until it’s done!”

@AndreaGriffiths11 I’m a bit late here but if there is some internal ticket on this feature, it would be wonderful if it went beyond a mere “ignore” file and instead had some interactivity and integration with Github Actions and workflows.

[fhinkel]

Any updates? We'd love to have this feature.

[corykinney]

I'd also be very interested in this feature. I'd like to have workflow in the template repository that can automatically keep it up-to-date with submodules, but I don't want the generated repositories to include the workflow.

[hoishing]

+1, ignoring files such as how to use the template is reasonable. Something like .template-ignore with glob patterns similar to gitignore would be great.

[vincerubinetti]

As a solution for now, I'm using GitHub Actions to "clean" the repo for the user when they generate it:

name: first-time-setup
run-name: first time setup of repo

on:
  # run when branch created (repo generated from template)
  create:

# only keep latest run of this workflow
concurrency:
  group: first-time-setup
  cancel-in-progress: true

jobs:
  first-time-setup:
    # ensure run only once, when repo generated
    if: github.run_number == 1

    runs-on: ubuntu-latest

    steps:
      # get main branch repo contents
      - name: Checkout code
        uses: actions/checkout@v3

      # remove files not needed for user instance of template
      - name: Remove unneeded files
        run: rm -f README.md demo.md testbed.md

      # personalize readme for user
      - name: Init readme
        run: |
          echo "
   
          Personalized readme text. Hello ${{ github.repository_owner }}!

          " > README.md

      # save changed files
      - name: Commit changed files
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "Setup repo"

This actually turns out to be a nicer solution because I can do more than just exclude certain files. I can customize files however I want based on user info like user/org name, repo name, etc. with the env and github contexts.

However, this only works when "generating" (i.e. "Use this template"), and not when forking, because when you fork, GitHub Actions is not enabled yet, and there is no workflow trigger for when Actions is first enabled. You could perhaps call the above workflow from some other workflow that you know will run at some point, like a "build live site" workflow.

[WoutDLN]

Thanks for your quick response!

I thought it might be an indentation issue, but was looking in the wrong place. That will teach me for trusting validator prompts.

But I am excited to report that it does work! The problem was that the original code posted by @vincerubinetti was indeed outdated: both the actions that the workflow references used Node.js 16, which has since deprecated. Updating it to newer versions (respectively actions/checkout@v4 and stefanzweifel/git-auto-commit-action@v5 did the trick. (I don't suppose it's possible to just refer to the 'latest' version of these actions, to prevent this issue in the future?)

And you were also right about the tokens. I removed the lines added by @anujonthemove, and the action still worked.

An updated version of the code, that works today (at least) looks like this:

name: first-time-setup
run-name: first time setup of repo

on:
  # run when branch created (repo generated from template)
  create:

# only keep latest run of this workflow
concurrency:
  group: first-time-setup
  cancel-in-progress: true

# ADDED THIS CHANGE
permissions: 
  actions: write
  checks: write
  contents: write

jobs:
  first-time-setup:
    # ensure run only once, when repo generated
    if: github.run_number == 1

    runs-on: ubuntu-latest

    steps:
      # get main branch repo contents
      - name: Checkout code
        uses: actions/checkout@v4

      # remove files not needed for user instance of template
      - name: Remove unneeded files
        run: rm -f README.md demo.md testbed.md

      # personalize readme for user
      - name: Init readme
        run: |
          echo "
   
          Personalized readme text. Hello ${{ github.repository_owner }}!

          " > README.md

      # save changed files
      - name: Commit changed files
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "Setup repo"

[WoutDLN]

Just a quick reminder for anyone who would like to use the above code:

The action is triggered on the user's account, after cloning the repository. Because this takes some time (seconds, in my case), it will first look like the action did not succeed (original files still in place, README.md file still includes the old text). So be sure to refresh your page, or go to the Actions tab to see if the action is still running, before concluding that it didn't work.

[anujonthemove]

I tested this action today and I can confirm that it does not work anymore. I think it has got outdated, need to re-check.
The purpose of this action was to(run only once and) clean the readme file when you create a new repository out of a template.

I used this in my Python Machine Learning Template repository and it used to work back then.

[vincerubinetti]

tl;dr: The action workflow by @vincerubinetti and added to by @anujonthemove is either very outdated, generated by AI (ChatGPT) or just plain wrong.

My code was not AI generated. The other person's may have been.

The problem was that the original code posted by @vincerubinetti was indeed outdated: both the actions that the workflow references used Node.js 16, which has since deprecated. Updating it to newer versions (respectively actions/checkout@v4 and stefanzweifel/git-auto-commit-action@v5 did the trick.

My code is indeed "out of date" in that it didn't use the latest versions of the actions, but that should not be causing errors. It will warn about Node 16 being deprecated, but that's it. Node 16 will not start becoming an error until May 13th.

If you see something like this

you can't just assume the warning is causing the error, you need to look at the actual error logs:

You have permissions errors going on.

Something I've noticed in my several years of working on gh-actions with templates is that, over time, GitHub seems to restrict/loosen permissions of certain categories and tokens (e.g. as they discover exploits), and sometimes change the default permissions when generating/forking a repo. For example, I now tell my users that, after they generate/fork from my template, they must go into their settings and give the GITHUB_TOKEN read/write permissions manually. And, as far as I understand the complicated hierarchy of permissions on GitHub, setting permissions: write in the action itself usually cannot just magically override this if it's restricted to "read" in the settings.

When I just blindly copy-paste

As with any code you see on the internet, it is meant to be instructive and should always be taken as pseudo code. Especially in this case, where the platform can change things under our feet that affect all sorts of behaviors.

(I don't suppose it's possible to just refer to the 'latest' version of these actions, to prevent this issue in the future?)

See this. You can go by branch or tag name. There is no semver involved; that is, no syntax like ^2.0.0 or 2.x.x. Something like @v2 only works when the action author explicitly adds a tag named exactly v2, and keeps it up to date with the latest commits. Also, using the @main branch to always use the latest is something you probably shouldn't do, because the author can change behavior/parameters/etc which will break your runs.

[WoutDLN]

Thanks @anujonthemove and @vincerubinetti for your responses! They've been really helpful. Just a couple of small comments in response to what's been said:

As with any code you see on the internet, it is meant to be instructive and should always be taken as pseudo code.
-- @vincerubinetti

Always a good reminder, but yes, I know this. I was just trying to explain in the simplest and clearest terms how one might replicate the issue I was having.

you can't just assume the warning is causing the error
-- @vincerubinetti

Yes, going through the actual error logs is a better (or even: the only true) way of identifying the problem. But I didn't just assume this was the problem: I tested it. I changed the versions of the Actions and tried to use the template again, and this time it worked. Which is why I thought I had resolved the issue, and wanted to share my solution. Although now I realise there may have been other variables at play that I hadn't considered before.

I tested this action today and I can confirm that it does not work anymore.
-- @anujonthemove

The thing is: most of the time, the action does seem to work -- for me at least. When I create a new repo on the basis of my template, I will first get an exact replica of the template itself (with all the superfluous and incorrect files). But the creation of the template triggers the Action, which I can see running when I go to the Actions tab. When that's finished (seconds later), files I had marked to be removed are removed, and files that I marked to be modified have been modified. You can try this out for yourself if you're interested. I've added this Action to a couple of my repos, one of them is this one: https://github.com/SSLIS/DCHM-template

That said, I have only tried to test this from my own account. It may be the case that when someone else tries to do the same thing, it doesn't work for them, because of some permission issues in their settings (as suggested by @vincerubinetti). I would be interested to know if that is the case.

Finally, I do acknowledge that there is something weird going on with this action. Like I said, the action seems to work most of the time, but not all the time. Sometimes, when I 'use this template', the action isn't triggered. And I have not been able to figure out yet what causes this. Because when I go through the exact same steps again, to create a second repo, that second repo does trigger the action. Preliminary testing suggests that the action isn't triggered the first time I 'use this template' on any given day, but is triggered on any subsequent attempts on the same day. But my testing hasn't been very extensive yet.

So it may very well be that changing the versions of the actions called in the script didn't actually resolve anything, like @vincerubinetti suggests, but that there was another (yet unidentified) variable getting in the way.

I would be very interested to learn what is going on here, and how (or if) it might be resolved. It's not mission critical at this time: more of a nice to have than a must have. I was just excited to have found a way to automatically clean up my template upon use -- however roundabout that way was. Obviously, this will never be a really 'good' solution to the problem, and a new type of .gitignore that ignores files before they are copied into the destination repo (as argued for elsewhere in this thread) would be a much better solution. But for now, as a stopgap solution, it seems to work (most of the time), and it's useful when it does. Of course, anyone using any GitHub Template (just like anyone forking any GitHub Repo) should probably know that the template (or fork) should be considered as a starting point, and that they are responsible for changing or removing any files that contain irrelevant or incorrect information (in the context of their own projects). But since we know which files will likely pose those kind of issues beforehand (e.g. LICENSE, CODE_OF_CONDUCT, or README files), it would be much more useful if we had a way to automate part of this process.

[jcogilvie]

My use case is that I have a CODEOWNERS file that protects the template, but I don't want the same CODEOWNERS present in the derived repo (because it doesn't make any sense to have it there).

The script solution here doesn't work for me because it runs after the derived repo is created, which means the first change in the new repo is subject to CODEOWNERS.

[anujonthemove]

+1 Any updates on this would be appreciated. Thanks!

[bj00rn]

+1 for this feature

[JakeBent]

+1 please do this

[texeltexel2009]

+1 would be nice to have

[doctrino]

+1 We are really missing this feature

[anantakumarghosh]

+1

[caendesilva]

Chiming in to say that this is really needed. I have a template to run tests on the project, but it shouldn't be present in the release when users create a repo based on the template. I don't want to use up their action minutes for something that they don't need. Considering forks don't even run workflows by default, why would repo templates be different?

[onedr0p]

I think Github needs to add official support for this with a .github/.template-ignore file or something and inside that file we can list the ignores in gitignore format that won't be carried over to the generated template. This would be nice.

CODEOWNERS
CODE_OF_CONDUCT.md
docs/

[caendesilva]

That would be awesome!

[neerajgrg]

Is there any updated on this ? @AndreaGriffiths11 , when can we expect this feature ?

[caendesilva]

In the meantime, the best way we managed to workaround this for HydePHP was by adding a workflow that runs on the create event. We then run the following Bash script to remove all files that are set as export-ignore by the .gitignore file:

# Read the .gitattributes file line by line
while IFS= read -r line; do
    # Check if the line contains 'export-ignore'
    if [[ $line == *"export-ignore"* ]]; then
        # Extract the path from the line
        path=$(echo "$line" | awk '{print $1}')
        rm -rf "$path"
    fi
done < ".gitattributes"

See hydephp/hyde#257 and this Gist https://gist.github.com/caendesilva/a7aa411b218d0fc5b5e4f5e884bc2350

[willguest]

[Andre601]

That isn't even close to answering the question in this discussion which is wether there is a way to ignore files being copied when using a template not how to ignore files in pushes in GitHub Actions. Please actually read what the discussion is about before answering it.

[willguest]

I came here with a similar issue, as I would like people who use my template to not receive some of the files in the repository. I found that one possible route was to do this, since the act of 'using a template' consists partly of a push action behind the scenes.

My apologies if this is wrong, I was only trying to offer some information to help the discussion along. Does this mean that when someone clicks 'use this template' in order to create a new repository, this route will not work?

[Andre601]

Even if using a template counts as a push does it not exclude specific files from being copied. All your solution does is make the Action ignore specific files, which is redundant for the topic of this discussion, as it won't exclude the files from being copied too.