feat!: remove --since filter in favour of --diff

docs/commands/bootstrap.mdx

@@ -49,7 +49,7 @@ Bootstrap supports [all package filtering options](/filters), therefore if you w
 ```bash
 # Only bootstrap packages that have
 # changed since the main branch.
-melos bootstrap --since="main"
+melos bootstrap --diff="main"
 ```
 
 ## Adding a postbootstrap lifecycle script

docs/filters.mdx

@@ -1,6 +1,6 @@
 ---
 title: Filtering Packages
-description: "Learn more about all the package filtering flags in Melos."
+description: 'Learn more about all the package filtering flags in Melos.'
 ---
 
 # Filtering Packages
@@ -23,11 +23,13 @@ Filter packages where the current local package version exists on pub.dev.
 melos bootstrap --published
 ```
 
-Use `--no-published` to filter packages that have not had their current version published yet.
+Use `--no-published` to filter packages that have not had their current version
+published yet.
 
 ## --scope
 
-Include only packages with names matching the given glob. This option can be repeated.
+Include only packages with names matching the given glob. This option can be
+repeated.
 
 ```bash
 # Run `flutter build ios` on all packages with "example" in the package name
@@ -36,31 +38,29 @@ melos exec --scope="*example*" -- flutter build ios
 
 ## --ignore
 
-Exclude packages with names matching the given glob. This option can be repeated.
+Exclude packages with names matching the given glob. This option can be
+repeated.
 
 ```bash
 # Run `flutter build ios` on all packages but ignore those whose packages names contain "internal"
 melos exec --ignore="*internal*" -- flutter build ios
 ```
 
-## --since
-
-Only include packages that have been changed since the specified `ref`, e.g. a commit sha or git tag.
-
-```bash
-# Run `flutter build ios` on all packages that have been changed since the specified commit hash
-melos exec --since=<commit hash> -- flutter build ios
-```
-
 ## --diff
 
-Only include packages that are different between the current working tree and the specified `ref`, e.g. a commit sha or git tag, or between two different refs.
+Filter packages based on whether there were changes between a commit and the
+current HEAD or within a range of commits.
+
+A range of commits can be specified using the git short hand syntax
+`<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`.
 
 ```bash
-# Run `flutter build ios` on all packages that are different between current branch and the specified commit hash
+# Run `flutter build ios` on all packages that are different between current
+# branch and the specified commit hash.
 melos exec --diff=<commit hash> -- flutter build ios
 
-# Run `flutter build ios` on all packages that are different between remote `main` branch and HEAD
+# Run `flutter build ios` on all packages that are different between remote
+# `main` branch and HEAD.
 melos exec --diff=origin/main...HEAD -- flutter build ios
 ```
 
