[PATCH] Document escaping of special characters in gitignore files

[PATCH] Document escaping of special characters in gitignore files

[Jakub Narebski]

You can use backslash to escape special characters, like '#' or '*',
in gitignore files.

Requested-by: Bruce Korb <bruce.korb@gmail.com>
Signed-off-by: Jakub Narebski <jnareb@gmail.com>
---
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'.

 Documentation/gitignore.txt |    7 +++++++
 templates/info--exclude     |    1 +
 2 files changed, 8 insertions(+), 0 deletions(-)

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.
 
  - An optional prefix '!' which negates the pattern; any
    matching file excluded by a previous pattern will become
@@ -98,6 +99,12 @@ Patterns have the following format:
    For example, "/{asterisk}.c" matches "cat-file.c" but not
    "mozilla-sha1/sha1.c".
 
+ - You can escape special characters using backslash.
+   For example, "{backslash}#*" matches files beginning in `#`
+   (otherwise it would be considered comment),
+   and "{backslash}!*{backslash}?" matches files starting with `!`
+   (negate pattern prefix) and ending with `?` (glob wildcard).
+
 NOTES
 -----
 
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]
 # *~
+# \#*#
-- 
1.7.3

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

[Andreas Schwab]

Jakub Narebski <jnareb@gmail.com> writes:

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

Should this be written as `{backslash}#`?

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

[Junio C Hamano]

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.

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

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

[Jakub Narebski]

On Wed, 5 Jan 2011, Junio C Hamano wrote:
> 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.

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

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

[Thomas Rast]

Jakub Narebski wrote:
> 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.

This is correct, but the behaviour you quote was introduced in a minor
release of asciidoc (!!!).  From 71c020c5:

    Disable asciidoc 8.4.1+ semantics for `{plus}` and friends
    
    asciidoc 8.4.1 changed the semantics of inline backtick quoting so
    that they disable parsing of inline constructs, i.e.,
    
      Input:    `{plus}`
      Pre 8.4.1:        +
      Post 8.4.1:       {plus}
    
    Fix this by defining the asciidoc attribute 'no-inline-literal'
    (which, per the 8.4.1 changelog, is the toggle to return to the old
    behaviour) when under ASCIIDOC8.

So in fact with current settings in Documentation/Makefile, the brace
escapes *are* expanded even within backticks.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

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

[Bruce Korb]

On 01/05/11 11:27, Jakub Narebski wrote:
>>> +++ 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.

As the source of this thread, I, too, use emacs and it is exactly
the problem of trying to figure out how to get git to ignore these
auto save files that got me down this path.  It was too hard to figure out.
So I suggested some doc changes and the addition of the "exclude
emacs auto save files" pattern to the sample text.  People who do not
use emacs would not understand the \#*# line and folks who do would.
They see files like that all the time.  For the sake of vi users, you
might want to explain them, but I don't think it is crucial.
It *is* important to have an example of a needs-to-be-escaped file name.

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

[Junio C Hamano]

Bruce Korb <bruce.korb@gmail.com> writes:

> On 01/05/11 11:27, Jakub Narebski wrote:
>>>> +++ 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.
>
> As the source of this thread, I, too, use emacs and it is exactly
> the problem of trying to figure out how to get git to ignore these
> auto save files that got me down this path.  It was too hard to figure out.
> So I suggested some doc changes and the addition of the "exclude
> emacs auto save files" pattern to the sample text.  People who do not
> use emacs would not understand the \#*# line and folks who do would.
> They see files like that all the time.  For the sake of vi users, you
> might want to explain them, but I don't think it is crucial.
> It *is* important to have an example of a needs-to-be-escaped file name.

Perhaps a single liner comment to describe the three examples immediately
below "exclude patterns (uncomment them..." is in order in that case,
something like:

# exclude patterns (object and library, emacs backup, emacs autosave
# files) -- uncomment if you want to use them
# *.[oa]
# *~
# \#*#

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

[Jakub Narebski]

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

> Perhaps a single liner comment to describe the three examples immediately
> below "exclude patterns (uncomment them..." is in order in that case,
> something like:
> 
> # exclude patterns (object and library, emacs backup, emacs autosave
> # files) -- uncomment if you want to use them
> # *.[oa]
> # *~

Errr... I think that '*~' pattern is generic UNIX backup, like '*.bak'
is for MS-DOS / MS Windows.

http://en.wikipedia.org/wiki/Tilde#Backup_filenames

  Backup filenames

  The dominant Unix convention for naming backup copies of files is
  appending a tilde to the original file name. It originated with the
  Emacs text editor[citation needed] and was adopted by many other
  editors and some command-line tools.

> # \#*#

Anyway, should I reroll this patch with above addition?  Should I add
an explanation why we can use `\#` but need to use "{tilde}#"? 
-- 
Jakub Narebski
Poland