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 incconsistency is much more viible 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.

> 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.

> 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.

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