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

["brian m. carlson" <sandals@crustytoothpaste.net>]

[-- Attachment #1: Type: text/plain, Size: 2936 bytes --]

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.
> 
> Alterantives:
> ~~~~~~~~~~~~~
> 
> 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"] -%>
----

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])
----

and then run:

EMAIL=sandals@crustytoothpaste.net template.rb .muttrc.erb >.muttrc
EMAIL=sandals@crustytoothpaste.net template.rb .gitconfig.erb >.gitconfig

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.

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.

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.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]