HOWTO Split Huge Subdirectories into Git Submodules

howto_git_submodules.sh

# First, split the huge directory into its own standalone branch.
git subtree split -P v1/fpdf/assets/img -b api_fpdf_asset_images

# Second, push the huge directory into its own repository.
pushd ..
mkdir api_fpdf_asset_images
pushd api_fpdf_asset_images
git init
git pull ../api.filtered api_fpdf_asset_images

# Third, push it to Bitbucket, or wherever.
git remote add origin ssh://url/to/repository.git
git push origin -u master

# Fourth, cleanup.
popd; popd
# In the PWD of the `api` working copy:
git rm -rf v1/fpdf/assets/img
git commit v1/fpdf/assets/img -m'Migrated to subtree.'

# Fifth, remove the historical data for the huge directory.
# BE EXCEPTIONALLY CAREFUL WITH THIS COMMAND!!
# It can also take an extended period of time. 5+ minutes.
git filter-branch --prune-empty --tree-filter 'rm -rf v1/fpdf/assets/img' HEAD

# Confirm that the huge directory is wiped from the historical log:
git log -- v1/fpdf/assets/img

# Sixth, on both dev boxes and in the repo on the bitbucket server (be sure to backup first!):
# Clear up all of the cached refs to the huge directory:
rm -r .git/refs/original/ && git reflog expire --all && git gc --aggressive --prune=now

# Finally, attach the new repo as a submodule to the api repo:
git submodule add https://path/to/api_fpdf_asset_images.git v1/fpdf/assets/img
git commit -m'Attached FPDF asset images git submodule.'
git push

# As part of the deployment plan, or if a developer needs access to the submodule:
git submodule init