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

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Nov 3, 2019, 21:46 UTC
Message-ID: <20191103214608.GC32531@camp.crustytoothpaste.net>
In-Reply-To: <861ruoiw97.fsf@gmail.com>

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

Show 19 quoted lines

> 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