Symbolic Links
Introduction
Symbolic links, which are available in Unix/Linux (and so in Mac OS X) and in Windows, are a very handy way to store something in one place, but cause your system to act as though it is stored in two different places. They are similar to, but not the same as, Windows Shortcuts. For most purposes, symbolic links look and act like all folders. They are different from regular folders, however, in that their content comes from somewhere else on the computer's file system.
To illustrate their use, I'll use two specific examples of how they can be useful with TNG. Both will use Wampserver on Windows, so I won't be covering how to create symbolic links in Unix/Linux.
But first, I'll address a terminology problem. The term "symbolic link" is ambiguous. Sometimes, you will read
"There are two kinds of symbolic links: hard and soft."
In other places, you may read
"There are two kinds of links: hard links, and symbolic links".
Even the help text for the Windows command that creates links is ambiguous about the meaning of "symbolic" link, as you'll see below.
There are also "Junctions", which are very similar to symbolic links. But - Hard links are links to a specific file, and I will be dealing with directory links, that is, links to Windows folders, so we don't have to worry about "hard" links. - Symbolic links and Junctions have important differences when it comes to reaching across a network to shared folders on other computers. But within one environment, as in my experience and examples, I can't really find a difference, so I'll focus on Symbolic Links.
The Scenario
Again, the point of a symbolic link is to allow something stored in one place to appear that it is stored in two different places. I also have a test installation of TNG - actually several version of TNG in a WAMP environment on PC. I don't want to have several physical copies of my Gedcom extracts or my media; I want them to be stored only once, and used by used by multiple TNG instances, and my PC-based genealogy software, Family Tree Maker (FTM). To do that, I just let FTM behave as it normally does, and I use symbolic links in my TNG folders to point to FTM folders.
One factor that is somewhat distinctive to my configuration, I partition my hard disk and use my "h:" (for "home") drive for many things that might ordinarily be placed in "My Documents". But that doesn't really affect the nature of my use of symbolic links; it only affects exactly where symbolic links are placed and what they point to.
Folders for My PC Software
I have chosen a Family Tree Maker data root folder (h:\FTM) that is convenient for me. I can also control where I put Family Tree Maker Gedcom files, and have also chosen a Gedcom folder that is convenient for me, at h:\FTM\gedcom. And I can choose my FTM database (e.g. tree) names, but from there, database filename (which is not relevant here) and, more particularly, the folder name for my media files. FTM always create a subfolders named XX media, where XX is the database/tree name, and there is (unfortunately) always a space in the folder name.
Note that TNG and many PC software packages can separate different types of media files into separate folders, but Family Tree Maker cannot. So I am constrained to one media folder (per FTM tree). If you and your PC software have your media files divided among several folders that map cleanly to TNG folders, that's fine; this technique will still work, you may just have to create more symbolic links.
So, in summary,
- My FTM application folder is h:\FTM,
- My FTM Gedcom folder is h:\FTM\gedcom, and
- The media files for my primary FTM database (which I call "rr") are at h:\FTM\rr Media.
- The media files for my other FTM databases ("b" and "d") are at h:\FTM\b Media and h:\FTM\d Media.
Folders for TNG
Again, I use my H: drive, like this:
- My web server root folder is h:\rrlinux\www\.
- My primary TNG home folder is h:\rrlinux\www\family.
- My TNG Gedcom folder is (I'll say) h:\rrlinux\www\family\gedcomxx.
- The 'xx' doesn't stand for anything; it just makes the gedcom folder name different from 'gedcom'. Remember that if we call our gedcom folder 'gedcom', then anyone familiar with the TNG file structure knows exactly where to find our private Gedcom files.
- Because I have multiple TNG trees, the media files for my TNG trees (with ID's 'rr', 'b', and 'd') are stored below my root Media folder at h:\rrlinux\www\FTM\rr, h:\rrlinux\www\FTM\b, h:\rrlinux\www\FTM\d
- Note that I use the same folder name that I use with FTM. I don't have to; it just turned out to be convenient. If FTM didn't always stick that space character in its media folder names, I'd use the FTM subfolder names in TNG, too, but space character just confuse things in web applications, especially in folders.)
Multiple TNG Instances
Having one duplicate copy of each of three media folders might not be awful. But I also have multiple TNG instances in my test environment:
- My primary test environment is at localhost/family
- I have an alternate test environment at localhost/families,
- A "pristine" TNGv11.1.2 environment is at localhost/tng11.1.2
- and so on.
(It turns out that I use Apache alias, and my test environments are not all physically below the server root folder h:\rrlinux\www\', but that's a completely separate consideration, and I'll describe things as though my TNG environments are at h:\rrlinux\www\family, h:\rrlinux\www\families, h:\rrlinux\www\tng11.1.2, and so on.
Objective
I want to avoid separate copies of my Gedcom folder, and of my three media folders in each TNG environment. That is, I want the gedcom folder in each TNG environment to use the files at h:\FTM\gedcom, and I want the three media subfolders in each TNG environment to use their respective FTM media folders.
To accomplish that, I need symbolic links, which are Windows folders that actually point somewhere else in the Windows files system. Unfortunately, Windows Explorer cannot create symbolic links. It should be able to, but it can't. There are third party tools that create symbolic links, but I just use the Windows Command Prompt. The command that creates symbolic links is "mklink", and it is almost exactly like the "mkdir" command that I've been using for decades in Unix, Linux, and even MS-DOS.
'If you do not know how to use Windows Command Prompt, do not worry. You only need two command, and I'll explain them both.
The Windows Command Prompt
I suspect that most TNG site administrators - particularly those who are ambitious enough to install a web development environment on their PC's - are already familiar with the Command Prompt, but I'll try to walk slowly. I'll introduce the command prompt by noting that it predates Windows, and doesn't use a mouse. You just type commands at a prompt that identifies the folder you are in (i.e. the folder that your commands act on).
So, first, you'll need to open a command prompt window with elevated administrative privileges. You can use either of these two methods to do so:
Either way, you'll get a command prompt window. Note that the Windows Command Prompt windows prompts you with your current default folder. When you enter the command prompt window in elevated administrative mode, you start out in c:\Windows\system32.
The first thing I'll do is move to my TNG default folder, since that's where my symbolic links need to be. In my case, because I use the h: drive, I'll first have to switch to the H: drive by typing "H:", and then I'll type a cd (for Change Directory) command to move to the desired folder.
Note that I am doing all of this in Windows, so I have to use Windows filepath notation, with backslashes.
In the screen clip above, I used one cd command to go directly to the folder I was interested in. But I can also issue separate cd commands for each level in the folder hierarchy. In the example below, I'll use three cd commands to move to my default folder, and, just for illustration, move up the folder tree with two cd commands that use the notation '..' to represent the parent folder (just like file path shortcuts that you may be familiar with from Windows or Linux). Then, finally, I'll use a cd command to go back to my desired folder.
The Make Symbolic Link Command
Now that we're in the folder we want to be in, we can create our symbolic links with the mklink command. First, I'll just type mklink by itself to display help text.
Next, I will type a mklink command to create a symbolic link for my Gedcom folder gedcomxx. If gedcomxx already exists, I would have to delete it, either in Windows Explorer, or with the rmdir (for "remove directory") command. To create a symbolic direct, I need to specify the command argument /d . I need to type gedcomxx as the symbolic folder name that will point to the physical folder, and type h:\ftm\gedcom as the physical folder name.
Next, I'll use a cd command to move one level down in the folder hierarchy to the "FTM" folder. ("FTM" is not a standard TNG folder, of course. I'm using it instead of "media" or "photos" just so that my media folder structure is similar to that in FTM.) Then, I'll type a mklink command to create a symbolic link named rr that points to my FTM media folder for my database named 'rr'.
To complete the setup, I'll also need to
- Stay in this folder and create symbolic links for the b and d media folders
- Use CD to move to the main folder of next TNG environment, say, h:\rrlinux\www\families, and (if I think I need it) create a gendcomxx symbolic link),
- Move down one level into the FTM folder, and create the 3 media file symbolic links
- And repeat steps 2 and 3 for as many TNG environments as I want.
When I'm done, all the gedcom and media folders in my various TNG environments are symlinks to Family Tree Maker, and I haven't had to duplicate any Gedcom or media files.
Thumbnails
Note that, inside TNG, when I create thumbnails for my media files, I only have to do so in one TNG environment. The thumbnails will be stored in (or under) the FTM media folders, and will be available to each TNG environment that points to the FTM media folders. As far as Family Tree Maker is concerned, the thumbnails are extraneous, but, fortunately, they don't get in the way.
Creating Symlinks on Linux Servers
If you wish to create a symlink for media folders located elsewhere on your live server, the solution is very simple. You can either download and then delete the existing media folders in your tng directory via FTP, or you can change the folder names to something else in Setup --> General Settings --> Paths and Folders. (i.e., change photos to pics, documents to docs, whatever). Next you are going to create a file and name it something like media_symlinks.php. Eidt that file as follows:
<?php symlink('/path/to/folder/you/want/to/use', 'path/to/tng/folder/symlinkname'); ?>
For instance, symlink('/home/username/public_html/photos', '/home/username/public_html/tng/pics');
Upload this file to your web root (public_html, public, www) and then in your browser run it: www.yourdomain.tld/media_symlinks.php. If you get a blank page, everything worked. If you want, you can create a separate line for each symlink you want to create.
Related Links
- Symbolic Links Quick Reference a quick how to
- Wikipedia Symbolic link
- MSDN Symbolic Links
- The Complete Guide to Creating Symbolic Links (aka Symlinks) on Windows
- How to Create and Use Symbolic Links (aka Symlinks) on a Mac
- TamauraJones.net - Installing TNG on Windows (Wamp) with pictures! ;-) TNG v8, but still very applicable.
- TNG WampServer