Working with source control
Importing an Mbed program from a Git hosting service to Mbed Studio clones it as a Git repository. Similarly, importing an Mbed program from os.mbed.com clones it as a Mercurial repository. If you create a blank program, you can set it up as a source-controlled repository from the command-line or with local tools. All Mbed programs are added to Mbed Programs in your home directory.
You can manage changes to Git or Mercurial repositories from Mbed Studio as well as with the command-line or other tools. However there are some restrictions detailed below.
When using Git repositories: On Windows, you must have Git version 2.11 or later installed to be able to work with private repositories.
When using Mercurial repositories:
- Mbed Studio only supports the management of public Mercurial repositories. For private Mercurial repositories, use the command-line or other tools.
- Mbed Studio does not support committing or pushing to Mercurial repositories. To commit or push to a Mercurial repository, use the command-line or other tools.
Creating a branch from the master branch or switching branches
Branching allows you to branch out from the original code base and isolate your work from others. If the active program is a Git or Mercurial repository, you can see which branch you are working on from the status bar (by default, you are on the master branch). To create a new local branch (that is to say branch from the master) or switch to a different branch of a repository, click the current branch in the status bar. Note that new branches cannot be created in Mercurial repositories. Current branch in the status bar. The available branches are listed at the top of the window. Select Create new branch... and enter a name to create a new branch. The name of the new branch should not contain spaces. Create a new branch. To switch to a different branch, search for and select an existing branch in the list.
Applying the latest changes to your local repository
When working on a remote repository, several options are available to keep up to date with others' changes to the repository. Click the ... (More...) button to see the options.
- Fetch...: Use this option to obtain the remote changes but not merge them into your current local branch. Click Fetch... and select the repository from which you want to retrieve the latest changes in the list at the top of the window.
- Pull: Use this option to apply the latest changes from the default remote repository to your local repository. Changes from the remote branch are automatically merged into your local branch. It is highly recommended to do a pull only with a clean working copy. In other words, you should not have any uncommitted local changes before you pull.
- Pull from...: This option works the same way as Pull but you can select the remote repository from which to get the changes.
Committing and pushing changes
When you have saved changes to one or more program files or imported or updated an Mbed library, you may want to stage and commit the changes. A commit records the changes done to your local repository. After doing a commit, you can push your changes to the remote repository to share your changes with others.
Committing changes to your local repository
To commit changes:
- Select the branch you want to commit to.
- Open the Git pane. The new and changed files are listed below "CHANGES".
- Move your mouse over the file you want to commit and click + to stage your changes. The file is listed below "STAGED CHANGES".
- Once you have selected all the files you want to include in the commit, enter a commit message in the Commit message text field and then click Commit. The changes are committed and the commit can be seen in the Git history pane.
Tip: To view the changes that have been made to a file, double-click the file name. The changes open in a new tab. You are presented with what was available in the file before the changes (in red) along with what has changed (in green). You can open the file by clicking the Open File icon in the top-right corner of the window or go back to the changes by clicking the Open Changes icon. There is also an Open File option available when you hover over the file name.
If you need to add new or updated files to your previous commit, or edit or add comments to the previous commit, click the Amend button. This allows you to modify the most recent commit in the branch you are working on. After clicking Amend, you can make further changes, stage or unstage files as appropriate and commit again. That commit will replace the amended commit. You can click the Amend button again, as many times as needed, to step back through the commits. If you click the Amend button multiple times and re-commit then all the amended commits will be combined together into a single commit. Be careful when clicking Amend because you cannot cancel this action. You can only manually re-commit the changes as new commits. This option is also available if you click the ... (More...) button and select Commit (Amend).
The Add signed-off by button or Commit (Signed Off) option when you click the ... (More...) button allow you to tag your commit and add comments, a signature, the date and your email. For some projects, this is a requirement for all contributions submitted as pull requests.
Pushing changes to the remote repository
Once you have done a commit, you can push your changes to the remote repository.
To push changes:
- Click the ... (More...) button and select Push. A field appears at the top of the window.
- Enter your Username and press Enter.
- Enter your password and press Enter.
The Push to... option works the same way as Push but you can select the remote repository to which you want to push your changes. Alternatively, you can also use the Publish Changes option on the left-hand side of the status bar to push your changes. Publish Changes option.
When doing a push you have to make sure that your local repository is synchronized with the remote repository to avoid conflicts. The merge option allows you to grab the latest changes from the remote repository before you can push.
To merge your local changes and changes done on the remote repository:
- Open the Git pane.
- Click the ... (More...) button and select Merge....
- From the drop-down list at the top of the window, select the branch that you want to merge into the current branch. If you imported the program from os.mbed.com or a Git hosting service, you can merge remote branches into the current branch.
Note: You cannot delete Git branches from Mbed Studio. Use the command-line or other tools.
Other synchronization options
The Synchronize Changes option on the left-hand side of the status bar shows you how many changes have been pushed to the remote repository by other users and how many commits you have done on your local repository. Synchronize Changes option. Click the Synchronize Changes option to display the synchronization options available.
- Pull and push commits from and to 'origin/master': Apply the latest changes from the default remote repository to your local repository by doing a pull, then push your changes to the remote repository.
- Fetch, rebase and push commits from and to 'origin/master': Fetch the remote changes without merging them into your current local branch, rebase and then push your changes to the remote repository. The rebase option compresses all the changes into a single "patch", then integrates the patch onto the master branch.
- Force push commits to 'origin/master': Do a force push to overwrite the remote branch with your local branch, regardless of the status of that remote branch.
Statuses are displayed to the right of each file to indicate changes. "A": Added "M": Modified "D": Deleted "U": Unstaged
"R" and "W" are related to libraries. See Including libraries.
Git History pane
The Git History pane shows your latest commits. From this pane, you can view the changes that have been made for a given commit when you click on the eye icon. View the changes for a given commit. You can also see the details of the changes on a given file when you double-click on the file. The changes open in a new tab. View the changes for a given file.