virtuslab/git-machete-intellij-plugin

Probably the sharpest git repository organizer & rebase/merge workflow automation tool you've ever seen

Git Machete IntelliJ Plugin

💪 Git Machete plugin is a robust tool that simplifies your git related workflow. It's a great complement to the JetBrains products' built-in version control system.

🦅 The bird's eye view provided by Git Machete makes merges/rebases/push/pulls hassle-free even when multiple branches are present in the repository (master/develop, your topic branches, teammate's branches checked out for review, etc.).

👁 A look at a Git Machete tab gives an instant answer to the questions:

• What branches are in this repository?
• What is going to be merged (or rebased/pushed/pulled) and to what?

🎯 With this plugin, you can maintain small, focused, easy-to-review pull requests with little effort.

⚙ It is compatible with all JetBrains products (IntelliJ IDEA, PyCharm, Android Studio etc.). The latest plugin version is available for IDE versions from 2022.3 onwards.
Earlier plugin versions (which might not have all the latest features & fixes) are available for earlier IDE versions as well, starting from as early as 2020.1.

🖥 For the console version, check git-machete.

Installing from JetBrains Marketplace

This plugin is available on JetBrains Marketplace.
To install this plugin go to File > Settings > Plugins (Preferences/Settings > Plugins on macOS) in your IDE, then make sure you are on Marketplace tab (not Installed), in search box type Git Machete and click Install.
After installation, depending on the IDE version, the restart may be required. In that case, just click Restart IDE and confirm that action in a message box.

Where to find the plugin tab

Git Machete IntelliJ Plugin is available under the Git tool window in the Git Machete tab. You can find the Git tool window in the lower left corner of the screen.
You can also use Ctrl + Alt + Shift + M (⌘⌥⇧M or ^⌥⇧M on macOS) shortcut to open it.

Getting started with Git Machete

The examples below show a few common situations where Git Machete proves exceptionally useful.

If you are a Git Master or have used the git-machete CLI already, you may want to jump directly to the features.

Scenario 1: Review

Let's start with a very common case of review. Suppose that you work on two branches: sticky-header and fancy-footer (you've split your work among these two branches to keep the PRs small and easily reviewable).

In the meantime, a teammate of yours requested a review of their PR for branch common-scripts...

Git Machete allows you to check out the remote branch with Slide In. Alternatively, you could check out it via git CLI or Git Branches widget in IntelliJ. Once the review is complete, you can simply check out any other branch from the right-click menu or by a double click — master in the example.

Once the branch common-scripts is no longer needed for review, it can be slid out (Slide Out) — deleted from the branch layout and optionally the branch can be removed from the local repository.

Scenario 2: Branch update

Some time passed and your teammate has merged the common-scripts before you managed to merge your branches. You are supposed to update master and your branches now.

Firstly, you can fetch all changes from the remote using Fetch All.
As you'd expect, your local master is behind its remote, so you perform Pull to get it in sync. Note that the pull via Git Machete plugin does not require checking out the given branch.

The edge between master and sticky-header turned red. It means that there are some commits belonging to the parent (master) branch that are not reachable from the child (sticky-header). In case of master, these commits came from the recently merged common-scripts.

To put sticky-header back in sync to master two options are available — Checkout and Sync to Parent by Rebase ... or Checkout and Sync to Parent by Merge ... Fortunately, there are no conflicts to resolve.
Once sticky-header is rebased or merged, you can do the same for fancy-footer.

You may want to update the remotes as well. To do so, perform Push... for both of the branches. The push can be done even for a branch that is not currently checked out. Note that force push is required (as you have rebased the branches since the latest push).

After the rebases and pushes, all of your branches are back in sync — both to their parents and to their remotes.

Scenario 3: Commit to parent branch (sequential branch setup)

A review of your sticky-header has been done and all you've applied and committed all the fixes.
Git Machete shows that sticky-header is ahead of its remote. Furthermore, the edge between sticky-header and fancy-footer is red. The solution to this situation will not differ much from the previous scenario...

You can start with Checkout and Sync to Parent by Rebase... to place fancy-footer back on top of sticky-header. Now Push... both branches. Everything is back in sync again.

Scenario 4: Merge (maintaining linear history)

A PR for your sticky-header branch has been approved and is ready to merge.
To make git revert & git bisect easier and generally simplify diagnostics & providing fixes in production settings, let's stick to linear git history and thus perform merges that do not produce the actual merge commits.
The way to go is to fast-forward merge sticky-footer into master.

Note that Fast-forward Merge into Parent does not require you to check out the branch getting merged (or its parent) beforehand. You can perform it while some other branch is checked out — fancy-footer in our case.

Once the fast-forward merge is complete, the edge between master and sticky-header gets gray, which means that the latter has been merged.
master is now ahead of remote because of the commits from sticky-header. Since master hasn't diverged from its remote tracking branch, Push... does not require force.

You can now Slide Out the merged sticky-header branch. The remaining master and fancy-footer branches are now in sync.

