modulesync 4.4.0 → 4.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b756f006e9c39eef2b7a94ec1f896866f22f88099978530b2e587565dc9826c8
-  data.tar.gz: 1d5fb83e96ee7974a09b12f91e6fea79997554fbe959d8ad6c29938d41f76ae8
+  metadata.gz: d8ccf6e8a41d6921a17a4171187f6ee1a63478ac231125c5bede16e52e9a2082
+  data.tar.gz: 5e65db0d1e4c83cdcaa4bd6537bb2080f5318551ae6ce10cbb62c1897217910d
 SHA512:
-  metadata.gz: b838e8aeaf52e6d0f2ff3dfbdc1a6c0ede1d1188862de5e6d7205632d94383782ef3aeaa2fb1150b18469a46c582ded2fad29621048657c4922453d69e4821ed
-  data.tar.gz: 19160e011a602778c435dfa18e5e7583fada6a7bfdca7ee125be0553b0b8acc795f10f986821bd3783a7dba9f5e8e1d6815565803f3411ab61b0a61c552e1d1b
+  metadata.gz: c16e333b6556c1141385a8d3e17c7a53c74b9fc74d648cdab58a655d8f055155c33ed37cb89d90ea16905b3b28ac9bb3fb98b520748ace87bd4a5dca85c33beb
+  data.tar.gz: fa3990dfd4ea5c958146832effa2292c5388b8100897a28d7548c3954c385da17fdb16cf1daf7c96aece91c951b69624106c4dcf487b36d17ab06cae67b6a775

data/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Setup ruby
-        uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
+        uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.317.0
         with:
           ruby-version: "3.4"
           bundler-cache: true
@@ -38,7 +38,7 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Install Ruby ${{ matrix.ruby }}
-        uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
+        uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.317.0
         with:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true

data/.github/workflows/release.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - name: Install Ruby
-        uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
+        uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.317.0
         with:
           ruby-version: 'ruby'
       - name: Build gem
@@ -96,7 +96,7 @@ jobs:
         with:
           name: gem-artifact
       - name: Install Ruby
-        uses: ruby/setup-ruby@d45b1a4e94b71acab930e56e79c6aa188764e7f9 # v1.316.0
+        uses: ruby/setup-ruby@6e5d382445ae5590b7449d8b3bc8cb1c2c27f617 # v1.317.0
         with:
           ruby-version: 'ruby'
       - name: Wait for release to propagate

data/CHANGELOG.md

@@ -2,9 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
-## [4.4.0](https://github.com/voxpupuli/modulesync/tree/4.4.0) (2026-07-09)
+## [4.5.0](https://github.com/voxpupuli/modulesync/tree/4.5.0) (2026-07-15)
 
