Category: Git

Reading code with exercises and IntelliJ IDEA

This article was first published in NLJUG‘s Java Magazine. You can view an online copy here.

As developers, we read code more than we write it. Research has shown that “developers on average spend as much as 58% of their time comprehending existing source code” (The Programmer’s Brain – Felienne Hermans). And yet, we don’t practice reading code nearly as much as we do writing code. Let’s look at how to practice reading code and how IntelliJ IDEA can help.

Code Reading Club

In 2022, a friend invited me to join a Code Reading Club, based on the work of Felienne Hermans. We have monthly sessions where we take a sample of code and apply structured exercises to this code to try and make sense of it. I have really enjoyed our sessions, not only for the opportunity to practice reading code, but also because I find it very interesting to learn how other people read code. To start your own club, use the Code Reading Club resources. Or try the code reading exercises from Felienne’s book, The Programmer’s Brain.

While it’s possible to use these exercises in our daily work, developers mostly read code in the IDE.

Exploring an existing code base

When joining a new team or company, you need to quickly get up to speed with existing code bases. Obviously you can look at the project, but unfortunately not everything can be captured in the code.

It helps to have a teammate give an introduction to the application; a description of what the application does, its place in the landscape, relevant history and design choices, current plans (are you actively developing new features or mostly doing maintenance?), which parts of the application are changed more than others, as well as links to existing documentation and other relevant information. Also think about which stories a new team member can pick up to help them become familiar with the project.

As a new team member, check out all relevant repositories. Make sure you can build the project, run the tests and run the application locally. How to do this will hopefully be described in the README. If not, consider adding it. Running the project locally can help you to both see how the application works by trying it out, and make sure that you can test your changes when you are done.

Opening a project in the IDE allows you to search and navigate your codebase more easily, as well as use additional useful IDE features. Let’s dive into several powerful IntelliJ IDEA features you can use to quickly be productive.

Note: Keyboard shortcuts are provided for macOS and Windows/Linux respectively.

Project overview

Explore modules and packages in the Project tool window (⌘1 | Alt+1) to get an idea of the project. If you prefer a visual representation, IntelliJ IDEA can generate several types of diagrams for you, including UML class diagrams. Also consider drawing your own diagrams; this will help you retain the information better and lets you focus only on the information you need for the task at hand. 

To understand dependencies between modules, packages and classes, the Dependency Structure Matrix (DSM) can help. Open the DSM from the main menu using Code | Analyze Code | Dependency Matrix….

Dependency Structure Matrix

In this example the matrix displays modules in a project. As you can see in the legend at the top right, dependencies are marked in blue and the direction of the dependencies is marked in green and yellow; the module marked in green depends on the module marked in yellow. Visualising the dependencies can help us to get an overview of the application. If you prefer, you can also generate a Project Modules diagram. Note that this diagram only gives you one side of the equation (which modules the selected module depends on). 

Search & navigate

Use Search Everywhere (⇧⇧ | Shift+Shift) to find anything in your project, including IDE settings & features. Other useful navigation features include Recent Files (⌘E | Ctrl+E) or Recent Locations (⌘⇧E | Ctrl+Shift+E). Knowing how to search and navigate code in your IDE is helpful when working with existing code, so you can focus on the task at hand.

Looking at a slice of the application

Instead of looking at the whole code base, look at a specific slice of the application. For example, find the main method and see what the application does from there, find a specific endpoint and trace the code down to the database, or find the location where an error is thrown and trace the code back up to how you got there. 

Understanding a piece of code

At some point you’ll find a piece of code that you will need to understand, for example, to fix a bug or make necessary changes. If you’ve ever been overwhelmed by a piece of code without any idea how to start, this is where code reading exercises can help! Of course, your IDE can also provide you with handy features. For starters, IntelliJ IDEA provides you with hints about the code, like syntax highlighting, inlay hints and gutter icons.

One of the reasons code can be confusing is because of a lack of information. For example, you might not know the exact implementation of a class or method. While you can Jump to Source (⌘↓ | F4) to navigate to the relevant code, and use shortcuts to Navigate Back (⌘[ | Ctrl+Alt+Left Arrow) and Navigate Forward (⌘] | Ctrl+Alt+Right Arrow), it’s easy to get lost in a large code base. To see where a particular file is located in the project, use the crosshair icon at the top of the Project tool window.

Select Opened File

It is also possible to pull up additional information using Quick Documentation (F1 | Ctrl+Q) to show the Javadoc, Quick Definition (⌥␣ | Ctrl+Shift+I) to see the code or Type Information (⌃⇧P | Ctrl+Shift+P) to determine which type is returned by an expression.

