Close full mode


Git RepositoryEdit on Github

Use git subrepo to manage a custom Orchard Core CMS module

  • I use git subrepo to manage my Orchard Core CMS custom modules. Here are what I did:
    • Create a repository for an individual custom module.
    • Pull required custom modules to the main project.
    • Continue working on the main project.
    • Push all changes to an individual modules' repositories.
    • We can pull an update version of each module that used by other projects.
    • Let's started by following the steps below.

Create a new repository for a custom module

  • Log in to your GitHub account and create a new GitHub repository for your custom Orchard Core CMS module.
  • Create an empty project.
  • Select public project for an open source project or private if not.
  • Select Initialize with README file.
  • Select Visual Studio as git ignore template.
  • Select MIT License for an open source project.
  • Create a new develop branch from the branch drop down.
  • Change a develop branch as a default branch.

Install git-subrepo

  • Follow this document to install git-subrepo.
  • Execute git subrepo --version to verify if you have successfully installed git-subrepo.
    $ git subrepo --version

Clone a custom module to the main project

  • Assume that we have set up an Orchard Core CMS project. If not, you can follow this document to set up a new Orchard Core CMS project.
  • Your Orchard Core CMS project should look like this:
    $ tree -I "bin|obj" orchard-example
    ├── nuget.config
    └── src
    └── Orchard.Web
    ├── NLog.config
    ├── Orchard.Web.csproj
    ├── Program.cs
    ├── Properties
    │ └── launchSettings.json
    ├── Startup.cs
    ├── appsettings.json
    └── wwwroot
  • Before cloning a module project with git-subrepo, please make sure your main project is under git repository and you have committed all changes.
  • CD to the root of your Orchard Core CMS project and run the following command:
    $ git subrepo clone <your-custom-module-remote-url> <your-custom-module-path> -b <branch-name>
  • Please note the tool does not create another subdirectory with the name of the subrepo that you are using.
  • Example command to clone develop branch of Codesanook.OrganizationProfile to the main project.
    $ git subrepo clone [email protected]:codesanook/Codesanook.OrganizationProfile.git src/Modules/Codesanook.OrganizationProfile -b develop

Generate code for a custom module

  • If we clone an empty project, we need to generate some code from a template.
  • Follow this document to generate code from a custom module template.

Your current project's file structure

  • After cloning a custom module's repository and generate some code if needed, your project files' structure should look like this:
    $ tree -Ia "bin|obj|Localization" orchard-example
    └── src
    ├── Modules
    │   └── Codesanook.OrganizationProfile
    │ └── .gitrepo
    └── Orchard.Web
  • Please note that some files/folders have been omitted for simplicity.
  • git-subrepo creates .gitrepo file for storing some subrepo essential information. We don't edit this file directly but we manage our project with git-subrepo commands instead.
  • If you run git log, you will find a new commit message similar to the following content:
$ git log
Date: Tue Mar 22 16:31:26 2022 +0700
git subrepo clone [email protected]:codesanook/Codesanook.OrganizationProfile.git src/Modules/Codesanook.OrganizationProfile
subdir: "src/Modules/Codesanook.OrganizationProfile"
merged: "6e44051"
origin: "[email protected]:codesanook/Codesanook.OrganizationProfile.git"
branch: "develop"
commit: "6e44051"
version: "0.4.3"
origin: ""
commit: "2f68596"

Continue your work

  • You can now continue your work, commit and push changes to your main project repository as usual without any special commands.
  • It is good to make a separated commit for changes in your custom module.

Push changes to a custom module's repository

  • Execute the following command to push changes to a custom module's repository:
    $ git subrepo push <your-custom-module-path>
  • Example command to push changes in Codesanook.OrganizationProfile back to its repository:
    $ git subrepo push src/Modules/Codesanook.OrganizationProfile
  • You can also specify a branch name when using a push command.

Update the latest version of a custom module

  • On another project, if you want to update the latest version of a custom module, just execute the following command:
    $ git subrepo pull <your-custom-module-path>
  • Example command to pull changes in Codesanook.OrganizationProfile to another project:
    $ git subrepo pull src/Modules/Codesanook.OrganizationProfile

Turn an existing subdirectory into a subrepo.

$ git subrepo init <subdir> [-r <remote>] [-b <branch>] [--method <merge|rebase>]

Other consideration to distribute your custom module.

  • You can also make your open source custom module as Nuget package and let other projects consume your Nuget package instead of cloning it by git-subrepo.
  • This is good if a consumer that doesn't make any changes to your custom module.
  • You may learn how to publish a Nuget package from these videos.

Useful links and credit

Loading comments...