Symbolic link documentation

Symbolic link documentation

[Matt Seitz (matseitz)]

[-- Attachment #1: Type: text/plain, Size: 170 bytes --]

Where does the git user documentation discuss how git handles symbolic
links?


--
Matt Seitz
Manager, File System Virtualization
Cisco Systems, Inc.
.:|:.:|:. 

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Matt Seitz.vcf --]
[-- Type: text/x-vcard; name="Matt Seitz.vcf", Size: 410 bytes --]

BEGIN:VCARD
VERSION:2.1
N:Seitz;Matt
FN:Matt Seitz
ORG:Cisco Systems, Inc
TITLE:Manager
TEL;WORK;VOICE:408-200-8000
ADR;WORK:;;3975 Freedom Circle, Floor 8;Santa Clara;CA;95054;United States of America
LABEL;WORK;ENCODING=QUOTED-PRINTABLE:3975 Freedom Circle, Floor 8=0D=0ASanta Clara, CA 95054=0D=0AUnited States o=
f America
EMAIL;PREF;INTERNET:matseitz@cisco.com
REV:20070709T234049Z
END:VCARD

Re: Symbolic link documentation

[Johannes Schindelin]

Hi,

On Thu, 20 Sep 2007, Matt Seitz (matseitz) wrote:

> Where does the git user documentation discuss how git handles symbolic 
> links?