Did you know IntelliJ IDEA can help you work with regular expressions? You can mark a String as RegExp from Show Context Actions (⌥⏎ | Alt+Enter), using Inject Language or Reference and selecting RegExp (or a specific flavor of regular expressions). From the Show Context Action menu, select Check RegExp to open a popup where you can check whether a certain String matches the regular expression. Place your String in the Sample field in the popup; a yellow warning sign will be shown if the String is incomplete, a red exclamation mark shows the String does not match, or a green check mark will indicate that the String matches the RegExp.

Check RegExp

The structure of the code

Code is not read from top to bottom. Code doesn’t run linearly either! Developers “scan” code looking for the parts you’re interested in. Using white space and formatting can help improve readability.

When you write code in IntelliJ IDEA, the code will be formatted automatically. If you encounter code that isn’t properly formatted, you can reformat it (⌘⌥L | Ctrl+Alt+L).

You can collapse the code (⌘⇧- | Ctrl+Shift+Minus) to get an overview of a class without being overwhelmed with too many details. You can expand it again (⌘⇧+ | Ctrl+Shift+Plus) as needed. Other ways to get a quick overview of the code are to use the File Structure popup (⌘F12 | Ctrl+F12), or the Structure tool window (⌘7 | Alt+7). 

When reading code, it might help to play with it a little bit as you try to understand it. Remember to revert any changes you make!

Restructure

Restructure the code by moving code blocks around to match your mental model, preferred style or coding conventions. Use shortcuts to move a statement up (⌘⇧↑ | Ctrl+Shift+Up Arrow) or down (⌘⇧↓ | Ctrl+Shift+Down Arrow). 

Refactoring

You can use refactoring to change the code to aid your understanding. Rename variables or methods (⇧F6 | Shift+F6), extract variables (⌥⌘V | Ctrl+Alt+V) or extract methods (⌥⌘M | Ctrl+Alt+M) and give them meaningful names, inline variables (⌥⌘N | Ctrl+Alt+N) you don’t need. The most frequently used refactorings are available in the Refactor This menu (^T | Ctrl+Alt+Shift+T) . Additional refactorings or quick fixes might be available under Show Context Actions (⌥⏎ | Alt+Enter).

Testing

Look at the tests for a piece of code to see what this code is supposed to do, using Navigate to Tests (⌘⇧T | Ctrl+Shift+T). Hopefully names of the tests will express the intended behavior of the application. This is useful for two reasons: 1. The tests will serve as executable documentation of the system. 2. Should the tests fail in the future, good names can help to quickly tell you what’s wrong, so you don’t spend more time than necessary analyzing failures. 

Debugging

Run code through the debugger to see if the actual behavior of the code matches your understanding. Place a breakpoint (⌘F8 | Ctrl+F8) in the code at the point where you want to observe its state. Run the test in debug mode (⌃D | Shift+F9); execution will halt when it hits the breakpoint. You can observe the state of objects & variables in the editor and in the debug window, and look at the call stack in the Debug tool window. Continue execution by either stepping into a method (F7) or stepping over a line (F8). 

The IntelliJ IDEA debugger is very powerful and has many useful features. I highly recommend familiarizing yourself with its features; this will come in handy next time you need to urgently debug your code for a production incident! 

Version control

Sometimes you might want to know how the code came to be the way it is, and do a bit of what I like to call “Git archeology”. Use Annotate with Git Blame to see when the code was last changed. Click the commit in the gutter to navigate to that commit in the Git tool window and look at the diff. If you’re using JetBrains AI Assistant [13], you can also ask it to explain the commit to you. Right-click the commit and select Explain Commit with AI Assistant from the context menu.

Explain Commit with AI Assistant

AI Assistant features to understand code

Finally, AI coding assistants, like JetBrains AI Assistant, may offer other useful features for understanding existing code. For example, chat with an AI Assistant and ask questions about software development, your project’s code and version control. Ask it to explain specific code to you, maybe even explain regular expressions, SQL queries, cron expressions, etc.

Because it is deeply integrated within IntelliJ IDEA, JetBrains AI Assistant can explain runtime errors right from the console. With another assistant you may need to copy-paste the error into a chat window. Alternatively, use an AI assistant to write documentation for a class or method. The generated Javadoc is often more concise than the explanation in the chat.

Conclusion

I hope you found this overview useful to see how to approach understanding existing code with the help of IntelliJ IDEA. This article is based on my talk “Reading Code”, which includes live demos of the features discussed in this article.

Shortcuts

