Symbolic link documentation

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


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

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

"Matt Seitz (matseitz)" [off-list ref] 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.

Johannes Schindelin [off-list ref] wrote:

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

quoted

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.

Hi,

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

Johannes Schindelin [off-list ref] wrote:

quoted

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

quoted

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

From: spearce@spearce.org [mailto:spearce@spearce.org] 

quoted

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.

quoted

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

"Matt Seitz (matseitz)" [off-list ref] 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.

"Johannes Schindelin" [off-list ref] 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. 

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

"Matt Seitz (matseitz)" [off-list ref] wrote:

From: spearce@spearce.org [mailto:spearce@spearce.org] 

quoted

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.