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

From: Jakub Narebski <[email-masked]>
Date: Sun, 03 Nov 2019 20:40:36 +0100

"brian m. carlson" <[email-masked]> writes:
> On 2019-11-03 at 15:04:44, Jakub Narebski wrote:

>> Why the change between formatting '``assume unchanged''' (with double
>> quotes and space separated) and 'skip-worktree' (without quotes, and
>> kebab-cased)?  In the commit message you write about assume-unchanged
>> and skip-worktree.
>> 
>> I guess that follows the inconsistency in git-update-index(1) headers,
>> namely we have
>> 
>>   USING ``ASSUME UNCHANGED'' BIT
>>   ------------------------------
>> 
>> but
>> 
>>   SKIP-WORKTREE BIT
>>   -----------------
>> 
>> This inconsistency is much more visible when both names are on the same
>> line, however.
>
> Yeah, I can change them to make them consistent.  I did preserve the
> existing formatting for both, as you mentioned.

Thanks in advance.  This inconsistence just looks strange in one line.

>> I'm not sure if it is a place for it, but the proposed text treats
>> assume-unchanged and skip-worktree as similarly unsuited for intended
>> purpose.  However, their failure modes are different: (ab)using the
>> assume-unchanged for "ignore changed to tracked files" may lead to data
>> loss (as changes are overwritten), while with skip-worktree the trouble
>> is that some operations that should succeed (like unstashing) are
>> unnecessarily blocked - but no data loss.
>
> I agree the failure modes can be different, but from my experience there
> are people who have seen checkout failures with both bits set
> independently.  I'm not exactly sure what those cases are, but folks do
> see them on Stack Overflow quite frequently.
>
> Even if there is a difference in failure modes, I'd rather encourage
> people to just not use this mechanism rather than explain why or in
> which cases it won't do what you want.

What I wanted to say here is that if you really, really need to abuse
those mechanism for "ignore tracked files changes", it is better to use
skip-worktree bit -- at least you wouldn't loose your data (your
precious changes).

Nb. I have experimented with both assume-unchanged and skip-worktree,
so I know their annoyances, but I have not had a need to use them.

>> I would really like to see a simple example of such template, so that
>> even people who are unfamiliar with Ruby's ERB can think of equivalent
>> solution for their language or toolchain of choice.
>
> I hesitated to mention ERB, but I wasn't sure that folks would know what
> we meant by a "templating mechanism".  The reason I had chosen to
> mention it is that someone could search for "Ruby ERB" and find out what
> it looked like and then look for an option in their own language.

I would like to see not an example of template, but example how such
template can be used in place of "ignore tracked files change".

> My concern with adding such a template is that an example will likely
> grow this section quite a bit, and it's meant as a short aside to help
> people avoid making a common mistake and guide them to a proper solution
> rather than a comprehensive howto.  I'm planning on adding a FAQ
> document in the future that covers a lot of these issues in more detail
> and helps folks figure out solutions to common problems, and I'd prefer
> to explain this more in depth there.

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.

In many cases using environment variables to provide local changes is
recommended, something like e.g.

  AWS::S3::Base.establish_connection!(
    :access_key_id     => ENV['S3_KEY'],
    :secret_access_key => ENV['S3_SECRET']
  )

Best,
-- 
Jakub Narębski