NamemacOSWindows/Linux
Project tool window⌘1Alt+1
Search Everywhere⇧⇧Shift+Shift
Recent Files⌘ECtrl+E
Recent Locations⌘⇧ECtrl+Shift+E
Jump to Source⌘↓F4
Navigate Back⌘[Ctrl+Alt+Left Arrow
Navigate Forward⌘]Ctrl+Alt+Right Arrow
Quick DocumentationF1Ctrl+Q
Quick Definition⌥␣Ctrl+Shift+I
Type Information⌃⇧PCtrl+Shift+P
Show Context Actions⌥⏎Alt+Enter
Reformat code⌘⌥LCtrl+Alt+L
Collapse all⌘⇧-Ctrl+Shift+Minus
Expand all⌘⇧+Ctrl+Shift+Plus
File Structure⌘F12Ctrl+F12
Structure tool window⌘7Alt+7
Move Statement Up⌘⇧↑Ctrl+Shift+Up Arrow
Move Statement Down⌘⇧↓Ctrl+Shift+Down Arrow
Refactor Rename⇧F6Shift+F6
Extract Variable⌥⌘VCtrl+Alt+V
Extract Methods⌥⌘MCtrl+Alt+M
Inline Variable⌥⌘NCtrl+Alt+N
Refactor This^TCtrl+Alt+Shift+T
Navigate to Tests⌘⇧TCtrl+Shift+T
Toggle Breakpoint⌘F8Ctrl+F8
Debug⌃DShift+F9
Step intoF7F7
Step overF8F8

Cherry Picking Git Commits To A Different Branch

If you accidentally committed your code to the wrong branch, you don’t have to redo the work. IntelliJ IDEA offers a low-stress solution by allowing you to move your commit to a different branch using Git’s cherry-pick option.

Cherry Picking Git Commits To A Different Branch

Links

Reading Code like a pro

As developers, we spend more time reading code than writing it, and this video provides tips to enhance your code-reading skills within the IntelliJ IDEA IDE. Learn how to leverage features like syntax highlighting, inlay hints, and code formatting to navigate and understand code effortlessly. Discover techniques to quickly scan code, collapse and expand sections for efficient navigation, and use powerful search functionalities to locate specific elements.

Whether you’re a beginner or an experienced developer, these tips will empower you to read and comprehend code with confidence, making your coding journey in IntelliJ IDEA a seamless and productive experience.

Links

IntelliJ IDEA: Selectively Commit Changes to a File

Sometimes you’re making multiple changes to a file that you don’t want to commit together. For example, if you’re working on a new feature, but notice some other small things you want to fix. If these changes are in separate files, we can commit each file separately. But what if they’re in the same file?

In IntelliJ IDEA (as of version 2023.3), we can now select which chunks and specific lines we want to add to our commit.

We can see which files were changed by opening the Commit tool window (⌘0 on macOS, or Alt+0  on Windows/Linux). Here we can open the diff for a particular file to see which changes were made to that file, using ⌘D (macOS) / Ctrl+D (Windows/Linux).

IntelliJ IDEA showing a diff in a file. There are multiple checkboxes in the gutter of the changed file for different changes to the file.

In the diff, we have the option to include specific changes to our commit, by clicking the Include into commit checkbox in the gutter next to each chunk of modified, deleted or newly added code.

IntelliJ IDEA showing a diff in a file and checkboxes in the gutter of the changed file. A tooltip on a checkbox shows "Include into commit".

We can even select specific lines from a change to include in a commit. To commit only a specific line from a chunk, right-click the line you want to include and select Split Chunk and Include Current Line into Commit.

IntelliJ IDEA showing a diff in a file with a checkbox in the gutter of the changed file. The context menu shows the option "Split Chunk and Include Current Line into Commit" highlighted.

Alternatively, hover over the gutter and select the checkbox next to the line you want to include in the commit. Or, if we change our mind, we can also hover over the gutter and clear the checkbox next to the line we want to exclude.

IntelliJ IDEA showing a diff in a file. There are multiple checkboxes in the gutter of the changed file. A tooltip on one of the checkboxes shows "Include into commit".

Once we have selected all the changes we want to commit, we write a meaningful commit message, and select Commit. Any unselected changes will stay in the current change list, so that you can commit them separately later.

What if we don’t want to add these changes to the same pull request, not even in a separate commit? Maybe you want to do some more cleaning up in your code base, and create a separate pull request for those changes later. We can undo this commit and move these changes to a different change list. To do so, select Move to Another Changelist from the context menu of a modified chunk.

IntelliJ IDEA showing a diff in a file with a checkbox in the gutter of the changed file and a context menu with the option "Move Lines to Another Changelist" highlighted.

Next, we can name our new changelist. The changes will be assigned to this changelist and we can see it in the Commit tool window.

IntelliJ IDEA showing a diff in a file with a popup on top. The popup is titled Move Lines to Another Changelist and the new changelist is named "Fixes".

Links

IntelliJ IDEA Pro Tips: Selectively Commit Changes to a File

While working on a new feature, you find some small other things to fix. Since these changes are unrelated, you probably shouldn’t commit them together. You could revert these changes to redo them separately, but who wants to do extra work? Fortunately, you can now select which chunks or even lines of changes to add to your commit. You can commit the rest separately or even move it to a new change list.

Links

Working with GitLab Merge Requests in IntelliJ IDEA

