Document ability to disable template directory in git-init

Hello,

Looking at the git-init(1) man page, there doesn't appear to be a way to disable copying the contents of the default template directory, other than passing a path pointing to an empty directory.

However, if one passes an empty path, for example with the --template option, then git does not complain and does not copy anything:

git init --template=

Looking at the code, this undocumented (AFAICS) behavior appears to be there at least from git 2.1:

static void copy_templates(const char *template_dir)

{
	...

	if (!template_dir)
		template_dir = getenv(TEMPLATE_DIR_ENVIRONMENT);
	if (!template_dir)
		template_dir = init_db_template_dir;
	if (!template_dir)
		template_dir = system_path(DEFAULT_GIT_TEMPLATE_DIR);
	if (!template_dir[0])
		return;

For reference, the corresponding code in 2.50:

static void copy_templates(const char *option_template)

{
	const char *template_dir = get_template_dir(option_template);
	
	...

	if (!template_dir || !*template_dir)
		return;

I would like to suggest that we document this behavior so that it can be relied upon. The motivation for omitting the default template are repositories created by tools, such as package managers, for the sole purpose of fetching some information from remotes. In this case all the stuff copied from the template (such as hooks) is an unnecessary waste of time and space.

Looking at the git-init(1) man page, the TEMPLATE DIRECTORY section seems like the natural place to document this semantics. For example, we could add the following sentence after the list of all the places where the template directory can be specified:

"If the specified template directory is an empty path (for example, --template=), then no template will be copied."

Let me know what you think.

Thanks,
Boris

Digging through the changelog, I think the feature is added in v1.5.6.4:

"git init --template=" with blank "template" parameter linked files under root directories to .git, which was a total nonsense. Instead, it means "I do not want to use anything from the template directory".

I've seen some package managers pass "--template=" to git-clone, I'd say this is a widely used undocumented feature :P Document the behavior would help people understand the existing usages of --template=

Thanks.

Thanks for digging this up. So in a sense this is an obscurely- documented behavior that people could reasonably choose to rely upon. I think only more reason to document this more prominently.

The commit which added it, d65d2b2fb4 (init: handle empty "template" parameter, 2008-07-28), notes the behavior:

init: handle empty "template" parameter

If a user passes "--template=", then our template parameter is blank. Unfortunately, copy_templates() assumes it has at least one character, and does all sorts of bad things like reading from template[-1] and then proceeding to link all of '/' into the .git directory.

This patch just checks for that condition in copy_templates and aborts. As a side effect, this means that --template= now has the meaning "don't copy any templates."

It was released in 1.5.6.5, just in case anyone is looking at the release notes for 1.5.6.4 and wondering why this isn't mentioned. :)

It came up in <[email protected]> on the list.

It's been this way for 17 years and seems unlikely to change. Documenting it ought to be a good thing.

I think that may fit best in the TEMPLATE DIRECTORY section of Documentation/git-init.adoc, if anyone here is interested in taking a stab at a patch.

You'd probably want to confirm how git init behaves when init.templatedir and GIT_TEMPLATE_DIR are set to empty values as well, to document the effects fully and save a future user wondering why the docs mention --template= and not init.templatedir or GIT_TEMPLATE_DIR.

If they all behave the same (which I believe they do), the docs could just say an empty value causes no templates to be copied, without listing each of the methods by which it might be set.

Todd

Oops, I suppose this is my fault. I agree that this is the intended behavior, and probably ought to be documented.

However, as Kristoffer mentioned, "--no-template" should work in the same way and is IMHO a bit more ergonomic. It didn't exist back when that commit was made (we weren't using parse-options yet).

So perhaps the documentation for --template ought to point people in that direction. But probably we should still mention the "empty string" behavior in all of the other spots, since as you mentioned it works equally for the config and environment variables (where is no "--no-" equivalent).

-Peff

You can apparently pass --no-templates

```
git init --template=$HOME/git-template --no-templates
```

I had a distinct description in the template directory. That was not used in the above.

Typo:

```
git init --template=$HOME/git-template --no-template
````