GitHub Project's Wiki Repository As Documentation Submodule Helper Script Template

doc.sh

#!/usr/bin/env bash

# |---------------------------------------------------------------------------------------------------------------------
# |
# | GitHub Project's Wiki Repository As Documentation Submodule Helper Script Template
# |
# |     - Before you start using this gist and/or make **any** changes to it, in order to understand the means,
# |       when using GitHub's repository wiki as a git submodule serving as the project's documentation in
# |       the project's /doc folder, **read thoroughly and understand the following article**:
# |
# |       https://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/
# |
# |     - NOTE: after a change and then a commit occurred in the /doc submodule, it is necessary also to make a
# |       commit in the parent repository in order the change in the /doc submodule to be saved.
# |       Check the "commit+push-project" case in this script.
# |
# |---------------------------------------------------------------------------------------------------------------------

add-wiki-repo-as-submodule() {

    # check **Setup – Clone submodule into existing repo** section on
    # https://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/

    #acquire the repository's .wiki.git URL
    wiki_path="...wiki.git"

    # make sure we are at the right path
    cd /project_root

    # remove /doc directory, if it is present
    rm -rf doc

    # add the wiki's repository as a git submodule
    git submodule add $wiki_path doc

    # it is necessary to commit and then push the modified git repository
    # after a submodule was added to the project's repository
    git commit -m "Add the project's wiki repository as a git submodule into /doc"
    git push

    # with this way, pull the submodule's content for the first time
    git submodule init
    git submodule update
}

pull-wiki-submodule-changes() {

    # check **Update the docs Submodule** section on
    # https://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/

    # make sure we are at the right path
    cd /project_root

    # pull and merge changes to the submodule in order to properly update the submodule's contents
    git pull
    git merge origin/master
    git submodule update
}

commit+push-wiki-submodule() {

    #acquire the project's name to be used in the commit message
    name="project-name"

    # check **Make changes to the docs submodule** section on
    # https://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/

    # make sure we are at the right path, in the doc's directory
    cd /project_root/doc

    git checkout master
    git commit -am "Update $name API documentation"
    git push
}

commit+push-project() {

    #acquire the project's name to be used in the commit message
    name="project-name"

    # check **Make changes to the docs submodule** section on
    # https://brendancleary.com/2013/03/08/including-a-github-wiki-in-a-repository-as-a-submodule/

    # make sure we are at the right path
    cd /project_root

    git commit -am "Update $name API documentation"
    git push
}

wiki-submodule-status() {

    # make sure we are at the right path, in the doc's directory
    cd /project_root/doc

    git status
}

case $1 in
    # run it via "doc.sh init"
    init)
        add-wiki-repo-as-submodule
        ;;

    # run it via "doc.sh pull"
    pull)
        pull-wiki-submodule-changes
        ;;

    # run it via "doc.sh commit+push"
    commit+push)
        commit+push-wiki-submodule
        ;;

    # run it via "doc.sh status"
    status)
        wiki-submodule-status
        ;;

    # run it via "doc.sh commit+push-project"
    commit+push-project)
        commit+push-wiki-submodule
        commit+push-project
        ;;

esac