-[Full Changelog](https://github.com/voxpupuli/modulesync/compare/v4.3.0...4.4.0)
+[Full Changelog](https://github.com/voxpupuli/modulesync/compare/v4.4.0...4.5.0)
+
+**Implemented enhancements:**
+
+- feat: update pr/mr title if needed [\#358](https://github.com/voxpupuli/modulesync/pull/358) ([rwaffen](https://github.com/rwaffen))
+- feat: add option to rebase modulesync branch with the latest changes from the origin’s default branch [\#356](https://github.com/voxpupuli/modulesync/pull/356) ([rwaffen](https://github.com/rwaffen))
+
+**Merged pull requests:**
+
+- Enhance README.md [\#298](https://github.com/voxpupuli/modulesync/pull/298) ([bastelfreak](https://github.com/bastelfreak))
+
+## [v4.4.0](https://github.com/voxpupuli/modulesync/tree/v4.4.0) (2026-07-09)
+
+[Full Changelog](https://github.com/voxpupuli/modulesync/compare/v4.3.0...v4.4.0)
 
 **Implemented enhancements:**
 

data/README.md

@@ -1,5 +1,4 @@
-ModuleSync
-===========
+# ModuleSync
 
 [![License](https://img.shields.io/github/license/voxpupuli/modulesync.svg)](https://github.com/voxpupuli/modulesync/blob/master/LICENSE)
 [![Test](https://github.com/voxpupuli/modulesync/actions/workflows/ci.yml/badge.svg)](https://github.com/voxpupuli/modulesync/actions/workflows/ci.yml)
@@ -9,198 +8,191 @@ ModuleSync
 [![RubyGem Downloads](https://img.shields.io/gem/dt/modulesync.svg)](https://rubygems.org/gems/modulesync)
 [![Donated by Puppet Inc](https://img.shields.io/badge/donated%20by-Puppet%20Inc-fb7047.svg)](#transfer-notice)
 
-Table of Contents
------------------
-
-1. [Usage TLDR](#usage-tldr)
-2. [Overview](#overview)
-3. [How it works](#how-it-works)
-4. [Installing](#installing)
-5. [Workflow](#workflow)
-6. [The Templates](#the-templates)
-
-Usage TLDR
-----------
-
-```
+## Table of Contents
+
+- [ModuleSync](#modulesync)
+  - [Table of Contents](#table-of-contents)
+  - [Usage TLDR](#usage-tldr)
+  - [Overview](#overview)
+  - [How It Works](#how-it-works)
+  - [Installing](#installing)
+  - [Workflow](#workflow)
+    - [Default mode](#default-mode)
+      - [Make changes](#make-changes)
+      - [Dry-run](#dry-run)
+      - [Offline support](#offline-support)
+      - [Damage mode](#damage-mode)
+      - [Automating Updates](#automating-updates)
+      - [Submitting PRs/MRs to GitHub or GitLab](#submitting-prsmrs-to-github-or-gitlab)
+    - [Using Forks and Non-master branches](#using-forks-and-non-master-branches)
+      - [Dry-run](#dry-run-1)
+      - [Damage mode](#damage-mode-1)
+      - [Configuring ModuleSync defaults](#configuring-modulesync-defaults)
+        - [Example](#example)
+          - [GitHub](#github)
+          - [GitLab](#gitlab)
+          - [Gerrit](#gerrit)
+      - [Filtering Repositories](#filtering-repositories)
+      - [Pushing to a different remote branch](#pushing-to-a-different-remote-branch)
+      - [Automating updates](#automating-updates-1)
+      - [Updating metadata.json](#updating-metadatajson)
+      - [Tagging repositories](#tagging-repositories)
+      - [Setting the tag pattern](#setting-the-tag-pattern)
+      - [Executing bundle command with a shared bundle path and gemfile](#executing-bundle-command-with-a-shared-bundle-path-and-gemfile)
+      - [Updating the CHANGELOG](#updating-the-changelog)
+      - [Working with templates](#working-with-templates)
+  - [The Templates](#the-templates)
+  - [Transfer Notice](#transfer-notice)
+  - [License](#license)
+  - [Release information](#release-information)
+
+## Usage TLDR
+
+```shell
 gem install modulesync
 msync --help
 ```
 
-Overview
---------
-
-ModuleSync was written as a simple script with ERB templates to help the
-Puppet Labs module engineers manage the zoo of Puppet modules on GitHub, and
-has now been restructured and generalized to be used within other
-organizations. Puppet modules within an organization tend to have a number of
-meta-files that are identical or very similar between modules, such as the
-`Gemfile`, `.travis.yml`, `.gitignore`, or `spec_helper.rb`. If a file needs to
-change in one module, it likely needs to change in the same way in every other
-module that the organization manages.
-
-One approach to this problem is to use sed in a bash for loop on the modules to
-make a single change across every module. This approach falls short if there is
-a single file that is purposefully different than the others, but still needs
-to be managed. Moreover, this approach does not help if two files are
-structured differently but need to be changed with the same meaning; for
-instance, if the .travis.yml of one module uses a list of environments to
-include, and another uses a matrix of includes with a list of excludes, adding
-a test environment to both modules will require entirely different approaches.
-
-ModuleSync provides the advantage of defining a standard template for each
-file to follow, so it becomes clear what a file is supposed to look like. Two
-files with the same semantics should also have the same syntax. A difference
-between two files should have clear reasons, and old cruft should not be left
-in files of one module as the files of another module march forward.
-
-Another advantage of ModuleSync is the ability to run in no-op mode, which
-makes local changes and shows the diffs, but does not make permanent changes in
-the remote repository.
-
-How It Works
-------------
-
-ModuleSync is a gem that uses the GitHub workflow to clone, update, and push module
-repositories. It expects to be activated from a directory containing
-configuration for modulesync and the modules, or you can pass it the location
-of this configuration directory. [The configuration for the Vox Pupuli
-modules](https://github.com/voxpupuli/modulesync_config), can be used as an
-example for your own configuration. The configuration directory contains a
-directory called moduleroot which mirrors the structure of a module. The files
-in the moduleroot are ERB templates, and MUST be named after the target file,
-with `.erb.` appended. The templates are
-rendered using values from a file called `config_defaults.yml` in the root (not
-moduleroot) of the configuration directory. The default values can be
-overridden or extended by adding a file called `.sync.yml` to the module itself.
-This allows us to, for example, have a set of "required" gems that are added
-to all Gemfiles, and a set of "optional" gems that a single module might add.
-
-Within the templates, values can be accessed in the `@configs` hash, which is
-merged from the values under the keys `:global` and the target file name (no
-`.erb` suffix).
-
-The list of modules to manage is in `managed_modules.yml` in the configuration
-directory. This lists just the names of the modules to be managed.
-
-ModuleSync can be called from the command line with parameters to change the
-branch you're working on or the remote to clone from and push to. You can also
-define these parameters in a file named `modulesync.yml` in the configuration
-directory.
-
-Installing
-----------
+## Overview
 
-```
+ModuleSync was written as a simple script with ERB templates to help the Puppet Labs module engineers manage the zoo of Puppet modules on GitHub, and has now been restructured and generalized to be used within other organizations.
+Puppet modules within an organization tend to have a number of meta-files that are identical or very similar between modules, such as the `Gemfile`, `.travis.yml`, `.gitignore`, or `spec_helper.rb`.
+If a file needs to change in one module, it likely needs to change in the same way in every other module that the organization manages.
+
+One approach to this problem is to use sed in a bash for loop on the modules to make a single change across every module.
+This approach falls short if there is a single file that is purposefully different than the others, but still needs to be managed.
+Moreover, this approach does not help if two files are structured differently but need to be changed with the same meaning;
+for instance, if the .travis.yml of one module uses a list of environments to include, and another uses a matrix of includes with a list of excludes, adding a test environment to both modules will require entirely different approaches.
+
+ModuleSync provides the advantage of defining a standard template for each file to follow, so it becomes clear what a file is supposed to look like.
+Two files with the same semantics should also have the same syntax.
+A difference between two files should have clear reasons, and old cruft should not be left in files of one module as the files of another module march forward.
+
+Another advantage of ModuleSync is the ability to run in no-op mode, which makes local changes and shows the diffs, but does not make permanent changes in the remote repository.
+
+## How It Works
+
+ModuleSync is a gem that uses the GitHub workflow to clone, update, and push module repositories.
+It expects to be activated from a directory containing configuration for modulesync and the modules, or you can pass it the location of this configuration directory.
+[The configuration for the Vox Pupuli modules](https://github.com/voxpupuli/modulesync_configs), can be used as an example for your own configuration.
+The configuration directory contains a directory called moduleroot which mirrors the structure of a module.
+The files in the moduleroot are ERB templates, and MUST be named after the target file, with `.erb.` appended.
+The templates are rendered using values from a file called `config_defaults.yml` in the root (not moduleroot) of the configuration directory.
+The default values can be overridden or extended by adding a file called `.sync.yml` to the module itself.
+This allows us to, for example, have a set of "required" gems that are added to all Gemfiles, and a set of "optional" gems that a single module might add.
+
+Within the templates, values can be accessed in the `@configs` hash, which is merged from the values under the keys `:global` and the target file name (no `.erb` suffix).
+
+The list of modules to manage is in `managed_modules.yml` in the configuration directory.
+This lists just the names of the modules to be managed.
+
+ModuleSync can be called from the command line with parameters to change the branch you're working on or the remote to clone from and push to.
+You can also define these parameters in a file named `modulesync.yml` in the configuration directory.
+
+## Installing
+
+```shell
 gem install modulesync
 ```
 
 For developers:
 
-```
+```shell
 gem build modulesync.gemspec
 gem install modulesync-*.gem
 ```
 
-Workflow
---------
+## Workflow
 
 ### Default mode
 
-With no additional arguments, ModuleSync clones modules from the puppetlabs
-github organization and pushes to the master branch.
+With no additional arguments, ModuleSync clones modules from the puppetlabs github organization and pushes to the master branch.
 
 #### Make changes
 
-Make changes to a file in the moduleroot. For sanity's sake you should commit
-and push these changes, but in this mode the update will be rendered from the
-state of the files locally.
+Make changes to a file in the moduleroot.
+For sanity's sake you should commit and push these changes, but in this mode the update will be rendered from the state of the files locally.
 
 #### Dry-run
 
-Do a dry-run to see what files will be changed, added and removed. This clones
-the modules to `modules/<namespace>-<modulename>` in the current working
-directory, or if the modules are already cloned, does an effective `git fetch
-origin; git checkout master; git reset --hard origin/master` on the modules.
-Don't run modulesync if the current working directory contains a modules/
-directory with changes you want to keep. The dry-run makes local changes there,
-but does not commit or push changes. It is still destructive in that it
-overwrites local changes.
+Do a dry-run to see what files will be changed, added and removed.
+This clones the modules to `modules/<namespace>-<modulename>` in the current working directory, or if the modules are already cloned, does an effective
 
+```shell
+git fetch origin
+git checkout master
+git reset --hard origin/master
 ```
+
+on the modules.
+Don't run modulesync if the current working directory contains a `modules/` directory with changes you want to keep.
+The dry-run makes local changes there, but does not commit or push changes.
+It is still destructive in that it overwrites local changes.
+
+```shell
 msync update --noop
 ```
 
 #### Offline support
 
-The --offline flag was added to allow a user to disable git support within
-msync. One reason for this is because the user wants to control git commands
-external to msync.  Note, when using this command, msync assumes you have
-create the folder structure and git repositories correctly. If not, msync will
-fail to update correctly.
+The --offline flag was added to allow a user to disable git support within msync.
+One reason for this is because the user wants to control git commands external to msync.
+Note, when using this command, msync assumes you have create the folder structure and git repositories correctly.
+If not, msync will fail to update correctly.
 
-```
+```shell
 msync update --offline
 ```
 
 #### Damage mode
 
-Make changes for real and push them back to master. This operates on the
-pre-cloned modules from the dry-run or clones them fresh if the modules aren't
-found.
+Make changes for real and push them back to master.
+This operates on the pre-cloned modules from the dry-run or clones them fresh if the modules aren't found.
 
-```
+```shell
 msync update -m "Commit message"
 ```
 
 Amend the commit if changes are needed.
 
-```
+```shell
 msync update --amend
 ```
 
-For most workflows you will need to force-push an amended commit. Not required
-for gerrit.
+For most workflows you will need to force-push an amended commit.
+Not required for gerrit.
 
-```
+```shell
 msync update --amend --force
 ```
 
 #### Automating Updates
 
-You can install a pre-push git hook to automatically clone, update, and push
-modules upon pushing changes to the configuration directory. This does not
-include a noop mode.
+You can install a pre-push git hook to automatically clone, update, and push modules upon pushing changes to the configuration directory.
+This does not include a noop mode.
 
-```
+```shell
 msync hook activate
 ```
 
-If you have activated the hook but want to make changes to the configuration
-directory (such as changes to `managed_modules.yml` or `modulesync.yml`) without
-touching the modules, you can deactivate the hook.
+If you have activated the hook but want to make changes to the configuration directory (such as changes to `managed_modules.yml` or `modulesync.yml`) without touching the modules, you can deactivate the hook.
 
-```
+```shell
 msync hook deactivate
 ```
 
 #### Submitting PRs/MRs to GitHub or GitLab
 
-You can have modulesync submit Pull Requests on GitHub or Merge Requests on
-GitLab automatically with the `--pr` CLI option.
+You can have modulesync submit Pull Requests on GitHub or Merge Requests on GitLab automatically with the `--pr` CLI option.
 
-```
+```shell
 msync update --pr
 ```
 
-In order for GitHub PRs or GitLab MRs to work, you must either provide
-the `GITHUB_TOKEN` or `GITLAB_TOKEN` environment variables,
-or set them per repository in `managed_modules.yml`, using the `github` or
-`gitlab` keys respectively.
+In order for GitHub PRs or GitLab MRs to work, you must either provide the `GITHUB_TOKEN` or `GITLAB_TOKEN` environment variables.
+You can also set them per repository in `managed_modules.yml`, using the `github` or `gitlab` keys respectively.
 
-For GitHub Enterprise and self-hosted GitLab instances you also need to set the
-`GITHUB_BASE_URL` or `GITLAB_BASE_URL` environment variables, or specify the
-`base_url` parameter per repository in `managed_modules.yml`:
+For GitHub Enterprise and self-hosted GitLab instances you also need to set the `GITHUB_BASE_URL` or `GITLAB_BASE_URL` environment variables, or specify the `base_url` parameter in `modulesync.yml`:
 
 ```yaml
 ---
@@ -217,13 +209,9 @@ repo2:
 
 Then:
 
-* Set the PR/MR title with `--pr-title` or in `modulesync.yml` with the
-  `pr_title` attribute.
-* Assign labels to the PR/MR with `--pr-labels` or in `modulesync.yml` with
-  the `pr_labels` attribute. **NOTE:** `pr_labels` should be a list. When
-  using the `--pr-labels` CLI option, you should use a comma separated list.
-* Set the target branch with `--pr-target-branch` or in `modulesync.yml` with
-  the `pr_target_branch` attribute.
+* Set the PR/MR title with `--pr-title` or in `modulesync.yml` with the `pr_title` attribute.
+* Assign labels to the PR/MR with `--pr-labels` or in `modulesync.yml` with the `pr_labels` attribute. **NOTE:** `pr_labels` should be a list. When using the `--pr-labels` CLI option, you should use a comma separated list.
+* Set the target branch with `--pr-target-branch` or in `modulesync.yml` with the `pr_target_branch` attribute.
 
 More details for GitHub:
 
@@ -231,42 +219,35 @@ More details for GitHub:
 
 ### Using Forks and Non-master branches
 
-The default functionality is to run ModuleSync on the puppetlabs modules, but
-you can use this on your own organization's modules. This functionality also
-applies if you want to work on a fork of the puppetlabs modules or work on a
-non-master branch of any organization's modules. ModuleSync does not support
-cloning from one remote and pushing to another, you are expected to fork
-manually. It does not support automating pull requests.
+The default functionality is to run ModuleSync on the Vox Pupuli modules, but you can use this on your own organization's modules.
+This functionality also applies if you want to work on a fork of the Vox Pupuli modules or work on a non-master branch of any organization's modules.
+ModuleSync does not support cloning from one remote and pushing to another, you are expected to fork manually.
+It does not support automating pull requests.
 
 #### Dry-run
 
-If you dry-run before doing the live update, you need to specify what namespace
-to clone from because the live update will not re-clone if the modules are
-already cloned. The namespace should be your fork, not the upstream module (if
-working on a fork).
+If you dry-run before doing the live update, you need to specify what namespace to clone from because the live update will not re-clone if the modules are already cloned.
+The namespace should be your fork, not the upstream module (if working on a fork).
 
-```
-msync update -n puppetlabs --noop
+```shell
+msync update -n voxpupuli --noop
 ```
 
 #### Damage mode
 
-You don't technically need to specify the namespace if the modules are already
-cloned from the dry-run, but it doesn't hurt. You do need to specify the
-namespace if the modules are not pre-cloned. You need to specify a branch to
-push to if you are not pushing to master.
+You don't technically need to specify the namespace if the modules are already cloned from the dry-run, but it doesn't hurt.
+You do need to specify the namespace if the modules are not pre-cloned.
+You need to specify a branch to push to if you are not pushing to master.
 
-```
-msync update -n puppetlabs -b sync_branch -m "Commit message"
+```shell
+msync update -n voxpupuli -b sync_branch -m "Commit message"
 ```
 
 #### Configuring ModuleSync defaults
 
-If you're not using the puppetlabs modules or only ever pushing to a fork of
-them, then specifying the namespace and branch every time you use ModuleSync
-probably seems excessive. You can create a file called modulesync.yml in the
-configuration directory that provides these arguments automatically. This file
-has a form such as:
+If you're not using Vox Pupuli modules or only ever pushing to a fork of them, then specifying the namespace and branch every time you use ModuleSync probably seems excessive.
+You can create a file called modulesync.yml in the configuration directory that provides these arguments automatically.
+This file has a form such as:
 
 ```yaml
 ---
@@ -276,17 +257,20 @@ branch: modulesyncbranch
 
 Then you can run ModuleSync without extra arguments:
 
-```
+```shell
 msync update --noop
 msync update -m "Commit message"
 ```
 
+Use `--rebase` to update the local working branch with the latest remote default
+branch before ModuleSync changes any files. If the rebase conflicts, ModuleSync
+aborts the rebase and reports an error for that module. A branch changed by the
+rebase is pushed even when the template sync itself produces no changes.
+
 Available parameters for modulesync.yml
 
 * `git_base` : The default URL to git clone from (Default: 'git@github.com:')
-* `namespace` : Namespace of the projects to manage (Default: 'puppetlabs').
-  This value can be overridden in the module name (e.g. 'namespace/mod') or by
-  using the `namespace` key for the module in `managed_modules.yml`.
+* `namespace` : Namespace of the projects to manage (Default: 'puppetlabs'). This value can be overridden in the module name (e.g. 'namespace/mod') or by using the `namespace` key for the module in `managed_modules.yml`.
 * `branch` : Branch to push to (Default: 'master')
 * `remote_branch` : Remote branch to push to (Default: Same value as branch)
 * `message` : Commit message to apply to updated modules.
@@ -333,14 +317,14 @@ pre_commit_script: openstack-commit-msg-hook.sh
 
 If you only want to sync some of the repositories in your managed_modules.yml, use the `-f` flag to filter by a regex:
 
-```
+```shell
 msync update -f augeas -m "Commit message"    # acts only on the augeas module
 msync update -f puppet-a..o "Commit message"
 ```
 
 If you want to skip syncing some of the repositories in your managed_modules.yml, use the `-x` flag to filter by a regex:
 
-```
+```shell
 msync update -x augeas -m "Commit message"    # acts on all modules except the augeas module
 msync update -x puppet-a..o "Commit message"
 ```
@@ -351,45 +335,41 @@ If no `-f` is specified, all repository are processed, if no `-x` is specified n
 
 If you want to push the modified branch to a different remote branch, you can use the -r flag:
 
-```
+```shell
 msync update -r master_new -m "Commit message"
 ```
 
 #### Automating updates
 
-If you install a git hook, you need to tell it what remote and branch to push
-to. This may not work properly if you already have the modules cloned from a
-different remote. The hook will also look in modulesync.yml for default
-arguments.
+If you install a git hook, you need to tell it what remote and branch to push to.
+This may not work properly if you already have the modules cloned from a different remote.
+The hook will also look in modulesync.yml for default arguments.
 
-```
-msync hook activate -n puppetlabs -b sync_branch
+```shell
+msync hook activate -n voxpupuli -b sync_branch
 ```
 
 #### Updating metadata.json
 
-Modulesync can optionally bump the minor version in `metadata.json` for each
-modified modules if you add the `--bump` flag to the command line:
+Modulesync can optionally bump the minor version in `metadata.json` for each modified modules if you add the `--bump` flag to the command line:
 
-```
+```shell
 msync update -m "Commit message" --bump
 ```
 
 #### Tagging repositories
 
-If you wish to tag the modified repositories with the newly bumped version,
-you can do so by using the `--tag` flag:
+If you wish to tag the modified repositories with the newly bumped version, you can do so by using the `--tag` flag:
 
-```
+```shell
 msync update -m "Commit message" --bump --tag
 ```
 
 #### Setting the tag pattern
 
-You can also set the format of the tag to be used (`printf`-formatted)
-by setting the `tag_pattern` option:
+You can also set the format of the tag to be used (`printf`-formatted) by setting the `tag_pattern` option:
 
-```
+```shell
 msync update -m "Commit message" --bump --tag --tag_pattern 'v%s'
 ```
 
@@ -399,30 +379,28 @@ The default for the tag pattern is `%s`.
 
 By default `msync execute` will remove bundler related env vars (^BUNDLE|^SOURCE_DATE_EPOCH$|^GEM_|RUBY), you can use `--env` flag to keep specified env vars:
 
-```
+```shell
 msync execute --env BUNDLE_PATH,BUNDLE_GEMFILE bundle exec rake lint
 ```
 
 #### Updating the CHANGELOG
 
-When bumping the version in `metadata.json`, modulesync can let you
-updating `CHANGELOG.md` in each modified repository.
+When bumping the version in `metadata.json`, modulesync can let you updating `CHANGELOG.md` in each modified repository.
 
 This is one by using the `--changelog` flag:
 
-```
+```shell
 msync update -m "Commit message" --bump --changelog
 ```
 
-This flag will cause the `CHANGELOG.md` file to be updated with the
-current date, bumped (minor) version, and commit message.
+This flag will cause the `CHANGELOG.md` file to be updated with the current date, bumped (minor) version, and commit message.
 
 If `CHANGELOG.md` is absent in the repository, nothing will happen.
 
-
 #### Working with templates
 
-As mentioned, files in the moduleroot directory must be ERB templates (they must have an .erb extension, or they will be ignored). These files have direct access to @configs hash, which gets values from config_defaults.yml file and from the module being processed:
+As mentioned, files in the moduleroot directory must be ERB templates (they must have an .erb extension, or they will be ignored).
+These files have direct access to @configs hash, which gets values from config_defaults.yml file and from the module being processed:
 
 ```erb
 <%= @configs[:git_base] %>
@@ -430,8 +408,8 @@ As mentioned, files in the moduleroot directory must be ERB templates (they must
 <%= @configs[:puppet_module] %>
 ```
 
-Alternatively some meta data is passed to the template. This will allow you to add custom Ruby extensions inside the
-template, reading other files from the module, to make the template system more adaptive.
+Alternatively some meta data is passed to the template.
+This will allow you to add custom Ruby extensions inside the template, reading other files from the module, to make the template system more adaptive.
 
 ```erb
 module: <%= @metadata[:module_name] %>
@@ -441,16 +419,15 @@ workdir: <%= @metadata[:workdir] %>
 
 Will result in something like:
 
-```
+```yaml
 module: puppet-test
 target: modules/github-org/puppet-test/test
 workdir: modules/github-org/puppet-test
 ```
 
-The Templates
--------------
+## The Templates
 
-See [Vox Pupuli's modulesync\_config](https://github.com/voxpupuli/modulesync_config) and [Puppet's modulesync\_configs (Archived)](https://github.com/puppetlabs/modulesync_configs) repositories for different templates currently in use.
+See [Vox Pupuli's modulesync\_config](https://github.com/voxpupuli/modulesync_config) repository for templates currently in use.
 
 ## Transfer Notice
 
@@ -467,6 +444,7 @@ This gem is licensed under the Apache-2 license.
 ## Release information
 
 To make a new release, please do:
+
 * update the version in `lib/modulesync/version.rb`
 * Install gems with `bundle install --with release --path .vendor`
 * generate the changelog with `bundle exec rake changelog`

data/lib/modulesync/cli.rb

@@ -114,6 +114,10 @@ module ModuleSync
              type: :boolean,
              desc: 'Do not run any Git commands. Allows the user to manage Git outside of ModuleSync.',
              default: false
+      option :rebase,
+             type: :boolean,
+             desc: 'Rebase the local branch onto the latest remote default branch before syncing.',
+             default: false
       option :bump,
              type: :boolean,
              desc: 'Bump module version to the next minor',

data/lib/modulesync/git_service/github.rb

@@ -41,8 +41,17 @@ module ModuleSync
                                            base: target_branch,
                                            head: head)
         unless pull_requests.empty?
-          # Skip creating the PR if it exists already.
-          $stdout.puts "Skipped! #{pull_requests.length} PRs found for branch '#{source_branch}'"
+          # assumption: there should only be one PR for a given source and target branch, so we just take the first one
+          pr = pull_requests.first
+
+          if pr['title'] == title
+            $stdout.puts "Skipped! #{pull_requests.length} PRs found for branch '#{source_branch}'"
+            $stdout.puts "Skipped! Existing PR ##{pr['number']} already has title '#{title}'"
+          else
+            @api.update_pull_request(repo_path, pr['number'], title: title)
+            $stdout.puts "Updated title of existing PR ##{pr['number']} to '#{title}'"
+          end
+
           return
         end
 

data/lib/modulesync/git_service/gitlab.rb

@@ -40,8 +40,17 @@ module ModuleSync
                                              source_branch: source_branch,
                                              target_branch: target_branch)
         unless merge_requests.empty?
-          # Skip creating the MR if it exists already.
-          $stdout.puts "Skipped! #{merge_requests.length} MRs found for branch '#{source_branch}'"
+          # assumption: there should only be one MR for a given source and target branch, so we just take the first one
+          mr = merge_requests.first
+
+          if mr['title'] == title
+            $stdout.puts "Skipped! #{merge_requests.length} MRs found for branch '#{source_branch}'"
+            $stdout.puts "Skipped! Existing MR !#{mr['iid']} already has title '#{title}'"
+          else
+            @api.update_merge_request(repo_path, mr['iid'], title: title)
+            $stdout.puts "Updated title of existing MR !#{mr['iid']} to '#{title}'"
+          end
+
           return
         end
 

data/lib/modulesync/repository.rb

@@ -42,6 +42,12 @@ module ModuleSync
       commits.any?
     end
 
+    def branch_behind?(branch, target_branch)
+      log = repo.log(1).between(branch, "origin/#{target_branch}")
+      commits = log.respond_to?(:execute) ? log.execute : log
+      commits.any?
+    end
+
     def default_branch
       # `Git.default_branch` requires ruby-git >= 1.17.0
       return Git.default_branch(repo.dir) if Git.respond_to? :default_branch
@@ -52,6 +58,12 @@ module ModuleSync
       %r{remotes/origin/HEAD\s+->\s+origin/(?<branch>.+?)$}.match(symbolic_ref.full)[:branch]
     end
 
+    def remote_default_branch
+      return Git.default_branch(@remote) if Git.respond_to? :default_branch
+
+      default_branch
+    end
+
     def switch(branch:)
       unless branch
         branch = default_branch
@@ -87,13 +99,16 @@ module ModuleSync
       @git = Git.clone(@remote, @directory)
     end
 
-    def prepare_workspace(branch:, operate_offline:)
+    def prepare_workspace(branch:, operate_offline:, rebase: false)
+      @rebased = false
       if cloned?
         puts "Overriding any local changes to repository in '#{@directory}'"
         git.fetch 'origin', prune: true unless operate_offline
         git.reset_hard
+        rebase_target = remote_default_branch if rebase && !operate_offline
         switch(branch: branch)
         git.pull('origin', branch) if !operate_offline && remote_branch_exists?(branch)
+        rebase_onto(rebase_target) if rebase_target
       else
         raise ModuleSync::Error, 'Unable to clone in offline mode.' if operate_offline
 
@@ -102,6 +117,31 @@ module ModuleSync
       end
     end
 
+    def rebase_onto(branch)
+      return false if repo.current_branch == branch || !branch_behind?(repo.current_branch, branch)
+
+      puts "Rebasing #{repo.current_branch} onto origin/#{branch}"
+      repo.lib.send(:command, 'rebase', "origin/#{branch}")
+      @rebased = true
+    rescue Git::Error => e
+      begin
+        repo.lib.send(:command, 'rebase', '--abort')
+      rescue Git::Error
+        # Preserve the original rebase error if Git had no rebase to abort.
+      end
+      raise ModuleSync::Error, "Rebase onto origin/#{branch} failed and was aborted: #{e.message}"
+    end
+
+    def push_changes(branch, remote_branch, options)
+      refspec = remote_branch ? "#{branch}:#{remote_branch}" : branch
+      if @rebased && !options[:force]
+        repo.lib.send(:command, 'push', '--force-with-lease', 'origin', refspec)
+      else
+        opts_push = options[:force] ? { force: true } : {}
+        repo.push('origin', refspec, opts_push)
+      end
+    end
+
     def default_reset_branch(branch)
       remote_branch_exists?(branch) ? branch : default_branch
     end
@@ -151,26 +191,24 @@ module ModuleSync
       end
       begin
         opts_commit = {}
-        opts_push = {}
         opts_commit = { amend: true } if options[:amend]
-        opts_push = { force: true } if options[:force]
         if options[:pre_commit_script]
           script = "#{File.dirname(__FILE__, 3)}/contrib/#{options[:pre_commit_script]}"
           system(script, @directory)
         end
         if repo.status.changed.empty? && repo.status.added.empty? && repo.status.deleted.empty?
           puts "There were no changes in '#{@directory}'. Not committing."
-          return false
+          return false unless @rebased
         else
           repo.commit(message, opts_commit)
         end
         if options[:remote_branch]
-          if remote_branch_differ?(branch, options[:remote_branch])
-            repo.push('origin', "#{branch}:#{options[:remote_branch]}", opts_push)
+          if @rebased || remote_branch_differ?(branch, options[:remote_branch])
+            push_changes(branch, options[:remote_branch], options)
             puts "Changes have been pushed to: '#{branch}:#{options[:remote_branch]}'"
           end
         else
-          repo.push('origin', branch, opts_push)
+          push_changes(branch, nil, options)
           puts "Changes have been pushed to: '#{branch}'"
         end
       rescue Git::Error => e

data/lib/modulesync/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ModuleSync
-  VERSION = '4.4.0'
+  VERSION = '4.5.0'
 end

data/lib/modulesync.rb

@@ -123,7 +123,8 @@ module ModuleSync
     # but we totally skip the workspace preparation to keep the current behavior
     unless options[:offline]
       puppet_module.repository.prepare_workspace(branch: options[:branch],
-                                                 operate_offline: false)
+                                                 operate_offline: false,
+                                                 rebase: options[:rebase])
     end
 
     module_configs = Util.parse_config puppet_module.path(MODULE_CONF_FILE)

data/spec/unit/module_sync/git_service/github_spec.rb

@@ -54,7 +54,7 @@ describe ModuleSync::GitService::GitHub do
       expect { @it.open_pull_request(**args) }.to output(/Submitted PR/).to_stdout
     end
 
-    it 'skips submitting PR if one has already been issued' do
+    it 'updates the title if an existing PR has a different title' do
       pr = {
         'title' => 'Test title',
         'html_url' => 'https://example.com/pulls/44',
@@ -66,7 +66,28 @@ describe ModuleSync::GitService::GitHub do
               state: 'open',
               base: 'master',
               head: "#{args[:namespace]}:#{args[:source_branch]}").and_return([pr])
-      expect { @it.open_pull_request(**args) }.to output("Skipped! 1 PRs found for branch 'test'\n").to_stdout
+      expect(@client).to receive(:update_pull_request)
+        .with(args[:repo_path], pr['number'], title: args[:title])
+      expect { @it.open_pull_request(**args) }
+        .to output("Updated title of existing PR #44 to 'Test PR is submitted'\n").to_stdout
+    end
+
+    it 'skips updating an existing PR if its title is unchanged' do
+      pr = {
+        'title' => args[:title],
+        'html_url' => 'https://example.com/pulls/44',
+        'number' => '44',
+      }
+
+      expect(@client).to receive(:pull_requests)
+        .with(args[:repo_path],
+              state: 'open',
+              base: 'master',
+              head: "#{args[:namespace]}:#{args[:source_branch]}").and_return([pr])
+      expect(@client).not_to receive(:update_pull_request)
+      expect { @it.open_pull_request(**args) }
+        .to output("Skipped! 1 PRs found for branch 'test'\n" \
+                   "Skipped! Existing PR #44 already has title 'Test PR is submitted'\n").to_stdout
     end
 
     context 'when labels are set' do

data/spec/unit/module_sync/git_service/gitlab_spec.rb

@@ -44,7 +44,7 @@ describe ModuleSync::GitService::GitLab do
       expect { @it.open_pull_request(**args) }.to output(/Submitted MR/).to_stdout
     end
 
-    it 'skips submitting MR if one has already been issued' do
+    it 'updates the title if an existing MR has a different title' do
       mr = {
         'title' => 'Test title',
         'html_url' => 'https://example.com/pulls/44',
@@ -56,8 +56,28 @@ describe ModuleSync::GitService::GitLab do
               state: 'opened',
               source_branch: args[:source_branch],
               target_branch: 'master').and_return([mr])
+      expect(@client).to receive(:update_merge_request)
+        .with(args[:repo_path], mr['iid'], title: args[:title])
+      expect { @it.open_pull_request(**args) }
+        .to output("Updated title of existing MR !44 to 'Test MR is submitted'\n").to_stdout
+    end
+
+    it 'skips updating an existing MR if its title is unchanged' do
+      mr = {
+        'title' => args[:title],
+        'html_url' => 'https://example.com/pulls/44',
+        'iid' => '44',
+      }
 
-      expect { @it.open_pull_request(**args) }.to output("Skipped! 1 MRs found for branch 'test'\n").to_stdout
+      expect(@client).to receive(:merge_requests)
+        .with(args[:repo_path],
+              state: 'opened',
+              source_branch: args[:source_branch],
+              target_branch: 'master').and_return([mr])
+      expect(@client).not_to receive(:update_merge_request)
+      expect { @it.open_pull_request(**args) }
+        .to output("Skipped! 1 MRs found for branch 'test'\n" \
+                   "Skipped! Existing MR !44 already has title 'Test MR is submitted'\n").to_stdout
     end
 
     context 'when labels are set' do

data/spec/unit/module_sync/repository_spec.rb

@@ -15,10 +15,12 @@ describe ModuleSync::Repository do
   end
   let(:branches) { instance_double(Git::Branches, remote: remote_branches) }
   let(:log) { instance_double(Git::Log) }
-  let(:git) { instance_double(Git::Base, branches: branches, log: log) }
+  let(:git_lib) { instance_double(Git::Lib) }
+  let(:git) { instance_double(Git::Base, branches: branches, lib: git_lib, log: log) }
 
   before do
     repository.instance_variable_set(:@git, git)
+    ModuleSync.instance_variable_set(:@options, verbose: false)
   end
 
   it 'detects commits on a remote source branch that are missing from the target branch' do
@@ -33,4 +35,85 @@ describe ModuleSync::Repository do
 
     expect(repository.remote_branch_ahead?('modulesync', 'main')).to be false
   end
+
+  describe '#rebase_onto' do
+    before do
+      allow(git).to receive(:current_branch).and_return('modulesync')
+      allow(log).to receive(:between).with('modulesync', 'origin/main').and_return(log)
+      allow(log).to receive(:execute).and_return([instance_double(Git::Object::Commit)])
+    end
+
+    it 'rebases the current branch onto the remote default branch' do
+      expect(git_lib).to receive(:send).with(:command, 'rebase', 'origin/main')
+
+      repository.rebase_onto('main')
+    end
+
+    it 'does not rebase the default branch onto itself' do
+      allow(git).to receive(:current_branch).and_return('main')
+      expect(git_lib).not_to receive(:send)
+
+      repository.rebase_onto('main')
+    end
+
+    it 'does not rebase a branch that already contains the remote default branch' do
+      allow(log).to receive(:execute).and_return([])
+      expect(git_lib).not_to receive(:send)
+
+      repository.rebase_onto('main')
+    end
+
+    it 'aborts and reports a failed rebase' do
+      allow(git_lib).to receive(:send).with(:command, 'rebase', 'origin/main').and_raise(Git::Error, 'merge conflict')
+      expect(git_lib).to receive(:send).with(:command, 'rebase', '--abort')
+
+      expect { repository.rebase_onto('main') }
+        .to raise_error(ModuleSync::Error, %r{Rebase onto origin/main failed and was aborted: merge conflict})
+    end
+  end
+
+  describe '#prepare_workspace' do
+    it 'fetches and rebases the selected branch onto the remote default branch when requested' do
+      allow(Dir).to receive(:exist?).with('/tmp/example/.git').and_return(true)
+      allow(Git).to receive(:default_branch).with('https://github.com/example/repository.git').and_return('main')
+      allow(git).to receive(:current_branch).and_return('modulesync')
+      allow(log).to receive(:between).with('modulesync', 'origin/main').and_return(log)
+      allow(log).to receive(:execute).and_return([instance_double(Git::Object::Commit)])
+      expect(git).to receive(:fetch).with('origin', prune: true).ordered
+      expect(git).to receive(:reset_hard).ordered
+      expect(git).to receive(:pull).with('origin', 'modulesync').ordered
+      expect(git_lib).to receive(:send).with(:command, 'rebase', 'origin/main').ordered
+
+      repository.prepare_workspace(branch: 'modulesync', operate_offline: false, rebase: true)
+    end
+  end
+
+  describe '#submit_changes' do
+    it 'does not push an unchanged branch that was not rebased' do
+      status = instance_double(Git::Status, added: {}, changed: {}, deleted: {})
+      branch = instance_double(Git::Branch, checkout: true)
+      allow(git).to receive(:branch).with('modulesync').and_return(branch)
+      allow(git).to receive(:status).and_return(status)
+      expect(git).not_to receive(:push)
+      expect(git_lib).not_to receive(:send)
+
+      result = repository.submit_changes([], branch: 'modulesync', message: 'Update', force: false)
+
+      expect(result).to be false
+    end
+
+    it 'pushes a rebased branch even when ModuleSync made no file changes' do
+      status = instance_double(Git::Status, added: {}, changed: {}, deleted: {})
+      branch = instance_double(Git::Branch, checkout: true)
+      repository.instance_variable_set(:@rebased, true)
+      allow(git).to receive(:branch).with('modulesync').and_return(branch)
+      allow(git).to receive(:status).and_return(status)
+      expect(git_lib).to receive(:send)
+        .with(:command, 'push', '--force-with-lease', 'origin', 'modulesync')
+
+      result = repository.submit_changes([], branch: 'modulesync', message: 'Update', force: false)
+
+      expect(result).to be true
+    end
+  end
 end

data/spec/unit/module_sync_spec.rb

@@ -63,5 +63,12 @@ describe ModuleSync do
 
       described_class.manage_module(puppet_module, [], {})
     end
+
+    it 'requests a rebase before syncing when enabled' do
+      described_class.instance_variable_set(:@options, described_class.config_defaults.merge(rebase: true))
+      expect(repository).to receive(:prepare_workspace).with(branch: nil, operate_offline: false, rebase: true)
+
+      described_class.manage_module(puppet_module, [], {})
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: modulesync
 version: !ruby/object:Gem::Version
-  version: 4.4.0
+  version: 4.5.0
 platform: ruby
 authors:
 - Vox Pupuli
@@ -266,7 +266,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Puppet Module Synchronizer
 test_files: []