2028

If I have a file or directory that is a symbolic link and I commit it to a Git repository, what happens to it?

I would assume that it leaves it as a symbolic link until the file is deleted and then if you pull the file back from an old version it just creates a normal file.

What does it do when I delete the file it references? Does it just commit the dangling link?

Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Alex
  • 34,776
  • 10
  • 53
  • 68
  • 29
    `.gitignore` sees the symlink as a file not a folder. – 0xcaff Feb 03 '14 at 15:34
  • 12
    Well, evidently there's more to the question than that answer implies. For instance, I'm wondering the following: if I create a sym link in my repository to some large file in that repository, push the changes, and then pull those changes to another machine, what will happen? Will the large file be stored as a large file in both locations, or will the sym link be preserved, such that on the new machine, the link file points to the original large file? – jvriesem Jun 13 '14 at 00:06
  • 10
    This is is an old thread but this comment may still be useful. In response to jviesem, a soft link is basically a file with the name of another file. So once you pull it to a different machine, the link will be downloaded and it will have the name of the big file on the original file system. If on the new machine the name isn't valid, then then link will have a invalid name. The big file will not be downloaded to the new machine. – lasaro Nov 19 '15 at 18:29
  • 11
    @lasaro, the way to avoid broken links in a git repo is to always use relative paths when making the symlinks, using `../..` as needed. – Wildcard Jan 22 '16 at 23:57
  • `git add -f filename` to add to git – HoKy22 Apr 01 '17 at 23:41
  • 15
    Notice that in most versions of Windows you need elevated permissions in order to create a symlink. If you're on Windows and `git pull` creates a file instead of symlink, try to run you Git client as administrator. – axmrnv May 30 '17 at 11:04
  • 3
    Info about what git does on Windows; https://stackoverflow.com/questions/11662868/what-happens-when-i-clone-a-repository-with-symlinks-on-windows?noredirect=1&lq=1 – brillout Oct 20 '17 at 16:10
  • 2
    For those in Windows 10, you might be happy to know that enabling developer mode removes the restriction of being an administrator (with elevated permissions). See the Microsoft article https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/ – Luke Machowski Feb 22 '22 at 03:43

4 Answers4

1627

From linux symlink manual (assuming you are in Linux):

A symbolic link is a special type of file whose contents are a string that is the pathname of another file, the file to which the link refers. (The contents of a symbolic link can be read using readlink(2).)

So a symbolic link is one more file, just as a README.md or a Makefile. Git just stores the contents of the link (i.e. the aforementioned path of the file system object that it links to) in a 'blob' just like it would for any other file. It then stores the name, mode and type (including the fact that it is a symlink) in the tree object that represents its containing directory.

When you checkout a tree containing the link, it restores the object as a symlink regardless of whether the target file system object exists or not.

If you delete the file that the symlink references it doesn't affect the Git-controlled symlink in any way. You will have a dangling reference. It is up to the user to either remove or change the link to point to something valid if needed.

onlycparra
  • 607
  • 4
  • 22