In this tutorial, we will take a look at working with GitLab Merge Requests inside IntelliJ IDEA.

When reviewing Merge Requests in a web interface, we don’t have the same support that our IDE gives us, like syntax highlighting and the context within which the code was written.

IntelliJ IDEA has support for reviewing and merging GitLab Merge Requests. These features are available if the IntelliJ IDEA project has a remote that points to GitLab.

Remote

We can open the GitLab Merge Requests using the GitLab logo on the left, or from the menu by going to Git > Gitlab > Show Gitlab Merge Request.

Open Merge Requests from logo
Open Show GitLab Merge Requests from menu

Logging in to GitLab from IntelliJ IDEA

If we aren’t already logged in to GitLab via IntelliJ IDEA, the GitLab Merge Requests tool window will prompt us to Log In.

Log In

We can log into GitLab with a token. When we click Generate, this will take us to the GitLab page where a token with the right scopes can be generated for us. Click the button Create personal access token to create the token. When the token is generated, click the button to copy the token.

Generate a token
Create Personal Access Token
Copy the token

We can copy the token into the Token field in the popup and click Log In.

Paste the token into the Token field

Alternatively, we can use an existing token, as long as it has the required scopes.

We can also log in to our GitLab account in the Settings. Open the Settings (⌘, on macOS | Ctrl+Alt+S on Windows/Linux) and go to Version Control > GitLab. Click Add Account (⌘N on macOS | Alt+Insert on Windows/Linux) to add an account if there is no account logged in, or click the + button at the top left to add an account. In the popup, add the Server if needed, paste the token from GitLab into the Token field in the popup and click Log In.

Add GitLab account in Settings
Paste the token into the Token field in Settings
Account added in Settings

GitLab Merge Request tool window

Once we’re logged in, the GitLab Merge Requests tool window will show all open Merge Requests for the GitLab repository.

GitLab Merge Requests tool window

We can change the search criteria to look for specific Merge Requests. We can use predefined filters, or search for something more specific.

Filter
Search

If the Merge Request has assignees and/or reviewers assigned, we can see them here.

Assignee
Reviewer

We can see the details of a specific Merge Request by double-clicking on it.

Merge Request details

We can go back to the list of search results by clicking the project name in the top left of the Merge Requests tool window. We can see that the Merge Request we just looked at still has a tab open here, in case we want to go back.

Click project name to go back to the list of Merge Requests

Usually, you’ll want to look for open Merge Requests, since these are the ones that need attention. Let’s double-click, or press Enter, on one of these Merge Requests.

Open Merge Requests

View GitLab Merge Requests inside IntelliJ IDEA

If the Merge Request does not have a reviewer assigned, we can assign one from the Merge Request tool window in IntelliJ IDEA. Click the three dots at the bottom left of the Merge Request details and select the action Request Review. From the list that pops up, select the reviewer(s) to assign this Merge Request to.

Request Review
Assign reviewer

We can see the files that have been changed in the Merge Request in the bottom left window, and the timeline in the main editor pane.

Changed files and timeline

We can also select a file to see the diff as well as the comments for that file. We can go back to the timeline by clicking View Timeline.

The timeline shows the same information as the GitLab Merge Request activity page. The timeline shows activity on the Merge Request, including comments and other status changes in the main editor pane. If there are inline comments on the code, we can see them here.

It also shows the result of any checks that were run. We can go to the details to see which checks failed, and even click them to go straight to the failing check on GitLab, so we can look at the details.

Checks failed

We can open the Merge Request in our browser in several ways. We can right-click the Merge Request number and select Open in Browser. Alternatively, we can open the Merge Request in our browser by right-clicking it, either when it’s already open, or in the list of Merge Requests and selecting Open Merge Request in Browser.

Open on GitLab
Open in browser

IntelliJ IDEA also shows if there are any conflicts, so we know if this request is safe to merge or not.

Conflicts

We can open any of the files that make up the Merge Request, and IntelliJ IDEA will show them in the diff viewer, so we can have a closer look at the changes that make up the Merge Request. Inline comments will be displayed in the diff view too. Alternatively, we can open the diff view by selecting the file and using the shortcut for Show Diff (⌘D on macOS | Ctrl+D on Windows/Linux).

Show diff

If the Merge Request contains changes to multiple files, we can navigate between those files. We can do so using the arrows at the top of the diff viewer, or using the shortcuts to Compare Next File (⌃⇧→ on macOS | Alt+→ on Windows/Linux) or Compare Previous File (⌃⇧← on macOS |Alt+← on Windows/Linux).

Navigate between files

If the Merge Request consists of multiple commits, we can see the individual commits in the Changes from dropdown list. We can look at the changes for an individual commit if we want.

Multiple commits

We can also see the number of comments for the Merge Request, and for each file.

