[PATCH] Some documentation...

Hi

I'm starting to write some docs...
Comments... even "yep, looks OK, carry on" :)

I plan on putting the 'git command' ones into the 'git help ...' 
structure once Petr accepts it.
I guess the low level ones go into a README.reference until they 
stabilise and become man pages...

In doing this I noticed a couple of points:
* update-cache won't accept ./file or fred/./file
* checkout-cache doesn't seem to preserve mode

Are these bugs or should they be documented?
I've taken the approach of documenting behaviour for now.

Signed-off-by: David Greaves <redacted>
---

On Wed, 20 Apr 2005, David Greaves wrote:

In doing this I noticed a couple of points:
* update-cache won't accept ./file or fred/./file

The comment in update-cache.c reads:
/*
  * We fundamentally don't like some paths: we don't want
  * dot or dot-dot anywhere, and in fact, we don't even want
  * any other dot-files (.git or anything else). They
  * are hidden, for chist sake.
  *
  * Also, we don't want double slashes or slashes at the
  * end that can make pathnames ambiguous.
  */

It could be argued that './' is a special case... but at the moment this 
is definitely a designed 'feature' not a 'bug'.
  --scott

BLUEBIRD SEQUIN SECANT Waihopai Honduras KUDOVE genetic KUJUMP SCRANTON 
DES AMLASH Indonesia SLINC cracking ESMERALDITE mustard Uzi KUSODA
                          ( http://cscott.net/ )

C. Scott Ananian wrote:

On Wed, 20 Apr 2005, David Greaves wrote:

quoted

In doing this I noticed a couple of points:
* update-cache won't accept ./file or fred/./file

The comment in update-cache.c reads:
/*
 * We fundamentally don't like some paths: we don't want
 * dot or dot-dot anywhere, and in fact, we don't even want
 * any other dot-files (.git or anything else). They
 * are hidden, for chist sake.
 *
 * Also, we don't want double slashes or slashes at the
 * end that can make pathnames ambiguous.
 */

It could be argued that './' is a special case... but at the moment this 
is definitely a designed 'feature' not a 'bug'.

Indeed - I've been reading the code to document it as correctly as possible.

But I actually found this by running:

   find . -type f | xargs git add

for a new project - so I'd class it as user unfriendly...
Yes, I know how to get round it :)

I have ensured that my next perl version of gitadd.pl (that I submitted 
to Petr) doesn't allow these files to be added - and it could even 
cleanse leading ./ and any /./ constructs.

So maybe it's left as documented behaviour and higher level tools must 
manage the data they feed to it...

I hope it's useful to raise these niggles now before changing them is 
too hard.

David

-- 

On Wed, 20 Apr 2005, David Greaves wrote:

So maybe it's left as documented behaviour and higher level tools must 
manage the data they feed to it...

That was the plan.

I agree that "find . -type f | xargs update-cache --add --" in _theory_ is
a nice thing to do. But in practice, you want to make sure that find 
doesn't incldue the ".git" directory and that we always use the canonical 
names for all files etc etc.

I could do it in the low-level tools (ie do pathname cleanup there), and
indeed I did exactly that in the original code sequence. However, it very
quickly became obvious that the low-level code really doesn't want to
care, and that it's a lot easier to just do it at a higher level when 
necessary.

For example, if you have to add a sed-script or something that just 
removes '^./' and "^.git/", then that's trivial to do, and it leaves the 
core tools with a very clear agenda in life.

		Linus