Delete Head Branches

While GitHub offers settings for automatic deletion of merged branches, its approach is often a blunt instrument, indiscriminately deleting any merged branch. Mergify’s delete_head_branch action brings nuance to this process, allowing repository maintainers to craft conditions under which branches should be deleted after their pull requests are merged. By utilizing Mergify's intricate pull request rules and conditions, users can design custom branch cleanup strategies that cater to their specific workflow requirements.

GitHub's automatic branch deletion documentation provides the basic settings, but for those who require a more nuanced approach, Mergify's delete_head_branch is the ideal tool.

GitHub's Default Deletion: As soon as a pull request branch is merged, GitHub will automatically delete it, given the repository setting is enabled. This doesn’t account for scenarios where you might want to retain the branch for some time or under specific conditions.

Mergify’s Conditional Deletion: Using Mergify, one can establish specific conditions under which a branch should be deleted post-merge. This can be based on labels, types of files changed, the nature of the pull request, and more.

Here are a few example workflows that showcase the flexibility and power of Mergify’s delete_head_branch action:

Cleanup On-Demand

Only delete merged branches when the pull request is labeled with "cleanup".

1
pull_request_rules:
2
  - name: delete head branch after merge if the label "cleanup" is present
3
    conditions:
4
      - merged
5
      - label = cleanup
6
    actions:
7
      delete_head_branch:

Prevent Deletion for Dependent Branches

Avoid deleting branches that other pull requests depend on, ensuring dependent work isn't inadvertently closed.

1
pull_request_rules:
2
  - name: delete head branch after merge but not if other PRs depend on it
3
    conditions:
4
      - merged
5
    actions:
6
      delete_head_branch:
7
        force: false

Aggressive Cleanup

In scenarios where you are certain about deleting branches, even if other pull requests depend on them:

1
pull_request_rules:
2
  - name: always delete head branch after merge
3
    conditions:
4
      - merged
5
    actions:
6
      delete_head_branch:
7
        force: true

Conditional Cleanup Based on File Type

For instance, if documentation-related branches (those that only modify .md files) need to be deleted immediately post-merge:

1
pull_request_rules:
2
  - name: delete doc-related branches post-merge
3
    conditions:
4
      - merged
5
      - "files~=\.md$"
6
    actions:
7
      delete_head_branch:

Time-based Cleanup

Suppose you want branches to remain for a day post-merge for any potential discussions and then get deleted:

1
pull_request_rules:
2
  - name: delete branches 24 hours post-merge
3
    conditions:
4
      - merged-at < 1 day ago
5
    actions:
6
      delete_head_branch:

The delete_head_branch action is an example of how Mergify offers detailed control over Git workflows, moving beyond the default settings of platforms like GitHub. By understanding the various use-cases and implementing them in your repository, you can maintain a cleaner, more organized codebase, and ensure that old branches don't clutter your project as it grows.

Remember, the key is in understanding your project's requirements and leveraging tools like Mergify to tailor workflows that cater specifically to those needs.