Working with Subtrees

In this lab, you’ll get some experience working with subtrees.

PREREQUISITES

This lab requires that you have Internet access and have completed at least the first two steps in Connected Lab 10, where you forked the various split projects of the original calc2 project into your area in GitHub and cloned the super_calc project down to your local system.

STEPS

1. Start out in the super_calc directory for the super_calc repository that you cloned from your GitHub fork in Connected Lab 10. You’re going to add another repository as a subtree to super_calc.
2. To add the repository, use the following command:

   $ git subtree add -P sub_docs --squash https://github.com/<your github user id>/sub_docs master

   Even though you don’t have much history in this repository, you used the --squash command to compress it. Note that the -P stands for prefix, which is the name your subdirectory gets.

3. Look at the directory structure; note that the sub_docs subdirectory is there under your super_calc project. Also, if you do a git log, you can see where the subproject was added and the history squashed.

   $ ls sub_docs
   $ git log --oneline

   Note that there is only one set of history here because there is only one project effectively—even though we have added a repository as a subproject.

4. Now, you will see how to update a subproject that is included as a subtree when the remote repository is updated. First, clone the sub_docs project down into a different area.

   $ cd ..
   $ git clone https://github.com/<your github user id>/sub_docs sub_docs_temp

5. Change into the sub_docs_temp project, and create a simple file. Then stage it, commit it, and push it.

   $ cd sub_docs_temp
   $ echo "readme content" > readme.txt
   $ git add .
   $ git commit -m "Adding readme file"
   $ git push

6. Go back to the super_calc project where you have sub_docs as a subtree.

   $ cd ../super_calc

7. To simplify future updating of your subproject, add a remote reference for the subtree’s remote repository.

   $ git remote add sub_docs_remote https://github.com/<your github user id>/sub_docs

8. You want to update your subtree project from the remote. To do this, you can use the following subtree pull command. Note that it’s similar to your add command, but with a few differences:
   • You used the long version of the prefix option.
   • You are using the remote reference you set up in the previous step.
   • You don’t have to use the squash option, but you add it as a good general practice.

   $ git subtree pull --prefix sub_docs sub_docs_remote master --squash

   Because this creates a merge commit, you will get prompted to enter a commit message in an editor session. You can add your own message or just exit the editor.

9. After the command from step 8 completes, you can see the new README file that you created in your subproject sub_docs. If you look at the log, you can also see another record for the squash and merge_commit that occurred.

   $ ls sub_docs
   $ git log --oneline

10. Changes you make locally in the subproject can be promoted the same way using the subtree push command. Change into the subproject, make a simple change to your new README file, and then stage and commit it.

    $ cd sub_docs
    $ echo "update" >> readme.txt
    $ git commit -am "update readme"

11. Change back to the directory of the super_project. Then use the subtree push command below to push back to the super project’s remote repository.

    $ cd ..
    $ git subtree push --prefix sub_docs sub_docs_remote master

    Note the similarity between the form of the subtree push command and the other subtree commands you’ve used.

12. The next few steps show you how to take a subproject, put it onto a different branch, and then bring that content into a separate repository. First, use the subtree split command to take the content from the sub_docs subproject and put it into a branch named docs_branch in the super_calc area.

    $ git subtree split --prefix=sub_docs --branch=docs_branch

13. Look at the history for the new docs_branch. You can see all of the content that you have in the sub_docs project.

    $ git log --oneline docs_branch

14. Create a new project into which you can transfer the docs_branch content.

    $ cd ..
    $ mkdir docs_proj
    $ cd docs_proj
    $ git init

15. Finally, use the git pull command in a slightly different context to pull over that content into the master branch of your new project.

    $ git pull ../super_calc docs_branch:master

16. Do a git log of the master branch in the new project to see the copied content.

    $ git log --oneline master