We can Hide All Windows (⇧⌘F12 on macOS | Ctrl+Shift+F12 on Windows/Linux) to focus on the diff. We can Restore Windows using the same shortcut.

Alternatively, we can reopen the Merge Requests window by opening the Recent Files dialog (⌘ E on macOS | Ctrl+E on Windows/Linux), which also lets us open up any of the Tool Windows. Here we can search for “merge” to find the Merge Request tool window.

Recent files

Adding comments from GitLab and IntelliJ IDEA

Let’s look at comments on our Merge Request.

We can add comments to the GitLab conversation. Comments on this page are comments that apply to the Merge Request as a whole, and not a specific piece of code. We can see these comments inside IntelliJ IDEA too. We might need to refresh our Merge Request window, either using the shortcut to Refresh Reviews (⌘R on macOS | Ctrl+F5 on Windows/Linux) or by right-clicking the Merge Request window and selecting Refresh Merge Request.

Comment from GitLab
Refresh reviews

We can also add comments from inside IntelliJ IDEA. We can place high-level comments, like the comment we just placed from GitLab.

Comment from IntelliJ IDEA

We might also want to add comments on particular parts of the code. We can do so from inside IntelliJ IDEA by clicking on the plus in the gutter of the diff viewer. For example, let’s add a comment to the current Merge Request.

Inline comment

We can edit or delete comments. We can also reply to comments or resolve a comment that is no longer relevant, for example, if the code has been updated in line with the comment.

Working with comments

From the diff viewer, we can submit our review and approve the Merge Request if we think it’s ready to be merged.

Submit Review and Approve

Reviewing GitLab Merge Requests inside IntelliJ IDEA

One feature that’s really helpful when we’re reviewing a Merge Request is that we can check out the code that is in the Merge Request. In this project, I’m currently on the main branch. Let’s check out the branch for this Merge Request.

Check out branch locally

With the branch checked out locally, we can navigate the code related to this Merge Request. This lets us not only look at the code, but also make sure that the project still builds and tests pass. We can potentially make changes too.

Build success

Finally, let’s look at how to finish off the Merge Request.

If a Merge Request is no longer relevant, and we’re not going to take the changes that went into the Merge Request, we can close it. We can do so by clicking the three dots at the bottom left of the Merge Request tool window and selecting Close Merge Request.

Close

If the Merge Request is ready, meaning all the checks have passed, questions have been answered and requested changes to the code have been made, we can merge it. We can do so by clicking the Merge button at the bottom left of the Merge Request window. We also have the option to Squash and Merge, meaning all commits will be combined into a single commit when merging. We can add our own commit message for the merge, or edit the default one if we want to.

Merge
Edit commit message

The Merge Request will be merged, and if we do a Fetch we can see the updated branches for this repository.

Fetch
Updated branches

We can see in our browser that the Merge Request has been closed.

Merged

Summary and shortcuts

As we’ve seen, we can work with GitLab Merge Requests right inside IntelliJ IDEA. We can see all Merge Requests on a project, filter them or search for a specific Merge Request, perform a code review and add comments, see whether checks have passed and there are no merge conflicts, checkout the branch to run it locally, submit our review and approve the Merge Request, and merge (or close) the Merge Request all from inside our IDE.

IntelliJ IDEA Shortcuts Used

Here are the IntelliJ IDEA shortcuts that we used.

NamemacOS ShortcutWindows / Linux Shortcut
Open Settings⌘,Ctrl+Alt+S
Add Account⌘NAlt+Insert
Show Diff⌘DCtrl+D
Compare Next File⌃⇧→Alt+→
Compare Previous File⌃⇧←Alt+←
Hide all windows / Restore windows⇧⌘F12Ctrl+Shift+F12
Recent files⌘ECtrl+E
Refresh reviews⌘RCtrl+F5
IntelliJ IDEA shortcuts used

Related Links

IntelliJ IDEA: GitLab Merge Requests

Overview of IntelliJ IDEA 2023

IntelliJ IDEA is designed to help developers like us stay in the flow while we’re working. Like all IDEs, it has a lot of functionality available, but it’s designed to get out of your way to let you focus on the code.

Take a look at this overview of IntelliJ IDEA.

Introduction

  • Find Action: ⌘ ⇧ A (on macOS) / Ctrl+Shift+A (on Windows/Linux)
  • Feature Trainer
  • Hide all windows: ⌘ ⇧ F12 (on macOS) / Shift+Command+F12 (on Windows/Linux)
  • Project tool window: ⌘1 (on macOS) / Alt+1 (on Windows/Linux)
  • Quick Switch Scheme: ^`(on macOS) / Ctrl+` (on Windows/Linux)
  • IDE viewing modes
  • Preferences: ⌘, (on macOS) / Ctrl+Alt+S (on Windows/Linux)

