migrate from default to multi-site within same install?

@Breakeradi
What I would use it for is to move a website in test (http://www.domain.tld/newsite2review/) to production (http://www.domain.tld/). At least, that is my expectation when I read the description of the module; I have not installed it yet.

This module is specifically for changing the address (URL) of a mult-site site.

Multiple Multi-Site Sites Example (Rename):

You have a site that is using three domains + default to total four sites on separate domains.

/sites/default
/sites/www.example1.com
/sites/www.example2.com
/sites/www.example3.com

Two years into the life of your sites you decided to re-brand example3.com as well as change it's domain. Now there's a few ways you can do this (duplicate + rename, symbolic link, SQL, manual or this module) but I'm only going to cover this module in the example.

You then rename your www.example3.com directory to be www.mysupernewsite.com.

/sites/default
/sites/www.example1.com
/sites/www.example2.com
/sites/www.mysupernewsite.com

If you just rename your directory and people go to http://www.mysupernewsite.com there will be a lot of references to /sites/www.example3.com/files in your content, blocks, profile pictures and cck file fields (among other modules). Since you renamed your directory but didn't update the paths in your content, blocks, etc. you'll get bad links to images and miscellaneous files. This is the point where this module does it's thing. It runs a few queries to go through your data and replaces the old /sites/www.example3.com references with /sites/www.mysupernewsite.com so now all of your uploaded images, mp3s, profile pictures etc. are properly mapped to the new directory name. In the end your links to the files look like they were always done on this site and there's no old URL cruft.

Note: This example also applies for a development environment name/directory to a production domain name migration as well.

Default to Multi-Site Example (Merger):

It's not uncommon for a site to start off as being the only site (housed in default) but then to be moved to an existing multi-site setup or have more sites added. For this example we'll have a site called SiteB that was separate but then needs to become part of the first example's multi-site setup (Lets just say there was a merger between two companies that happen to run the same Drupal version).

SiteA:
/sites/default
/sites/www.example1.com
/sites/www.example2.com
/sites/www.mysupernewsite.com

SiteB:
/sites/default

The SiteB /sites/default would need to be named to it's full URL www.littlecompanysite.com and then copied/moved over to the SiteA /sites directory.

The directory structure would now look like:

SiteA:
/sites/default
/sites/www.example1.com
/sites/www.example2.com
/sites/www.mysupernewsite.com
/sites/www.littlecompanysite.com

SiteB:
(Empty, it's not needed)

After the copy/move all of your file references in content, blocks, profile pictures, cck file fields would be pointing at /sites/default. Since you already have a /sites/default from SiteA you can't use the symbolic link or the duplicate + rename methods. At this point you either need to run this module or dive into the SQL.

Note: This example also applies for a Muti-Site to a Default configuration as well.

Alternatives to this module

Why not just use duplicate + rename?

This will actually work on just about every operating system out there but it brings along most of the issues that the symbolic links do plus some new ones. The new issues that are specific to this type of migration is you now have two copies of your sites directory, one old and stagnating and one new and up to date + the old files. This takes up unnecessary room as well as makes your site directory confusing (I guarantee anybody who has used this method has at least once uploaded a file to the old /sites directory - via FTP - and spent a while trying to figure out why the file wasn't showing up). This module gets around that issue.

Why not just use symbolic links?

Symbolic links are a quick and dirty way to get around the renaming of your directory while keeping your references intact but they are somewhat messy. When you do this, you still keep your references to the old domain (in this case /sites/www.example3.com) which isn't too horrible but after your site is around for a few years, you've had a few domain names (which end up cascading symbolic links) and you've changed hosts a few times the links to your files in your various content will be a horrible mess (and very confusing). This module gets around that issue (also, symbolic links don't work in Windows.) For people who wonder, I've actually had a client rename their site URL four times within one week.

Why not just use SQL to update your content?

I've done this before and it's not a bad way to go. On it's lowest level, that's all this module does. This module just makes it a little easier for you to do (without having to mess around with the SQL.) It's easier for developers and makes this type of migration possible for non-programmer types.

Why not just manually update your content?

For nodes and blocks this is 100% possible, I wouldn't want to do it even on a small site but it is a possibility. On large sites manual updates just aren't practical. There are some things that you cannot update through Drupal without using this module like the CCK file field paths (you can use the SQL method for these of course but that doesn't help non-programmers.)

Also, here's the blog post that spurned me to stop running the SQL manually and create a module for the benefit of others. http://palma-seo.com/content/moving-single-drupal-install-default-direct...

Glad I was able to answer your question. I've now added a link to this ticket from the main project page for further information. Closing out the ticket.

OK, I've been working on my first project on my first vps as the default site. I figure I should use that space for my own web site (identity creation to follow project 1). So I want to move project1 to sites/all/domain1.com before I work on it any further. How do I do this? Same as moving to a different install and then recreate default dir?

I renamed the directory and browser it, but I can'y login.help!

directory renamed but can't login any more! I use IIS an rewrite url is on; It ran grace before!

Hi Dillon, are you running Drupal 6 or 7?

I used to use SQL to update the paths in my database, but its a lot of work and prone for errors. Then I figured a simple text find and replace could do the job wonderously too, but my text processor crashed on the big file. In the end I found a (linux) commandline tool called sed, which does the full SQL search and replace in a fraction of a second. The command I use is:
sed -i 's:sites/default:sites/myawesomenewsite.com:g' path/to/file.mysql

However I can imagine this module is awesome in an aegir environment where a lot of cloning happens. I'll be sure to check it out!