Externals is a project that allows you to use the workflow normally made possible by svn:externals in an SCM independent manner.

Please report bugs to either rubyforge.org/projects/ext or ext.lighthouseapp.com

I was inspired to create this project because I had several projects that had a mix of plugins managed by git and by svn. Git’s submodule feature is not exactly like svn:externals. Basically, I don’t like how you have to manually checkout a branch, and I don’t like git status not propagating through the submodules. Also, the branch tip doesn’t automatically move with git-submodule. Subversion always checks out the branch tip for subprojects when performing a checkout or update.

Externals is designed such that adding support for a new SCM, or new project types is easy.

The externals executable is called ext. Commands come in a long form and a short form. The longer form applies the action to the main project. The short forms apply the action to all sub projects.

The commands and usage are as follows (from ‘ext help’): There’s a tutorial available at nopugs.com/ext-tutorial There’s a tutorial available at nopugs.com/ext-tutorial

ext [OPTIONS] <command> [repository] [-b <branch>] [path]

-g, --git                        same as '--scm git'  Uses git to checkout/export the main project
-s, --svn, --subversion          same as '--scm svn'  Uses subversion to checkout/export the main project
-t, --type TYPE                  The type of project the main project is.  For example, 'rails'.
    --scm SCM                    The SCM used to manage the main project.  For example, '--scm svn'.
-b, --branch BRANCH              The branch you want the subproject to checkout when doing 'ext install'
-f, --force_removal              When doing an uninstall of a subproject, remove it's files and subfolders, too.
-w, --workdir DIR                The working directory to execute commands from.  Use this if for some reason you
                                 cannot execute ext from the main project's directory (or if it's just inconvenient,
                                 such as in a script or in a Capistrano task)
    --help                       does the same as 'ext help'  If you use this with a command
                                 it will ignore the command and run help instead.
    --version                    Displays the version number of externals and then exits.
                                 Same as 'ext version'

Commands that apply to the main project or the .externals file: freeze, help, init, install, touch_emptydirs, uninstall, update_ignore, upgrade_externals_file

freeze Usage: ext freeze project [REVISION]

Locks a subproject into a specific revision/branch.  If no
revision is supplied, the current revision/branch of the
project will be used.  You can specify the project by name
or path.

help You probably just ran this command just now.

init Creates a .externals file containing only [main]

It will try to determine the SCM used by the main project,
as well as the project type.  You don't have to specify
a project type if you don't want to or if your project type
isn't supported.  It just means that when using 'install'
that you'll want to specify the path.

install Usage: ext install <repository> [-b <branch>] [path]

Registers <repository> in .externals under the appropriate
SCM.  Checks out the project, and also adds it to the ignore
feature offered by the SCM of the main project.  If the SCM
type is not obvious from the repository URL, use the --scm,
--git, or --svn flags.

touch_emptydirs Recurses through all directories from the

top and adds a .emptydir file to any empty directories it
comes across.  Useful for dealing with SCMs that refuse to
track empty directories (such as git, for example)

uninstall Usage: ext uninstall [-f|–force_removal] <project>

Removes a subproject from being tracked by ext.  If you
want the files associated with this subproject deleted as well
(if, for example, you wish to reinstall it from a different
repository) then you can use the -f option to remove the files.

update_ignore Adds all paths to subprojects that are

registered in .externals to the ignore feature of the
main project.  This is automatically performed by install,
and so you probably only will run this if you are manually
maintaining .externals

upgrade_externals_fileConverts the old format that stored

as [main][svn][git] to [<path1>][<path2>]...

version Displays the version number of externals and exits.

Commands that apply to the main project and all subprojects: checkout, export, status, update

checkout Usage: ext checkout <repository>

Checks out <repository>, and checks out any subprojects
registered in <repository>'s .externals file.

export Usage: ext export <repository>

Like checkout except this command fetches as little
history as possible.

status Usage: ext status

Prints out the status of the main project, followed by
the status of each subproject.

update Usage: ext update

Brings the main project, and all subprojects, up to the
latest version.

Commands that only apply to the subprojects: co, ex, st, up

co Like checkout, but skips the main project and

only checks out subprojects.

ex Like export, but skips the main project.

st Like status, but skips the main project.

up Like update, but skips the main project.

The externals project is copyright 2008 by Miles Georgi, nopugs.com, azimux.com and is released under the MIT license.

The license is available in the same directory as this README file and is named MIT_LICENSE.txt