Coding assistance

  • Code completion
  • Complete Current Statement: ⌘ ⇧ ⏎ (on macOS) / Shift+Ctrl+Enter (on Windows/Linux)
  • Show Context Actions: ⌥ ⏎ (on macOS) / Alt+Enter (on Windows/Linux)
  • Intention actions
  • Navigate to next highlighted error: F2
  • Navigate to previous highlighted error: Shift F2
  • Generate code: ⌘ N (on macOS) / Alt + Insert (on Windows/Linux)
  • Live templates

Refactoring

  • Rename: Shift F6
  • Extend selection: ⌥ Up (on macOS) / Ctrl+W (on Windows/Linux)
  • Extract variable: ⌘ ⌥ V on macOS) / Ctrl+Alt+V (on Windows/Linux)
  • Postfix completion
  • Reformat code: ⌘ ⌥ L (on macOS) / Ctrl+Alt+L (on Windows/Linux)
  • Move statement up: ⇧⌘ Up (on macOS) / Ctrl+Shift+Up (on Windows/Linux)
  • Surround with: ⌘ ⌥ T (on macOS) / Ctrl+Alt+T (on Windows/Linux)
  • SmartType Completion: ^ ⇧ Space  (on macOS) / Shift+Ctrl+Space (on Windows/Linux)
  • Inline: ⌘ ⌥ N (on macOS) / Ctrl+Alt+N (on Windows/Linux)
  • Extract method: ⌘ ⌥ M on macOS) / Ctrl+Alt+M (on Windows/Linux)

Testing & Debugging

Navigation

  • Navigate backwards: ⌘ [ (on macOS) / Ctrl+Alt+Left (on Windows/Linux)
  • Navigate forwards: ⌘ ] (on macOS) / Ctrl+Alt+Right (on Windows/Linux)
  • Find usages / declaration: ⌘ B (on macOS) / Ctrl+B (on Windows/Linux)
  • Recent Files: ⌘E (on macOS) / Ctrl+E (on Windows/Linux)
  • Recent locations: ⇧⌘E (on macOS) / Ctrl+Shift+E (on Windows/Linux)
  • Search everywhere: ⇧⇧ (on macOS) / Shift Shift (on Windows/Linux)
  • Find in files: ⇧⌘F (on macOS) / Ctrl+Shift+F (on Windows/Linux)

Reading Code

  • Folding -> Expand: ⌘ + (on macOS) / Ctrl+ + (on Windows/Linux)
  • Folding -> Collapse: ⌘ – (on macOS) / Ctrl+ – (on Windows/Linux)
  • Folding -> Expand All : ⇧ ⌘ + (on macOS) / Ctrl+Shift+ + (on Windows/Linux)
  • Folding -> Collapse All: ⇧ ⌘ + (on macOS) / Ctrl+Shift+ – (on Windows/Linux)
  • File Structure: ⌘ F12 (macOS) / Ctrl+F12 (Windows/Linux) – Twice to expand list
  • Quick documentation: F1 (macOS) / Ctrl+Q (Windows/Linux)
  • Toggle Rendered View:  ^ ⌥ Q (macOS) / Ctrl+Alt+Q (Windows/Linux)

Version Control support (Git)

  • Commit: ⌘ 0 (macOS) / Alt+0 (Windows/Linux)
  • Jump to last tool window: F12
  • Show diff: ⌘ D (macOS) / Ctrl+D (Windows/Linux)
  • Commit Anyway and Push: ⌥ ⌘ K (on macOS) / Ctrl+Alt+K (on Windows/Linux)
  • Git tool window: ⌘9 (on macOS) / Alt+9 (on Windows/Linux)
  • Terminal: ⌥ F12 (on macOS) / Alt+F12 (on Windows/Linux)
  • Git integration

Language and technology support

Integrated tools support

Contributing to open source software; creating a pull request

In this tutorial, we are going to take a look at contributing to Open Source Software, specifically how to do a pull request (PR). We will look at forking and cloning the project, making the changes, committing and pushing these changes, creating the pull request, the review and hopefully merge of your PR. The same process may apply when making contributions to a project at work that you don’t own. In this example, the project is on GitHub. Other Git code repositories may use a similar process.

There are many reasons to contribute to open source projects, and different ways to find an issue to work on, from fixing a bug that is bothering you, to simply wanting to help out, or even just to gain more experience and learn something new. If you’re fixing something that is currently bothering you, you will have a specific issue and project to work on. If not, you could consider contributing to a project you like to use, or finding an issue that is suitable for someone new to contributing to open source and/or the project. There are also many different things you can contribute. Code is one, but projects also need testing and other things. For more information on what you can contribute and how to find something to contribute, please have a look at this video.

For this blog post, let’s assume we’ve found a project we want to work on, and an issue we want to fix.

Getting the project

When making your first contribution, you won’t have access to push to the open source project directly. So, the first thing we will need to do is fork this project to our own profile. This means we create a copy of the original project on our profile.

