Page history Edit this page How do I edit this website?

How to extract a subproject

Sometimes, a piece of functionality is developed as part of one project, but grows so much as to warrant becoming its own, separate project.

This tutorial describes how to split part of a Git repository into its own dedicated Git repository, preserving only the history relevant to the subproject being extracted.

Extract the revision history

  1. Use Git’s filter-branch feature to extract the Git history of only the subproject:

    git filter-branch -f --prune-empty --subdirectory-filter <subdir>

    Where <subdir> is the folder containing the subproject’s source code.

Update the Maven build

Assuming you are using Maven to build the subproject:

  1. Add an <scm> section to the pom.xml to reflect the new remote repository’s URL (see example):

    vi pom.xml
git commit -m 'Add SCM location' pom.xml

  2. Replace the old <parent> with a new one, such as pom-scijava, pom-imagej or pom-fiji (see example)—or remove the <parent> altogether.

  3. Add a <developers> section to the pom.xml to indicate the project developers (see example). You can also add <contributors> if desired and relevant.

  4. Make sure the project still builds:

    mvn clean package

  5. Add (or adjust) the .gitignore file (see example).

Push the changes

  1. Make sure that all your changes look good:

    git status
git diff

    This is good advice in general: check git status and git diff every time before you commit, to prevent making a fool out of yourself.

  2. Commit everything, mentioning the commit of the parent project from which history was rewritten (see example):

    git add . && git commit -s

  3. Create a new repository somewhere for the new project—we recommend GitHub.

  4. Connect your repository with the remote one:

    git remote set-url origin git@github.com:my-org/my-new-project

    Where git@github.com:my-org/my-new-project is the remote URL for the new project’s dedicated repository.

  5. Push the resultant history to the project’s new repository:

    git push -u origin master

Change any online resources

  1. Edit the relevant web page(s) to reflect the new Git repository location
  2. Update any other known links to the project