Re: [PATCH] Document escaping of special characters in gitignore files

From: Jakub Narebski <jnareb@gmail.com>
Date: Jan 5, 2011, 19:27 UTC
Message-ID: <201101052027.24640.jnareb@gmail.com>
In-Reply-To: <7vwrmjchuu.fsf@alter.siamese.dyndns.org>

On Wed, 5 Jan 2011, Junio C Hamano wrote:

Show 25 quoted lines

> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > This patch was originally send 10 Sep 2010, but I guess it was lost
> > because it appeared only deep in thread inside response, and not as
> > well separated patch.  I have found about it when I got conflict
> > merging current code.
> >
> > It applies on top of current 'master'.
> 
> Thanks.  A few questions before applying.
> 
> > diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
> > index 7dc2e8b..20abc20 100644
> > --- a/Documentation/gitignore.txt
> > +++ b/Documentation/gitignore.txt
> > @@ -68,6 +68,7 @@ Patterns have the following format:
> >     for readability.
> >  
> >   - A line starting with # serves as a comment.
> > +   Use `\#` for a literal # character starting filename.
> 
> Is a literal bs safe here?  You later use "{backslash}#" in this same
> file, and it might make sense to do so here for the sake of source
> readability, even if a literal bs is safe here---provided that
> "{backslash}#" does not break here, of course.

First, I have checked how it is done in current codebase, and as one can check, inside backtics escape sequences are written literally, e.g. `\"`, `\\` in Documentation/config.txt -- notice that those are about escaping of special characters too.

Second, http://www.methods.co.nz/asciidoc/userguide.html#_text_formatting ("7. Text Formatting", "7.1. Quoted Text") says (emphasizis mine):

  Word phrases `enclosed in backtick characters` (grave accents) are also
  rendered in a monospaced font but in this case the enclosed text is
  __rendered literally__ and is not subject to further expansion (see
  inline literal).

So yes, it is safe, and no, `{backslash}#` would not work.

I later use "{backslash}#" because it is inside double quotes, and not backticks. It is similar to how {caret} is treated inside double or single quotes.

Show 19 quoted lines

> > @@ -98,6 +99,12 @@ Patterns have the following format:
> > ...
> > + - You can escape special characters using backslash.
> > +   For example, "{backslash}#*" matches files beginning in `#`
> > ...
> 
> > diff --git a/templates/info--exclude b/templates/info--exclude
> > index a5196d1..2ebaf0d 100644
> > --- a/templates/info--exclude
> > +++ b/templates/info--exclude
> > @@ -4,3 +4,4 @@
> >  # exclude patterns (uncomment them if you want to use them):
> >  # *.[oa]
> >  # *~
> > +# \#*#
> 
> Do we need this?  Without explanation it is somewhat hard to realize that
> this last line is also an example of a pattern that excludes any filename
> that begins and ends with a pound.

Well, perhaps not. Note though that this exclude pattern is actually useful for me, as GNU Emacs uses this convention ("#<filename>#") for auto-save files. From "(emacs.gz)Auto Save Files":

     Auto-saving does not normally save in the files that you visited,
  because it can be very undesirable to save a program that is in an
  inconsistent state when you have made half of a planned change.
  Instead, auto-saving is done in a different file called the "auto-save
  file", and the visited file is changed only when you request saving
  explicitly (such as with `C-x C-s').

     Normally, the auto-save file name is made by appending `#' to the
  front and rear of the visited file name.  Thus, a buffer visiting file
  `foo.c' is auto-saved in a file `#foo.c#'.

-- 
Jakub Narebski
Poland