Complete feature list

Please see the feature list for more specific feature description.

Build

Please see the development documentation for instructions on how to build this plugin on your own.

Issue reporting

If you see any bug or just would like to propose any new feature, feel free to create an issue.

When reporting a bug, it'd be very helpful for us if you could enable the IntelliJ logging on a DEBUG level, reproduce a bug and include the logs from IntelliJ in the issue.

Go to Help > Diagnostic Tools > Debug Log Settings and then paste the following line:

com.virtuslab

Then reproduce the bug and go to Help > Show Log in Files (Help > Show Log in Finder on macOS) to open the log file.

References

For additional background on what we believe are good practices take a look into our slides presentation. It explains our motivations and gives you an overview of main Git Machete objectives.

For more information about the plugin, see the teaser blog post and the complete feature list.

See also git-machete — a CLI version of this plugin.

git-machete-intellij-plugin's Issues

Investigate usage of git4idea in backend

Usage of git4idea may bring many benefits (as some eventual operation are already refer to it).

Potentially depending on git4idea would give possibilities to handle the changing state of repository easier.

Deploy dependency injection in code (Google Guice)

Set up code formatter to keep field annotations in the preceding line

  @Nonnull @Getter
  private static final RepositoryGraph nullRepositoryGraph = new RepositoryGraphBuilder().build();

is much more readable than

  @Nonnull @Getter private static final RepositoryGraph nullRepositoryGraph = new RepositoryGraphBuilder().build();

esp. if there's a bunch a fields declared one after another.

Investigate compatibility of this plugin with IntelliJ versions

... and provide a proper description to README

https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties

Repairing of SLF4J error

This error are printed out on stderr when JGit is initialized:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation

Handling submodules in repository

Current implementation of JGitRepository is not adapted to handling submodules

Apply builder pattern to GitMacheteRepository...

...and probably other classes with heavy constructors

Reduce spacing between graph elements

