Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files

From: Jakub Narebski <jnareb@gmail.com>
Date: Nov 5, 2019, 00:21 UTC
Message-ID: <86imnzgoll.fsf@gmail.com>
In-Reply-To: <20191103214608.GC32531@camp.crustytoothpaste.net>

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

Show 37 quoted lines

> On 2019-11-03 at 19:40:36, Jakub Narebski wrote:
>>
>> Your proposed change:
>> 
>>   +If the file you want to change is some sort of configuration file (say,
>>   +for a build tool, IDE, or editor), a common solution is to use a
>>   +templating mechanism, such as Ruby's ERB, to generate the ignored
>>   +configuration file from a template stored in the repository and a source
>>   +of data using a script or build step.
>> 
>> I don't see how such templating mechanism could be used.  You have some
>> kind of configuration file with placeholders comitted, and you have a
>> version of this file with local changes -- how templating mechanism
>> could solve this?  I would like to see few lines of an example and its
>> use.
>> 
>> Alternatives:
>> ~~~~~~~~~~~~~
>> 
>> In our build system, we have versioned Makefile, and not versioned
>> config.mak (with local configuration), which is included by Makefile.
>
> Essentially, make and shell support this by themselves, but if, for
> example, I wanted to adjust my dotfiles to set the email address once
> and for all, I could create the following files:
>
> .muttrc.erb:
> ----
> my_hdr From: brian m. carlson <<%= data["email"] -%>>
> ----
>
> .gitconfig.erb:
> ----
> [user]
> name = brian m. carlson
> email = <%= data["email"] -%>
> ----

All right, the above might be useful as an example (well, one of those), but might be not necessary if the description of preferred solution is stated in more detail. I think it is better to start with generics, i.e. track template, and generate untracked file, then provide examples like Ruby's ERB.

Show 24 quoted lines

> template.rb:
> ----
> #!/usr/bin/env ruby
>
> require 'erb'
>
> class Template
>   def name
>     @name ||= 0
>     @name += 1
>     "name_a#{@name}"
>   end
>
>   def data
>     ENV.map { |k, v| [k.downcase, v] }.to_h
>   end
>
>   def erb(file)
>     ERB.new(File.read(file), nil, '-', name).result(binding)
>   end
> end
>
> puts Template.new.erb(ARGV[0])
> ----

This is certainly too much detail.

> and then run:
>
> EMAIL=sandals@crustytoothpaste.net template.rb .muttrc.erb >.muttrc
> EMAIL=sandals@crustytoothpaste.net template.rb .gitconfig.erb >.gitconfig

That could be kept as an example, after simplification.

Show 6 quoted lines

> The problem that folks tend to have is that they have a single editor or
> IDE project file, such as an XCode configuration file, that can't be
> split among multiple files, some of which are checked in and some of
> which are not.  Other situations are generating a configuration file for
> a web server like nginx in development, which may of course differ
> depending on where the user has checked out the repository.

All right.

Show 6 quoted lines

> Using some sort of file like a config.mak is a fine solution, but many
> programs don't support that, so it's necessary to create a template for
> the build process and add a script to generate it.  The actual
> configuration values can come from the environment, the user's
> gitconfig, a YAML file the user has configured, or anywhere else that
> makes sense.

I still think that config.mak (or equivalent) solution might be worth mentioning in passing.

> As you can see, the example is large and unwieldy, and would not make a
> good inclusion in the man page.  I included that paragraph because Peff
> stated that it would be nice if we could offer people a solution, but
> I'd rather drop it if it's too confusing without an example.

I think it can be done even without example, but without example it would need careful crafting of the wording.

Best,

-- 
Jakub Narębski