Get Help for Octopus


Octopus is a git client for the mac. It helps you to work with git repositories and to deal with the files under version control. If you need help concerning git itself and/or how to install git, please visit

Getting started

Open Octopus

When opening octopus, it will ask you to choose the correct git-binary or to locate it if it was not found. Alternatively it offers you to download the latest copy to install.

Open local repository

To open an existing local repository, either a) drag the repository on the sidebar or b) choose File -> Open local repository from the menu. After locating the repository, Octopus will import all settings and the repository. If you have more than one repository you may drag the repository into correct order for easier work.

Open remote repository

To clone a remote repository choose File -> Clone remote repository, paste the correct remote url and choose a location on your computer. Octopus will be smart enough to choose the correct name for you, alternatively you may choose another one.

Creating new repository

To create a new repository choose File -> Create empty repository and choose a location on your computer.

Working with Octopus

Where do I find my repositories?

All repositories known to octopus will be displayed in the left pane (Repository List) along with some information. The icon indicates if either the repository is only local available or if it has a corresponding remote repository. The number on the right only appears if there are unpushed commits and shows the amount of commits.

Where do I find commits of the past time?

Choosing a repository from the repository list will open all recent commits in the repositories timeline. Default limit of shown commits is 60 commits, but you might change this in the preferences section. Please note: increasing the amount of commits can significantly slow down octopus. As of now, octopus does not support graphical timelines, which will change in the coming releases.

Where are my Branches?

To open the Branches View either choose View -> Branches or simply click on the arrow on the history bar. This view allows you to a) checkout remote branches, b) switch branches, c) push local branches to remote and d) to merge branches. Branches can as well be removed and tags can be added with their corresponding icons.

How do I merge my Branches?

Merging branches can be done easily by dragging and dropping one branch on the other. Please note that the branches workspace should be clean in order to do this.

How do I checkout Branches?

Remote branches can be dragged and dropped into the other section e.g. to checkout remote branch locally drag the branch name over to the local branches section. Please be aware to not drag it on a branch as this will initiate a merge. To use the freshly pulled branch, simply click on the name of the branch, octopus will immediately change branches.

What's the right pane (Detail View) all about?

All information about a certain commit is displayed in the detail view. All files are shown with their changes (except for images) during this commit. To display older commits including this file, choose File History next to each file.

What the ... is Cherry-Picking?

Octopus includes a functionality to cherry-pick a certain commit to another branch, meaning it transfers only this commit to another branch. To use this, click on the cherry-pick Icon which will bring up a dialogue. Available Branches will be shown in a select option, if no branches are displayed, Octopus cannot find any local branches. Be sure to checkout remote branches you want to pick this commit to.

I want to edit a file directly in an editor!

For easier workflow Octopus has a integrated functionality to open committed files in an external editor. The preferred editor can be chosen in the preferences.

Where do I stage my files?

To stage new and untracked files or to simply stage changes to a file known to git, use the staging view. It allows you to stage and unstage files using drag and drop functionality. To stage/unstage all files, use the buttons next to the staging areas.

What is stashing and how do I use it?

Stashing is a great way quit what you’re working on and come back to it later. This might be helpful when dealing with several branches and having to do a hot-fix for another branch. To stash, stage all files you want to stash as git can only stash known files and use the Stash Changes command. To unstash, use the corresponding entry in the stash list. Stash lists can as well be cleared with the Clear Stashes command.

How to use the Checkout / Rebase / Hard reset functionality?

Note: Handle with care! Please only use these options if you know what you're doing. These options allow you to reset your repository or single files to a previous state. To reset a single file, choose the file and select Checkout. To reset a complete commit, choose Hard reset to commitid. To rebase to a previous commit choose the commit from the history list and choose the Rebase to commit_id option. In case git will find some errors, octopus will open a window for you to check. For further informations on these commands please visit

What does the eye button (QuickLook) do?

Quick Look works as known in the OS X Finder, it allows you to quickly have a look at a changed file and to review changes before committing.

How do I commit my changes?

The commit command will open a message box and will then commit all staged changes that are available to git.

How do I push to remote repositories?

Pushing to remote is as easy as clicking the button which opens over the history list. If uncommitted changes are available to the repository, it will be shown by an indicator in the repository view. Please note that this option is only available if the repository has a corresponding remote.

How do I pull from remote?

Use the pull icon on the lower bar to pull changes from a remote repository. Please note that this option only works if the repository has a corresponding remote.

I want searching functionality!

Want to search for a certain string in the commit messages? Use the search field to narrow results. Pressing CMD+F when a diff window is open will search in the diff window as well.

I like to clean everything, even my repository!

Cleaning the repository will remove all untracked files that are not in version control by git. Please handle with care as it removes every single file which is not tracked yet.

How to edit the repositorys configuration and .gitignore?

The Edit repository command gives you full flexibility in editing your .gitignore and repository configuration. Please use the latter one with care as it contains all information about repository.

It's done. How do I remove the repository?

Tired of working on the same job or finished your work? Choose Remove repository to safely remove it from your hard drive or use the option to only remove the reference within octopus.