CB Bailey
  • 755,051
  • 104
  • 632
  • 656
  • 368
    BTW. If you are on filesystem like FAT that does not support symbolic links, and your repository uses them, you can set `core.symlinks` configuration variable to false, and symlinks would be checked out as small plain text files that contain the link text. – Jakub Narębski Jun 05 '09 at 09:42
  • 24
    @JakubNarębski I saw this before. There was a text file in our repo with one line, a path to a library we use. Couldn't figure out what the purpose of it was. I know now what happened. – Matt K Apr 10 '14 at 14:40
  • 47
    I hesitate to comment on highly upvoted answer but I think the phrasing "just like it would for a normal file" might be misleading to newcomers. It is like a normal file only in that the content is in a blob. The critical difference is that for a normal file the blob is the file content but for a symlink the blob has the pathname of the file it links to. – Matthew Hannigan Oct 25 '14 at 02:55
  • 15
    @JakubNarębski Regarding "small plain text files" .. You would hope they are small and text but of course a blob is a blob and potentially could be huge and binary. See http://stackoverflow.com/questions/18411200/git-unable-to-create-symlink-file-name-too-long for when a file is mistyped as a symlink. – Matthew Hannigan Oct 25 '14 at 03:15
  • 8
    Be sure to check your global settings for symlinks and the local settings for symlinks. If settings were copied over from TortiseGit or windows, then you could have `symlinks = false` messing with them. – phyatt Dec 12 '17 at 17:05
  • What about going in the other direction? I.e. the files in the repo are being linked to from elsewhere? Does that negatively affect the repo in any way? – posfan12 Sep 06 '20 at 12:50
  • 2
    @MatthewHannigan -- I hesitate to comment on a highly upvoted comment ;) but the actual file content for a symlink file literally is "the pathname of the file it links to". There is no difference in respect to the blob content. (It may be different for other OS's/FS's but this is true for a least most (all?) Unix-y environments like mac, linux, bsd, etc.) – boweeb Oct 29 '21 at 13:36
  • May I ask if the symlink created on Linux will be recognised when git pulls in the repo on Windows? The symlink structure in both OSes are different: https://unix.stackexchange.com/questions/63172/does-windows-recognize-linuxs-symbolic-links – LCZ Feb 23 '22 at 08:54
404

You can see what Git does with a symbolic link by adding it to the index. The index is like a pre-commit. When the index is committed, you can use git checkout to bring everything that was in the index back into the working directory.

So, what does Git do when you add a symbolic link to the index?

First, make a symbolic link:

$ ln -s /path/referenced/by/symlink symlink

Git doesn't know about this file yet. git ls-files lets you inspect your index (-s prints stat-like output):

$ git ls-files -s ./symlink
[nothing]

Now, add the symbolic link to the index. When you add a file to the index, Git copies its contents in the object store.

$ git add ./symlink

What was added?

$ git ls-files -s ./symlink
120000 1596f9db1b9610f238b78dd168ae33faa2dec15c 0       symlink

The hash is a reference to the packed object that was created in the object store. You can examine this object if you look in .git/objects/15/96f9db1b9610f238b78dd168ae33faa2dec15c in the root of your repository. This is the file that Git stores in the repository, that you can later check out. If you examine this file, you'll see it is very small. It does not store the contents of the linked file. To confirm this, print the contents of the packed repository object with git cat-file:

$ git cat-file -p 1596f9db1b9610f238b78dd168ae33faa2dec15c
/path/referenced/by/symlink

(Note 120000 is the mode listed in ls-files output. It would be something like 100644 for a regular file.)

But what does Git do with this object when you check it out from the repository and into your filesystem? It depends on the core.symlinks config. From man git-config:

core.symlinks

If false, symbolic links are checked out as small plain files that contain the link text.

So, with a symbolic link in the repository, upon checkout you either get a text file with a reference to a full filesystem path, or a proper symbolic link, depending on the value of the core.symlinks config.

Either way, the content of the path referenced by the symlink is not stored in the repository (unless the referenced path is also in the repository, of course).

Dmitry Minkovsky
  • 36,185
  • 26
  • 116
  • 160
  • 1
    Is the link path that's stored in the remote guaranteed to be relative if it points to a path inside the repo? What about paths to outside the repo? Is it absolute or relative to the root of project? Does it depend on how the link is made? – geekley Nov 14 '20 at 02:10
  • Yeah I think it depends on how you create the symlink. If you create it and the destination is prefixed with a `/`, then it will be absolute and may point outside your repo. Otherwise, it will be relative. If it's relative and points into your repo, it should be portable, at least between Unix-like systems. – Dmitry Minkovsky Nov 14 '20 at 02:43
  • 1
    @geekley Not sure how I dropped this by accident during editing, but you can see the contents of a git store object with `git cat-file -p`, so if your symlink's hash is `c6e5580589892eb40407c74a825afaa6c9315787`, you can do `git cat-file -p c6e5580589892eb40407c74a825afaa6c9315787` and see that pack file's contents, which is just a symlink – Dmitry Minkovsky Nov 14 '20 at 02:48
  • 4
    I like this answer more than the accepted one. – Nike Oct 13 '22 at 20:03
