Stand-up (Part 5): Using git source control in Monaco

This is the fifth blog post in our series around developing a node.js application using Monaco. In this part we take a look at the Git tooling support Monaco provides. We assume that you are familiar with the basic concepts of Git. If not, there is a lot of useful documentation and tutorials around Git available on other sites, like here or here.

In the previous chapters of this series you have learned all the basic steps to setup a node.js project using Monaco. There is a lot more to explain around Monaco and how to use it for the best development experience. You can check out our Channel9 videos on further topics like Editor Tips and Tricks and Navigating the environment if you are interested.

If you are interested in previous parts of this series, please use the links below:

1. Part 1: Introduction
2. Part 2: How to configure the workspace for IntelliSense
3. Part 3: Using Mocha for server side unit testing
4. Part 4: How to debug node.js applications on Azure
5. Part 5: How to connect to an existing workspace using source control
6. Part 6: Best practices leveraging development and production sites

Pushing an existing workspace to a new repository

There are two typical scenarios where you want to use source control for your changes: On the one hand you might have existing source code that you want to push into a new Git repository and on the other hand you might have an existing repository with code that you want to pull into Monaco. If you have followed this series all the way from Part 1, your workspace will be filled with some files already. In this paragraph you will learn how to push these changes to a Git repository.

Monaco provides Git integration both from the console (Ctrl+Shift+C) through the Git command as well as the Git view (Ctrl+Shift+G). If you open this view, you can easily initialize an empty repository, clone from an existing one or connect to a Visual Studio Online repository.

In our case, we want to initialize a Git repository with all the files of our workspace. After you have clicked on the "Initialize git repository" button in the Git view, you can create your initial commit. Simply type a commit message into the input box on the top of the Git view and hit Enter. You can also use the console (Ctrl+Shift+C) for this purpose. All Git commands are available to you from there by providing the native Git command.

Since this is the first time we are using Git, Monaco will now ask you to provide some additional information about you. 

You name and e-mail will be used for Git to relate the changes you do to your identity. When someone else pulls your changes, these changes will show up with your name and e-mail. Type in your identity by uncommenting the related lines in the configuration file:

Close this editor with Ctrl+S to save it and enter your commit message again followed by Enter. This saves the git configuration file outside of wwwroot, but still inside the website. As a consequence you will have to enter the identity info again when setting up git for another web site. This is something we plan to improve in the future.

Now that we have our first commit created, we need to let Monaco know where to push it. Monaco works with any Git repository, so it is your choice where you want to push your changes to. You can create a project with Git repository for free at CodePlex or GitHub. 

Open the Monaco console (Ctrl+Shift+C) and type the following commands to add your Git repository as a remote and push your changes:

git remote add origin <Git Repository URL>

git push origin master

 In case your repository is protected with credentials, Monaco will ask for them and also provide an option to remember the credentials for further use. We are currently not storing the credentials across multiple web sites, so you might see the same dialog showing up from another web site.

Pulling a workspace from an existing repository 

In this scenario we assume that you start with a fresh web site without local changes. The standup application is hosted in a Git repository at CodePlex but any git URL will work. If your git repository is hosted in VSOnline, then you can connect to VSOnline and pick from the list of repositories without having to look up the Git URL.

We can quickly pull the sources into Monaco using Git. From the Git view (Ctrl+Shift+G) type https://git01.codeplex.com/monacostandup into the repository URL field and press “Clone from a git URL”. You will see the console running the clone operation and the explorer filling with the contents of the repository. In case your repository is protected by credentials, Monaco will ask you to type username and password.

Now that the entire standup application source code is pulled into your workspace you can actually run the application from your web site. Just use the run action from the left hand side or press Ctrl+F5 and see it live!

A tour around Monaco Git tooling features

Once the clone operation has finished you will notice some more controls showing up in the navigation bar to the top. These controls provide you with an up to date indication of your current git status. This includes an indication of

• the branch you are working on
• changes to the working tree ("dirty changes") and index 
• incoming and outgoing changes

The first dropdown gives you an indication of the branch you are working on. It will also indicate if you have dirty changes on the working tree or the index by adding a '*' and '+' decoration after the branch name. In case you are in a state where you have to merge changes, an exclamation mark is added to indicate this state. From the dropdown you can create new branches and quickly switch between branches.

The second dropdown provides you with a synchronize action that will pull incoming changes and push your commits to the repository. It will also give you an indication of incoming changes from the server and outgoing commits you have not yet pushed.

Monaco will periodically check for incoming changes in the background. You don't have to configure anything to be informed when new changes are ready to be pulled into the workspace. You will see the same indicator from the Monaco console. Any git operation will update the console prompt directly so that you are always informed about the state of your repository.

Monaco makes it easy to track changes and work with them. In the next paragraph we will take a tour on making a change and committing it to the repository. 

Tracking changes with Monaco

Now that our workspace is under control of Git, changes you make to files are tracked and reported. You will be able to distinguish added, changed and deleted files from the Git view (Ctrl+Shift+G). In the example below you see app.js was modified, newfile.txt added and the routes folder deleted:

You will also notice a little decoration on top of the Git icon on the left hand side of the workbench. This decoration indicates the number of changes that have not yet been committed. In our example, four changes are waiting to be committed.

Let's make some simple modifications to a file in the workspace to get a feeling for change indication in Monaco. In the screenshot below you can see changes to the app.js file. Since the original revision of the file is known to Monaco through Git, the editor can indicate additions, changes or deletions to lines in the file. This makes it easy to track changes in individual files:

Before committing changes back to the repository you typically want to review all changes. Each entry in the git view can be clicked to review the changes that were made. Click on the file you changed to bring up Monaco's diff editor. This editor will give you an indication of lines changed from the revision that was pulled from the Git repository. The change indication goes down to the word level making it easy for you to track smaller changes to individual lines.

The right hand side of the diff editor is a fully editable editor. You can continue to make changes here as needed.

Once all changes have been reviewed, you can type in a commit message into the Git view and press Enter to create the commit. You will notice that the change indicator in the navigation bar to the top now shows you the number of outgoing commits. Just click on the "synchronize" action to push your changes back to the repository.