Document ability to disable template directory in git-init

Document ability to disable template directory in git-init

[Boris Kolpackov]

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

Re: [External] Document ability to disable template directory in git-init

[Han Young]

On Thu, Jul 3, 2025 at 10:51 PM Boris Kolpackov <boris@codesynthesis.com> wrote:
> Looking at the code, this undocumented (AFAICS) behavior appears to
> be there at least from git 2.1:

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 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.
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.

Re: [External] Document ability to disable template directory in git-init

[Boris Kolpackov]

Han Young <hanyang.tony@bytedance.com> writes:

> 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".

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.

Re: Document ability to disable template directory in git-init

[Todd Zullinger]

Boris Kolpackov wrote:
> Han Young <hanyang.tony@bytedance.com> writes:
> 
>> 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".
> 
> 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 <20080722200911.GA3097@sigill.intra.peff.net>
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

Re: Document ability to disable template directory in git-init

[Jeff King]

On Fri, Jul 04, 2025 at 09:53:13AM -0400, Todd Zullinger wrote:

> > 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 <20080722200911.GA3097@sigill.intra.peff.net>
> on the list.
> 
> It's been this way for 17 years and seems unlikely to
> change.  Documenting it ought to be a good thing.

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

Re: Document ability to disable template directory in git-init

[Kristoffer Haugsbakk]

On Thu, Jul 3, 2025, at 16:40, Boris Kolpackov wrote:
> 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

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.

Re: Document ability to disable template directory in git-init

[Kristoffer Haugsbakk]

On Fri, Jul 4, 2025, at 16:57, Kristoffer Haugsbakk wrote:
> You can apparently pass `--no-templates`
>
> ```
> git init --template=$HOME/git-template --no-templates
> ```

Typo:

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