153

"Editor's" note: This post may contain outdated information. Please see comments and this question regarding changes in Git since 1.6.1.

Symlinked directories:

It's important to note what happens when there is a directory which is a soft link. Any Git pull with an update removes the link and makes it a normal directory. This is what I learnt hard way. Some insights here and here.

Example

Before

 ls -l
 lrwxrwxrwx 1 admin adm   29 Sep 30 15:28 src/somedir -> /mnt/somedir

git add/commit/push

It remains the same

After git pull AND some updates found

 drwxrwsr-x 2 admin adm 4096 Oct  2 05:54 src/somedir
Peter Mortensen
  • 30,738
  • 21
  • 105
  • 131
Shekhar
  • 7,095
  • 4
  • 40
  • 45
  • I'm trying to solve this problem that I've been getting as well. Seems like a bug with git-pull translating the result for some reason. – Kevin Apr 04 '11 at 21:10
  • 22
    Is this behavior present on all versions of git or has this been fixed with? – jbotnik Jun 09 '11 at 20:28
  • 24
    It seems like this behaviour is fixed now, see: http://stackoverflow.com/a/1943656/1334781 – Ron Wertlen Sep 25 '14 at 08:15
  • 6
    It's worth noting that these warnings about symlinked directories **do not** apply to versioned symlinks. The major edge case in question was that of folks symlinking some or all of the working tree into a different path (say onto a different partition with more disk space) and expecting git to check out code through the existing symlink. That is, if you have a project that contains versioned symlinks to files or directories, the normal symlink-as-blob behavior will preserve symlinks, correctly version changes to those symlinks, and otherwise work as expected. – John Whitley Dec 22 '09 at 01:18
  • *The above behavior tested with git 1.6.5.6; but I strongly suspect that versioned behavior has been correct in git for quite some time.* – John Whitley Dec 22 '09 at 01:18
  • 2
    Shekar: Will you place edit your answer to reflect changes in git in recent years? – einpoklum Jun 22 '17 at 18:46
  • 3
    @RonWertlen That is a link to this same question. – alx - recommends codidact Aug 05 '20 at 08:33
5

Special case: When "git checkout"(man) removes a path that does not exist in the commit it is checking out, it wasn't careful enough not to follow symbolic links, which has been corrected with Git 2.32 (Q2 2021).

See commit fab78a0, commit 462b4e8 (18 Mar 2021) by Matheus Tavares (matheustavares).
(Merged by Junio C Hamano -- gitster -- in commit 9210c68, 30 Mar 2021)

checkout: don't follow symlinks when removing entries

Signed-off-by: Matheus Tavares

At 1d718a5 ("do not overwrite untracked symlinks", 2011-02-20, Git v1.7.5-rc0 -- merge), symlink.c:check_leading_path() started returning different codes for FL_ENOENT and FL_SYMLINK.
But one of its callers, unlink_entry(), was not adjusted for this change, so it started to follow symlinks on the leading path of to-be-removed entries.
Fix that and add a regression test.

And because we no longer try to unlink such paths, we also don't get the warning from remove_or_warn().

For the regular file and symlink cases, it's questionable whether the warning was useful in the first place: unlink_entry() removes tracked paths that should no longer be present in the state we are checking out to.
If the path had its leading dir replaced by another file, it means that the basename already doesn't exist, so there is no need for a warning.
Sure, we are leaving a regular file or symlink behind at the path's dirname, but this file is either untracked now (so again, no need to warn), or it will be replaced by a tracked file during the next phase of this checkout

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250