Include certain hidden files in templates (e.g. based on .quartoignore)

[skwde]

Description

As mentioned here https://quarto.org/docs/extensions/starter-templates.html#creating-a-template all hidden files / directories are ignored.

It would be nice to have a way to allow certain hidden files / directories.
This would allow to also bundle common project setup with the template like lint config files or a .devcontainer

I tried using a .quartoignore or .gitignore like

!.devcontainer/
!.devcontainer/*
!.pre-commit-config.yaml

but this didn't help.

[mcanouil]

Use format-resources and/or resources to add resources depending on what your extension is.
It should work, if not please share a small Git repository which reproduce the issue.

[skwde]

Ok, thanks for your reply.

So just to confirm, it is currently not possible to create a project directory from a skeleton.
I simply want to have a custom project files (project not in the quarto sense, but in the git repository sense).

The approach you mention seems like a workaround to what I try to achieve. (I don't want to change rendering / preview behavior or ship my own css style).
From what I understand the use of templates is not meant for that.
I guess I wrongly understood quarto projects / templates in the first place.

I however thing that something like this is quite useful to more than me, should this move to a feature request?

[mcanouil]

project not in the quarto sense, but in the git repository sense

Then use Git/GitHub (or GitLab) and create a repository template.

[skwde]

Yes that's what I try to do, quarto use template allows for git repositories

When using git clone for my template, another another manual interaction is required, namely removing .git.
That is why I try to use quarto templates in the first place.

Are quarto templates only meant to be used with and _extension folder?
I don't quite get why there is the restriction of not copying any hidden files, at least it should be optin, e.g. with an option.
Point 1 and 2 at https://quarto.org/docs/extensions/starter-templates.html even mention it, that it is meant for initial content.

[mcanouil]

Yes that's what I try to do, quarto use template allows for git repositories

A "template" is a format extension which contains a template.qmd.

There are no restrictions. It's a current limitation as there is nothing to tell Quarto what files/directories should be kept or not from the _extensions directory in the Git repository.

Extensions were designed to allow users to use whatever custom formats they want because custom formats require repeated and tedious tasks without.

FYI:

• Allow (project) extensions to provide resources #9515

with an option.
Point 1 and 2 at https://quarto.org/docs/extensions/starter-templates.html even mention it

You have to read the links to understand what "initial content" means.

[skwde]

Thanks again for your response and explanation.

The issue is indeed helpful.

Now patiently waiting for it to be solved ;)

[NeuroShepherd]

I was not able to accomplish this with any combination of including files via resources, format-resources, or specifying exact or glob paths to dot files in my .quartoignore like the original poster.

However, I found a (hacky) solution to this where I first negated the exclusion of all dot files/folders, and then added back the paths I wanted to ignore. E.g. a testing project of mine is structured like this:

tree -La 1
.
├── _extensions
├── _quarto.yml
├── _site
├── .DS_Store
├── .git
├── .github
├── .gitignore
├── .posit
├── .quarto
├── .quartoignore
├── apage.qmd
├── index.qmd
├── README.md
└── template.qmd

and my .quartoignore file contains this:

!.*
.git/
.quarto/
.posit/
.quartoignore

which copies over my.github and .gitignore while ignoring the other dot files.

I have a suspicion there's an issue (or at least a misunderstanding from the user-side) with the template.ts implementation. It seems this code:

quarto-cli/src/extension/template.ts

Lines 37 to 41 in effe145

	excludes.push(...kBuiltInExcludes);
	const filtered = excludes.filter((ex) => {
	return !includes.includes(ex);
	});

filters on exact string matches, which means a broad exclusion pattern like ".*" from kBuiltInExcludes will not be removed by a more specific include pattern like ".github/**" because they are not identical strings, leading to the broader exclusion taking precedence.

[mcanouil]

Using Quarto Wizard for Positron/VSCode, you can choose whatever is available inside the Quarto extension directory/repository, including hidden directories/files.

See https://m.canouil.dev/quarto-wizard/getting-started/using-templates.html#installing-a-template

[NeuroShepherd]

Neat, thanks for the additional work-around!