Fork project

Fork

We then need to clone this project to our local machine. We see that we have several options to get the code. Let’s use HTTPS as that can be the simplest option. When we click the clipboard icon, the URL will be copied to our clipboard.

Clone

Copied

When we open IntelliJ IDEA and don’t already have a project open, we’ll see the Welcome screen. Here we have the option to Get from VCS (version control system).

Welcome screen

When we click the button, the Get from Version Control dialog opens. We can paste the URL we just copied. We can select where we want to store this project on our computer; let’s stick with the default. When we select Clone, IntelliJ IDEA will clone the GitHub repository to the selected directory.

Clone project

If we already have a project open, we can open the Get from Version Control dialog by going to File > New > Project from version control.

New Project from version control menu

IntelliJ IDEA will open the project on our machine.

Making and committing our changes

Before making any changes, we’ll want to make sure that we can build the project. Hopefully, how to build the project will be described in the README, as it is for this example. Let’s open the terminal and build the project as described. In this example, we need Docker, which is already installed and running.

Build the project

Now that we know we can build the project, we can start making changes. First, we need to look for the right place to make the change. We might navigate the project in the Project tool window (⌘1 on macOS, or Alt+1 on Windows/Linux), or look for a specific file or code snippet using Find in Files (⌘⇧F on macOS, or Ctrl+Shift+F on Windows/Linux).

Project tool window

Find in files

We might want to create a specific branch for our changes.

Once we are done making our changes and the project still builds, we can commit our changes (⌘K on macOS, or Ctrl+K on Windows/Linux). We can check our changes in the Commit tool window (⌘1 on macOS, or Alt+1 on Windows/Linux) to see if these are the right files and use Show Diff (⌘D on macOS, or Ctrl+D on Windows/Linux) to see if the changes are correct.

Commit changes

Check the differences

If we don’t have access to the original project, we need to push our code to our fork.

Push

Creating the pull request

Once we are happy with our changes, we can create a pull request.

We go back to our GitHub profile and create a pull request from there. After we have pushed our changes, we can see that our fork is 1 commit ahead. We can start creating our pull request by clicking Contribute.

Contribute

We need to provide a title and description for our pull request. Make sure the title is a good description of the changes you want to contribute. If your PR fixes an issue, you can add “fixed #x” (where x is the issue number) to the title; this will automatically close the linked issue when the PR is merged. Once you are happy with the title and description, click the button Create pull request to open your pull request.

Open the pull request

Create pull request

Negotiating the review process

Now the waiting starts. On an active project, hopefully your PR will be reviewed soon. Your PR might get comments from reviewers that you need to fix. For complex changes, this might take several iterations. For smaller changes, hopefully it won’t. Before doing a lot of work on an issue you might want to check that your contribution is wanted and your solution is what they are looking for. Don’t be discouraged by review comments. Keep in mind that the maintainers will have to maintain your solution in the future and they want to make sure that it fits their project.

As you can see, reviewers can comment on your PR, approve the PR or request changes which must be addressed before merging. A project might have other checks set up that need to pass before merging. You might want to check that these checks pass and that there are no conflicts with the main branch.

Review

Checks

Summary and shortcuts

In this blog post, we’ve seen how to do an open source pull request. For more information on what you can contribute and how to find something to contribute, please have a look at this video.

IntelliJ IDEA Shortcuts Used

Here are the IntelliJ IDEA shortcuts that we used.

Name macOS Shortcut Windows / Linux Shortcut
Open / Close Project Tool Window ⌘1 Alt+1
Find in Files ⌘⇧F Ctrl+Shift+F
Commit changes ⌘K Ctrl+K
Commit tool window ⌘1 Alt+1
Show diff ⌘D Ctrl+D

Related Links

Cherry-pick: Move a commit to a different branch

There are several reasons why you might want to move a commit to a different branch. Let’s take a look at some of them.

Committed to the wrong branch

You’re working on a new feature, but an urgent bug came in. You fixed the bug and committed the fix, but oops… you forgot to create a new branch for the bugfix! Now this bugfix is on the wrong branch. How do we fix this?

IntelliJ IDEA Git log window showing a bugfix commit on a new-feature branch
Bugfix commit is on the wrong branch

Use cherry-pick to move the commit

I could redo the work, especially if it’s a small change, but … I don’t want to! Luckily, there is a better way.

We only want to move this one commit from the feature branch to a separate bugfix branch. We can do this using Git’s “cherry pick” option from IntelliJ IDEA.

First, let’s go back to main and create the bugfix branch that we should have created in the first place.

IntelliJ IDEA Git log window showing that the main branch is checked out.
Back on the main branch

Once we’re back on the main branch, we can create a new branch named “bugfix”.

Create a new Bugfix branch

On the newly created branch, we can select the bugfix commit from the other branch and select Cherry-Pick to apply that commit to our current branch.