After increasing spaces and adding the indents (#85) graph became too high.

Find and apply the solution to improve its layout in this aspect.

Suggested solution:
Modify the high of some (splitting and phantom?) graph elements` cells.

Delegate generation of equals/hashCode to Lombok wherever possible

To ensure canEqual, calling equals of superclass, sync b/w hashCode and equals etc. are properly taken care of.

Wire up code autoformatter

Consider making compile-time dependencies intransitive by default

For instance now intellijPlugin has a transitive dependency on gitCoreApi and branchRelationFileApi... but most likely, for the sake of low coupling, it should just have access to the interfaces of gitMacheteApi and not the interfaces deeper layers (of course it doesn't have the access to the implementations already, but that's not the issue here).

So, consider making the compile-time module dependencies intransitive by default if feasible.

Investigate pros and cons of var usage

and depending on the results of the investigation

• use is more (especially refactor intellijPlugin module, that does not use vars)
  or
• limit it usage to proper situations

Extract common Gradle dependencies (Guice, Lombok, junit) to a shared location

If possible, extract the entire dependencies { ... } block (ofc excluding references to other modules of the project) and maybe even plugins/sourceCompatibility/repositories. If that's not easily doable, at least extract the versions of external dependencies to a shared location for easy updating (btw e.g. junit got updated to 4.13 in the meantime)

Set up a simple CI pipeline

Preferably TravisCI (since that's where also CLI's and other VL's projects' CIs live: https://travis-ci.org/VirtusLab/git-machete)

At least compile everything + check there's no improperly formatted code (see #13)

Add extra padding between subtrees

develop-to-master-20200211 and develop are too close to each other

Update graph table on changes to machete file

Display correct name of remote in sync to origin status text

Improve color handling in graph elements

SyncToParentStatus presence enables us to pick and distinguish colors specified for graph elements.

However, for some elements SyncToParentStatus field is confusing (in particular to any other than BranchElement).

The same applies to SyncToOriginStatus.

Coloring of graph elements needs a general refactoring.

Enforce strict null correctness check across the codebase

and corresponding nullable

#52 (comment)

Mark the commit deemed as fork point

Git Machete CLI marking:

Rename packages, classes and interfaces to more appropriate forms

com.virtuslab.branchrelationfile -> com.virtuslab.branchrelationfile.impl
com.virtuslab.gitcore.gitcoreapi -> com.virtuslab.gitcore.api
com.virtuslab.gitcore.gitcorejgit -> com.virtuslab.gitcore.impl
com.virtuslab.gitmachete.gitmacheteapi -> com.virtuslab.gitmachete.api
com.virtuslab.gitmachete.gitmachetejgit -> com.virtuslab.gitmachete.impl

JGit* -> GitCore*

Dispatch git fetch/git pull to IntelliJ git plugin

Checking sync with remote tracking branch

Enhance fork-point algorithm to handle branch tree modifications

Better implementation of getMergeBase

getMergeBase from JGitBranch can be implemented in better way.

Checking sync with upstream/parent branch

Add handling of multirepository projects

Projects may contain multiple repositories. The plugin should be able to handle such a situation.

Parse .git/machete file

Checkout branch from graph table

Motivation:
Switching branches with DvcsStatusWidget (down right corner), console git checkout or from version Control Log table is inconvenient (might enforce you to close Git Machete tab).

0. First decide how the feature should be handled (double click, dropdown, some other way?).
1. Add the possibility to perform branch checkout from Git Machete graph table.

Class that may be worth to have a look at: git4idea.branch.GitBranchWorker

Ensure data classes are final to avoid issues with `equals` when subclassing

Enable syntax-aware editing of .git/machete from IntelliJ

It's not obvious coz by default the entire .git/ is marked as ignored in Settings>Editor>File Types... => OK, this doesn't look much of a problem though

List commits belonging specifically to the given branch

See git machete fork-point

Ensure VCS used for project in IDEA is git (and not hg/p4/...) before displaying Git Machete tab

Possibly it's already enforced somehow... dunno

Dispatch git push (also in `--force-with-lease` version) to IntelliJ git plugin

Also: handle setting remote tracking branch while doing the push (--set-upstream flag of git push)

Implement (optional) sliding out of merged branches

Export installable IntelliJ plugin zip as an artifact from CI pipeline

So that others can preview the state of affairs as of the given PR :)

Employ Vavr (or maybe rather Guava?) where reasonable

https://www.vavr.io/vavr-docs

Immutable collections FTW, I'd use them everywhere :all-the-things:

Also possibly Try<...> e.g. for things like result of parsing .git/machete and consider Option instead of Optional everywhere for better null handling (?)

To a lesser extent: Lazy, pattern matching

Btw1: read about Vavr's name origin/history if you haven't heard, it's pretty epic

Btw2: for me this lib literally looks like making constructs from Scala as closely reflected in Java as possible (they mention Scala in the docs a couple times)

Btw3: it's pronounced /ˈweɪ.vɚ/ like "waiver", lol

Custom annotations cause exception

Steps to reproduce:
create GitMacheteRepository with machete file containing custom annotation

Expected:
No exception. Annotations handled/ignored.

Actual:
org.eclipse.jgit.errors.RevisionSyntaxException: Invalid ref name

Basic functional (black-box) tests for the backend

TBD how to set up the sample git repos for that purpose

Ensure each PR bumps version in intellijPlugin/build.gradle

Add a script that ensures that the version has been version bumped (wrt. MINOR or PATCH - for pre-production versions 0.x.y that doesn't matter much, https://semver.org/) into CI pipeline. That would be super-useful to avoid confusion while beta-testing (nothing worse than two even slightly different versions of the same software... that nevertheless have the same version number).

Not sure if CircleCI gives an easy access to PR base branch from inside the pipeline... if the answer isn't immediately obvious, check env vars, git remote -v, git config -l for hints. Otherwise, it can be always compared to what's on origin/master (which is almost surely available from inside the pipeline).

Display equivalent of `git machete status` output in manner similar to how git log is displayed in IntelliJ

Ensure displayed state of branches is auto-updated when the underlying repo changes on disk

With that in mind, I think that the backend implementation (@micpiotrowski) should be from now on kept as stateless as possible...

Prohibit rebase during an ongoing operation like merge/revert/another rebase etc.

Ensure that update (rebase) is not possible during ongoing rebase

Probably it should be performed in update of GitInteractiveRebaseAction

Dispatch git rebase (in `git machete update` flavour) to IntelliJ git plugin

Provide integration with GitHub

Especially wrt. open PRs (see VirtusLab/git-machete#82)

Investigate weak performance for larger graphs

As discussed today, apparently sth in this method leads to weak performance for larger graphs... ofc this can be investigated & resolved after this PR is merged

Originally posted by @PawelLipski in #28

Determine plugin layout and behaviour in case of missing machete file

Possibly then a suggested (aka discovered) layout of branches can be displayed (?) or stuff like that. Anyway, would be nice to encourage users to start actively using the plugin once they installed it as much as possible :)

Originally posted by @PawelLipski in #28

Wire up static code analyzer to CI

Preferably a one that is fully configurable (as in, each specific check can be turned off/on, and if on, severity level can be chosen - warn/error).

This is intended to catch smells that aren't captured by Java compiler by default, like comparing an Optional instance to null.

Extract and enhance dev guide from readme

include project setup, git hooks (spotless check), etc

Illegal reflective access on CI during gradle test

WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by com.google.inject.internal.cglib.core.$ReflectUtils$1 (file:/root/.gradle/caches/modules-2/files-2.1/com.google.inject/guice/4.2.2/6dacbe18e5eaa7f6c9c36db33b42e7985e94ce77/guice-4.2.2.jar) to method java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int,java.security.ProtectionDomain)
WARNING: Please consider reporting this to the maintainers of com.google.inject.internal.cglib.core.$ReflectUtils$1
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release