$ git grep symbolic Documentation/ | grep link
Documentation/RelNotes-1.5.0.2.txt:    in place of the symbolic link.  The default strategy,
Documentation/RelNotes-1.5.0.2.txt:    that was pointed at by the symbolic link.  Both of these
Documentation/RelNotes-1.5.0.2.txt:    when changes to a symbolic link conflicted.  It should have
Documentation/RelNotes-1.5.0.2.txt:    file the symbolic link pointed at.
Documentation/RelNotes-1.5.1.5.txt:    directory $PWD points at is a symbolic link.
Documentation/RelNotes-1.5.1.6.txt:    directory $PWD points at is a symbolic link.
Documentation/RelNotes-1.5.1.txt:    in place of the symbolic link.  The default strategy,
Documentation/RelNotes-1.5.1.txt:    that was pointed at by the symbolic link.  Both of these
Documentation/RelNotes-1.5.1.txt:    when changes to a symbolic link conflicted.  It should have
Documentation/RelNotes-1.5.1.txt:    file the symbolic link pointed at.
Documentation/RelNotes-1.5.3.2.txt:   - an untracked symbolic link to a directory made it fart;
Documentation/config.txt:	If false, symbolic links are checked out as small plain files that
Documentation/config.txt:	symbolic links. True by default.
Documentation/config.txt:	and other symbolic reference files, use symbolic links.
Documentation/config.txt:	expect HEAD to be a symbolic link.
Documentation/core-tutorial.txt:   This is similar to a symbolic link and points at
Documentation/git-local-fetch.txt:	Instead of regular file-to-file copying use symbolic links to the objects
Documentation/git-symbolic-ref.txt:In the past, `.git/HEAD` was a symbolic link pointing at
Documentation/git-symbolic-ref.txt:advertised (horrors).  Therefore symbolic links are now deprecated
Documentation/git-update-index.txt:to 'false' (see gitlink:git-config[1]), symbolic links are checked out
Documentation/git-update-index.txt:from symbolic link to regular file.
Documentation/git-update-ref.txt:these symbolic pointers, whether they are symlinks or these
Documentation/git-update-ref.txt:"regular file symbolic refs".  It follows *real* symlinks only
Documentation/glossary.txt:	references are manipulated with the gitlink:git-symbolic-ref[1]
Documentation/repository-layout.txt:	a symbolic link instead of a symref that points at the current
Documentation/technical/racy-git.txt:files vs symbolic links) and executable bits (only for regular

Hth,
Dscho

Re: Symbolic link documentation

[Shawn O. Pearce]

"Matt Seitz (matseitz)" <matseitz@cisco.com> wrote:
> Where does the git user documentation discuss how git handles symbolic
> links?

About the only mention I can find appears to be in git-config where
it talks a little bit about the core.symlinks configuration option.

But in general Git treats symlinks as though they were plain text
files.  The content of the "file" is the target of the symlink.
Use `git-add link` to stage the symlink for the next commit (just
like a file), `git-mv` to rename a symlink (just like a file), etc.
Editing a symlink to point to a new target is just a matter of
using the OS' tools (e.g. `ln -sf newdst link`).

So long as core.symlinks isn't set or is set to true Git will
recreate the symlink upon checkout of the revision, just like it
recreates plain text files.

-- 
Shawn.

Re: Symbolic link documentation

[Shawn O. Pearce]

Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> On Thu, 20 Sep 2007, Matt Seitz (matseitz) wrote:
> 
> > Where does the git user documentation discuss how git handles symbolic 
> > links?
> 
> $ git grep symbolic Documentation/ | grep link
> Documentation/RelNotes-1.5.0.2.txt:    in place of the symbolic link.  The default strategy,
> Documentation/RelNotes-1.5.0.2.txt:    that was pointed at by the symbolic link.  Both of these
> Documentation/RelNotes-1.5.0.2.txt:    when changes to a symbolic link conflicted.  It should have
> Documentation/RelNotes-1.5.0.2.txt:    file the symbolic link pointed at.
> Documentation/RelNotes-1.5.1.5.txt:    directory $PWD points at is a symbolic link.
> Documentation/RelNotes-1.5.1.6.txt:    directory $PWD points at is a symbolic link.
> Documentation/RelNotes-1.5.1.txt:    in place of the symbolic link.  The default strategy,
> Documentation/RelNotes-1.5.1.txt:    that was pointed at by the symbolic link.  Both of these
> Documentation/RelNotes-1.5.1.txt:    when changes to a symbolic link conflicted.  It should have
> Documentation/RelNotes-1.5.1.txt:    file the symbolic link pointed at.
> Documentation/RelNotes-1.5.3.2.txt:   - an untracked symbolic link to a directory made it fart;

Many of these release notes are talking about bugs that we fixed
related to switching between revisions where in one revision the
path was a symlink and in the other revision it was a directory or
a file (or vice-versa).

> Documentation/config.txt:	If false, symbolic links are checked out as small plain files that
> Documentation/config.txt:	symbolic links. True by default.
> Documentation/git-update-index.txt:to 'false' (see gitlink:git-config[1]), symbolic links are checked out
> Documentation/git-update-index.txt:from symbolic link to regular file.
> Documentation/technical/racy-git.txt:files vs symbolic links) and executable bits (only for regular

These are probably what Matt was looking for.

> Documentation/config.txt:	and other symbolic reference files, use symbolic links.
> Documentation/config.txt:	expect HEAD to be a symbolic link.
> Documentation/core-tutorial.txt:   This is similar to a symbolic link and points at
> Documentation/git-local-fetch.txt:	Instead of regular file-to-file copying use symbolic links to the objects
> Documentation/git-symbolic-ref.txt:In the past, `.git/HEAD` was a symbolic link pointing at
> Documentation/git-symbolic-ref.txt:advertised (horrors).  Therefore symbolic links are now deprecated
> Documentation/git-update-ref.txt:these symbolic pointers, whether they are symlinks or these
> Documentation/git-update-ref.txt:"regular file symbolic refs".  It follows *real* symlinks only
> Documentation/glossary.txt:	references are manipulated with the gitlink:git-symbolic-ref[1]
> Documentation/repository-layout.txt:	a symbolic link instead of a symref that points at the current

These are all about how Git stores refs, and how HEAD used to be
a symbolic link but has since changed to a symbolic reference...
So less useful to what he was looking for I think.

-- 
Shawn.

RE: Symbolic link documentation

[Matt Seitz (matseitz)]

[-- Attachment #1: Type: text/plain, Size: 1006 bytes --]

From: spearce@spearce.org [mailto:spearce@spearce.org] 
> 
> > Documentation/git-update-index.txt:to 'false' (see 
> > gitlink:git-config[1]), symbolic links are checked out 
> Documentation/git-update-index.txt:from symbolic link to regular file.
> > Documentation/technical/racy-git.txt:files vs symbolic links) and 
> > executable bits (only for regular
> 
> These are probably what Matt was looking for.

The git-update-index and git-update-ref manual references are the
closest to what I was looking for.  Both are more low-level and
technical than what I was hoping for, and the discussion in
git-update-index seems targeted primarily at how symlinks are translated
on file systems that don't support symlinks.

I guess I was looking for something like the GNU "tar" documentation of
how symlinks are handled
(http://www.gnu.org/software/tar/manual/html_node/dereference.html#deref
erence).

--
Matt Seitz
Manager, File System Virtualization
Cisco Systems, Inc.
.:|:.:|:.  

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Matt Seitz.vcf --]
[-- Type: text/x-vcard; name="Matt Seitz.vcf", Size: 410 bytes --]

BEGIN:VCARD
VERSION:2.1
N:Seitz;Matt
FN:Matt Seitz
ORG:Cisco Systems, Inc
TITLE:Manager
TEL;WORK;VOICE:408-200-8000
ADR;WORK:;;3975 Freedom Circle, Floor 8;Santa Clara;CA;95054;United States of America
LABEL;WORK;ENCODING=QUOTED-PRINTABLE:3975 Freedom Circle, Floor 8=0D=0ASanta Clara, CA 95054=0D=0AUnited States o=
f America
EMAIL;PREF;INTERNET:matseitz@cisco.com
REV:20070709T234049Z
END:VCARD

Re: Symbolic link documentation

[Johannes Schindelin]

Hi,

On Thu, 20 Sep 2007, Shawn O. Pearce wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> > On Thu, 20 Sep 2007, Matt Seitz (matseitz) wrote:
> > 
> > > Where does the git user documentation discuss how git handles 
> > > symbolic links?
> > 
> > $ git grep symbolic Documentation/ | grep link
> > [...]
> > Documentation/config.txt:	If false, symbolic links are checked out as small plain files that
> > Documentation/config.txt:	symbolic links. True by default.
> > Documentation/git-update-index.txt:to 'false' (see gitlink:git-config[1]), symbolic links are checked out
> > Documentation/git-update-index.txt:from symbolic link to regular file.
> > Documentation/technical/racy-git.txt:files vs symbolic links) and executable bits (only for regular
> 
> These are probably what Matt was looking for.

Well, he asked where the git user documentation talks about symbolic 
links, and I provided a pointer.

Ciao,
Dscho

Re: Symbolic link documentation

[Shawn O. Pearce]

"Matt Seitz (matseitz)" <matseitz@cisco.com> wrote:
> The git-update-index and git-update-ref manual references are the
> closest to what I was looking for.  Both are more low-level and
> technical than what I was hoping for, and the discussion in
> git-update-index seems targeted primarily at how symlinks are translated
> on file systems that don't support symlinks.
> 
> I guess I was looking for something like the GNU "tar" documentation of
> how symlinks are handled
> (http://www.gnu.org/software/tar/manual/html_node/dereference.html#deref
> erence).

Git never dereferences a symlink that are stored as part of the
revision data.  The only time we dereference a symlink is when it
is used inside of .git/refs, or as .git/HEAD, which is what the
git-update-ref manpage was talking about.

So Git handles symlinks in the working tree *without* dereferencing
them.  Internally we store the target of the symlink, much as
tar would store the target of the symlink.  There is no way to
activate a dereference behavior (--dereference / -h in GNU tar)
as typically you want to preseve the symlink as a symlink to the
target; its part of your source code.

Maybe this is a good hint that the user manual should have a section
on symbolic links.  Its obvious to old Git hands that a symlink is
nothing more than a file with a slightly different mode, but that
may not be obvious to people who are new to Git.

-- 
Shawn.

Re: Symbolic link documentation

[Matt Seitz]

"Johannes Schindelin" <Johannes.Schindelin@gmx.de> wrote in message 
news:Pine.LNX.4.64.0709201851190.28395@racer.site...
>
> Well, he asked where the git user documentation talks about symbolic
> links, and I provided a pointer.

Thanks, I appreciated the pointers. 

RE: Symbolic link documentation

[Matt Seitz (matseitz)]

[-- Attachment #1: Type: text/plain, Size: 351 bytes --]

From: spearce@spearce.org [mailto:spearce@spearce.org] 
> 
> So Git handles symlinks in the working tree *without* 
> dereferencing them.  

Thanks.  Is there a recommended procedure for tracking changes when the
symlink target is outside the working tree?

--
Matt Seitz
Manager, File System Virtualization
Cisco Systems, Inc.
.:|:.:|:.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Matt Seitz.vcf --]
[-- Type: text/x-vcard; name="Matt Seitz.vcf", Size: 410 bytes --]

BEGIN:VCARD
VERSION:2.1
N:Seitz;Matt
FN:Matt Seitz
ORG:Cisco Systems, Inc
TITLE:Manager
TEL;WORK;VOICE:408-200-8000
ADR;WORK:;;3975 Freedom Circle, Floor 8;Santa Clara;CA;95054;United States of America
LABEL;WORK;ENCODING=QUOTED-PRINTABLE:3975 Freedom Circle, Floor 8=0D=0ASanta Clara, CA 95054=0D=0AUnited States o=
f America
EMAIL;PREF;INTERNET:matseitz@cisco.com
REV:20070709T234049Z
END:VCARD

Re: Symbolic link documentation

[Shawn O. Pearce]

"Matt Seitz (matseitz)" <matseitz@cisco.com> wrote:
> From: spearce@spearce.org [mailto:spearce@spearce.org] 
> > 
> > So Git handles symlinks in the working tree *without* 
> > dereferencing them.  
> 
> Thanks.  Is there a recommended procedure for tracking changes when the
> symlink target is outside the working tree?

Move the link target so its inside the working tree?

Git won't step outside of the working tree to look for or to record
changes.  Its outside.  We don't track things outside of the part
of the world you've asked us to track.

-- 
Shawn.