IntelliJ IDEA Git log with the bugfix commit selected and the context menu with option cherry-pick selected.
Cherry Pick the selected commit from the context menu

Cherry-pick from the command line

Yes, we can do this from the command line too, but there’s no cute cherry icon on the command line. To cherry-pick a commit from the command line, we can use the command git cherry-pick <commit hash>. We would need to find the commit hash of the commit we want to cherry-pick, which we can find for example in the Commit Details pane in the Git log window (see below).

IntelliJ IDEA with the terminal open and the command "git cherry-pick 51e33e5a".
Cherry-pick on the command line

As we can see, the bugfix commit is now on the bugfix branch.

IntelliJ IDEA Git log showing the Bugfix commit on the bugfix branch and a message "Cherry-pick successful".
Cherry-pick successful

Other use cases for cherry-picking

Cherry picking can be useful in other situations too. Let’s take a look at some other use cases for cherry-picking.

Backporting a fix

We can also use cherry-picking to backport a fix to a previous release branch. For example, let’s move our bugfix commit also to the v1-release.

To do so, first we need to look for the last release (v1). We can search for a specific commit hash, branch or tag name in the Git log (⌘ F on Mac or Ctrl+F on Windows/Linux).

IntelliJ IDEA Git log showing a pop-up to Enter hash or branch/tag name.
Search Git log for Hash/Branch/Tag

We can also filter commits in the commit log by branch, user, date or path. 

IntelliJ IDEA Git log showing the option to filter by branch, user, date or path
Filter by branch, user, date or path

To see which commits have not yet been applied to this branch, we can click View Options and select Highlight | Not Cherry-Picked Commits. We’ll compare with the new-feature branch. Commits that have already been applied to the current branch are greyed out.

IntelliJ IDEA Git log showing a context menu with Highlights | Not Cherry-Picked Commits selected
Select the Not Cherry-Picked Commits

When we select a commit, we can look at the information in the Commit Details area (at the bottom right) to make sure these are the changes we want to transfer to this branch. In the Commit Details area we can see which files were changed in a particular commit. We can right-click a file and select Show Diff from the context menu to open the changes that were made to that file.

IntelliJ IDEA Git log showing the details of a commit on the right.
Look at the details of a commit

If we are sure these are the changes we want, we can cherry-pick them to the previous release branch.

Cherry pick part of a commit

In the Commit details pane on the right, select the files containing the changes you want to apply to the target branch, right-click and select Cherry-Pick Selected Changes from the context menu.

IntelliJ IDEA Git log showing a context-menu with the option Cherry-Pick Selected Changes selected
Cherry-Pick Selected Changes

The cherry picked changes are transferred to the change list and we can commit them from there. 

IntelliJ IDEA Commit window with Changes selected to be committed.
Partial commit added to the Change List to be committed

Dealing with conflicts

So far, cherry picking went smoothly because there are no conflicting changes. What if there are conflicts?!

When we cherry-pick a commit that has conflicts with our current branch, the Merge Conflicts dialog opens.

IntelliJ IDEA Merge Conflict dialog with the options to Accept Yours, Accept Theirs or Merge
Merge Conflict

We can resolve the merge conflicts here. We want to keep some changes, and reject others.

IntelliJ IDEA Merge Conflict dialog with conflicts highlighted
Merge Conflicts dialog
IntelliJ IDEA Merge Conflict dialog with conflicts resolved and the option to Save changes and finish merging
Merge conflicts have been resolved

If you’re not able to resolve the merge conflicts, you can also abort the cherry pick.

IntelliJ IDEA Git log showing a notification that the Cherry-pick was performed with conflicts and a popup to Abort the Cherry-Pick
Abort Cherry-pick

Continue after cherry-picking

Once we’re done cherry-picking, we can go back to the “feature” branch. Since we haven’t pushed these changes yet, we can remove the commit from the feature branch by selecting Drop commit. 

IntelliJ IDEA Git log with a commit selected and a context-menu with the option to Drop Commit
Drop Commit

What if you have pushed the changes already? Then you might want to revert it on this branch instead. Right-click the commit and from the context menu select Revert Commit.

IntelliJ IDEA Git log with a commit selected and a context-menu with the option to Revert Commit
Revert Commit

Now we can continue working on the new feature!

Conclusion

Moving a commit to a different branch. Not nearly as scary as it sounds! Let the IDE help to turn this into a quick, low-stress task.

Cherry pick a commit to a different branch in any JetBrains IDE

Links

Cherry pick a commit to a different branch

Oops, you committed your code to the wrong branch… You could redo the work, but you don’t want to! Luckily, the IDE can help you move your commit to a different branch. Use Git’s cherry-pick option from your IDE to move changes over to a different branch in a quick, low-stress way.

Cherry pick a commit to a different branch

Links