@@ -100,4 +100,5 @@ Include only packages that depend on specific dependencies.
 melos exec --depends-on="flutter" --depends-on="firebase_core" -- flutter test
 ```
 
-Use `--no-depends-on` to filter packages that do not depend on the given dependencies.
+Use `--no-depends-on` to filter packages that do not depend on the given
+dependencies.

docs/guides/automated-releases.mdx

@@ -40,8 +40,8 @@ To determine which packages to version and how, Melos performs the following
 steps:
 
 1. Apply [filters](/filters) to the list of workspace packages.
-2. Load the commit history for each package. If the `--since` option is
-   specified, Melos will only load commits since the specified commit. Otherwise
+2. Load the commit history for each package. If the `--diff` option is
+   specified, Melos will only load the specified commit. Otherwise
    it will load all commits since the last version tag (e.g. `foo-v1.0.0`).
 3. Parse commit messages as Conventional Commits. If a commit message does not
    follow the Conventional Commits specification, it will be ignored.

docs/guides/migrations.mdx

@@ -29,3 +29,10 @@ these files, add the following to your `.gitignore` file:
 ```
 pubspec_overrides.yaml
 ```
+
+### `--since` was removed in favour of `--diff`
+
+The `--since` flag was removed in favour of `--diff`, which is more flexible and
+can be used to specify a range of commits in addition to a single commit.
+
+To migrate from `--since` to `--diff` simply replace `--since` with `--diff`.

packages/melos/README.md

@@ -79,7 +79,7 @@ configuration file if the default is unsuitable.
     - Include only packages with names matching the given glob.
   - `--ignore=<glob>`
     - Exclude packages with names matching the given glob.
-  - `--since=<ref>`
+  - `--diff=<ref>`
     - Only include packages that have been changed since the specified `ref`,
       e.g. a commit sha or git tag.
   - `--dir-exists=<dirRelativeToPackageRoot>`

packages/melos/lib/src/command_runner/base.dart

@@ -85,19 +85,13 @@ abstract class MelosCommand extends Command<void> {
           'can be repeated.',
     );
 
-    argParser.addOption(
-      filterOptionSince,
-      valueHelp: 'ref',
-      help: 'Only include packages that have been changed since the specified '
-          '`ref`, e.g. a commit sha or git tag. Cannot be used with --diff.',
-    );
-
     argParser.addOption(
       filterOptionDiff,
       valueHelp: 'ref',
-      help: 'Only include packages that are different between current working '
-          'tree and the specified `ref`, e.g. a commit sha or git tag, '
-          'or between two different refs. Cannot be used with --since.',
+      help: 'Filter packages based on whether there were changes between a '
+          'commit and the current HEAD or within a range of commits. A range '
+          'of commits can be specified using the git short hand syntax '
+          '`<start-commit>..<end-commit>` and `<start-commit>...<end-commit>`',
     );
 
     argParser.addMultiOption(
@@ -133,31 +127,29 @@ abstract class MelosCommand extends Command<void> {
       negatable: false,
       help: 'Include all transitive dependents for each package that matches '
           'the other filters. The included packages skip --ignore and '
-          '--since checks.',
+          '--diff checks.',
     );
 
     argParser.addFlag(
       filterOptionIncludeDependencies,
       negatable: false,
       help: 'Include all transitive dependencies for each package that '
           'matches the other filters. The included packages skip --ignore '
-          'and --since checks.',
+          'and --diff checks.',
     );
   }
 
   PackageFilter parsePackageFilter(
     String workingDirPath, {
-    bool sinceEnabled = true,
+    bool diffEnabled = true,
   }) {
     assert(
       argResults?.command?.name != 'version' &&
           argResults?.command?.name != 'run',
       'unimplemented',
     );
 
-    final since =
-        sinceEnabled ? argResults![filterOptionSince] as String? : null;
-    final diff = argResults![filterOptionDiff] as String?;
+    final diff = diffEnabled ? argResults![filterOptionDiff] as String? : null;
     final scope = argResults![filterOptionScope] as List<String>? ?? [];
     final ignore = argResults![filterOptionIgnore] as List<String>? ?? [];
 
@@ -169,7 +161,6 @@ abstract class MelosCommand extends Command<void> {
           .map((e) => createGlob(e, currentDirectoryPath: workingDirPath))
           .toList()
         ..addAll(config.ignore),
-      updatedSince: since,
       diff: diff,
       includePrivatePackages: argResults![filterOptionPrivate] as bool?,
       published: argResults![filterOptionPublished] as bool?,

packages/melos/lib/src/commands/version.dart

@@ -41,11 +41,11 @@ mixin _VersionMixin on _RunMixin {
 
     final workspace = await createWorkspace(
       global: global,
-      // We ignore `since` package list filtering on the 'version' command as it
+      // We ignore `diff` package list filtering on the 'version' command as it
       // already filters it itself, filtering here would map dependant version
       // fail as it won't be aware of any packages that have been filtered out
-      // here because of the 'since' filter.
-      filter: filter?.copyWithUpdatedSince(null),
+      // here because of the 'diff' filter.
+      filter: filter?.copyWithDiff(null),
     );
 
     if (workspace.config.commands.version.branch != null) {
@@ -74,7 +74,7 @@ mixin _VersionMixin on _RunMixin {
     final packageCommits = await _getPackageCommits(
       workspace,
       versionPrivatePackages: versionPrivatePackages,
-      since: filter?.updatedSince,
+      diff: filter?.diff,
     );
 
     final packagesWithVersionableCommits =
@@ -716,7 +716,7 @@ mixin _VersionMixin on _RunMixin {
   Future<Map<String, List<RichGitCommit>>> _getPackageCommits(
     MelosWorkspace workspace, {
     required bool versionPrivatePackages,
-    required String? since,
+    required String? diff,
   }) async {
     final packageCommits = <String, List<RichGitCommit>>{};
     await Pool(10).forEach<Package, void>(workspace.filteredPackages.values,
@@ -725,7 +725,7 @@ mixin _VersionMixin on _RunMixin {
 
       final commits = await gitCommitsForPackage(
         package,
-        since: since,
+        diff: diff,
         logger: logger,
       );
 

packages/melos/lib/src/common/git.dart

@@ -252,32 +252,47 @@ Future<void> gitCommit(
   );
 }
 
+/// RegExp that matches `<commit1>..<commit2>` or `<commit1>...<commit2>`.
+final _gitVersionRangeShortHandRegExp = RegExp(r'^.+\.{2,3}.+$');
+
 /// Returns a list of [GitCommit]s for a Melos package.
 ///
-/// Optionally specify [since] to start after a specified commit or tag.
+/// Optionally specify [diff] to start after a specified commit or tag.
 /// Defaults to the latest release tag.
+/// Diff also supports specifying a range of commits, e.g. `HEAD~5..HEAD`.
 Future<List<GitCommit>> gitCommitsForPackage(
   Package package, {
-  String? since,
-  String preid = 'dev',
+  String? diff,
   required MelosLogger logger,
 }) async {
-  var sinceOrLatestTag = since;
-  if (sinceOrLatestTag != null && sinceOrLatestTag.isEmpty) {
-    sinceOrLatestTag = null;
+  var revisionRange = diff?.trim();
+  if (revisionRange != null) {
+    if (revisionRange.isEmpty) {
+      revisionRange = null;
+    } else if (!_gitVersionRangeShortHandRegExp.hasMatch(revisionRange)) {
+      // If the revision range is not a valid revision range short hand then we
+      // assume it's a commit or tag and default to the range from that
+      // commit/tag to HEAD.
+      revisionRange = '$revisionRange...HEAD';
+    }
+  }
+
+  if (revisionRange == null) {
+    final latestTag = await gitLatestTagForPackage(package, logger: logger);
+    // If no latest tag is found then we default to the entire git history.
+    revisionRange = latestTag != null ? '$latestTag...HEAD' : 'HEAD';
   }
-  sinceOrLatestTag ??= await gitLatestTagForPackage(package, logger: logger);
 
   logger.trace(
-    '[GIT] Getting commits for package ${package.name} since '
-    '"${sinceOrLatestTag ?? '@'}".',
+    '[GIT] Getting commits for package ${package.name} for revision range '
+    '"$revisionRange".',
   );
 
   final processResult = await gitExecuteCommand(
     arguments: [
       '--no-pager',
       'log',
-      if (sinceOrLatestTag != null) '$sinceOrLatestTag...@' else '@',
+      revisionRange,
       '--pretty=format:%H|||%aN <%aE>|||%ai|||%B||||',
       '--',
       '.',
@@ -370,27 +385,3 @@ Future<bool> gitIsBehindUpstream({
 
   return isBehind;
 }
-
-Future<bool> gitHasDiffInPackage(
-  Package package, {
-  required String diff,
-  required MelosLogger logger,
-}) async {
-  logger.trace(
-    '[GIT] Getting $diff diff for package ${package.name}.',
-  );
-
-  final processResult = await gitExecuteCommand(
-    arguments: [
-      '--no-pager',
-      'diff',
-      '--name-status',
-      diff,
-      '--',
-      '.',
-    ],
-    workingDirectory: package.path,
-    logger: logger,
-  );
-  return (processResult.stdout as String).isNotEmpty;
-}

packages/melos/lib/src/common/utils.dart

@@ -44,7 +44,6 @@ const filterOptionScope = 'scope';
 const filterOptionIgnore = 'ignore';
 const filterOptionDirExists = 'dir-exists';
 const filterOptionFileExists = 'file-exists';
-const filterOptionSince = 'since';
 const filterOptionDiff = 'diff';
 const filterOptionNullsafety = 'nullsafety';
 const filterOptionNoPrivate = 'no-private';