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

"brian m. carlson" [off-list ref] writes:

On 2019-11-03 at 19:40:36, Jakub Narebski wrote:

quoted

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.

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.

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.

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