Version Control

Version control system (VCS) provides several benefits to your development cycle by:

  • Keeping track of software changes with the use of commit operations.
  • Providing a convenient way to revert to a previous commit.
  • Creating an environment for your team members to work on the same project.
  • Supplying an additional backup of your code.

Some time ago, GitHub began providing private repositories for small teams for free, making it a great system for hosting version control for your startup. As your team grows, their offerings remain reasonably priced.

Initializing a Local Repository

Using Terminal, browse to the new project.

cd ~/play-scala-web-app/play-scala-web-app

Create an empty local Git repository.

git init

Creating a GitHub Account

Browse to https://github.com and sign up.

Verify your account by solving the puzzle.

Click Next: Select a plan.

Answer the questionnaire and click Complete setup. You can also skip answering the questionnaire.

GitHub will now send you a verification email. Open the email from GitHub and click Verify email address.

Once your email has been verified, click Create a repository.

Enter repository name, description, select Private. Leave Initialize this repository with a README unchecked to avoid merge conflicts.

Click Create repository.

Close the browser window.

Setting Up Git Connection

Generating SSH Keys

The local Git application will use an SSH key to communicate with GitHub. SSH keys are safer than passwords.

Open Terminal and generate a unique key for GitHub.

ssh-keygen -t rsa

For file name, enter /users/username/.ssh/github.com. Username is your username, for example: /users/john/.ssh/github.com.

Leave the passphrase empty.

The private/public key pair will be created in .ssh directory: github.com is your private key to remain on your machine and github.com.pub is the public key to be shared with GitHub.com.

Next, we’ll need to configure SSH to use the github.com key when connecting to GitHub.com.

Open SSH configuration.

nano ~/.ssh/config

Enter the following. Keep User as git.

host github.com
HostName github.com
IdentityFile ~/.ssh/github.com
User git

Adding SSH Public Key to GitHub

Using Terminal, read your public github key.

cat ~/.ssh/github.com.pub

Select the contents of the key and copy into the buffer with command+c.

Log in to your GitHub account: https://github.com.

Click on the user icon in the top right corner and select Settings.

Click on SSH and GPG keys from the menu on the left.

Click New SSH key.

Add the title of the new repository and paste the contents of the buffer into the Key field.

Click Add SSH key.

Close the browser.

Testing Git Connection

Using Terminal test the SSH connection to GitHub.

ssh -T git@github.com

Enter yes to confirm the connection.

Configuring Project

Remote Repository URL

Log into your GitHub.com account: https://github.com, and click on the repository name in the left panel.

Copy the SSH connection string from the Quick setup section. The string begins with git@github.com… For example, git@github.com:LineDrop/scala-play-web-app-guide.git.

Adding Remote Repository to the Project

Launch IntelliJ IDEA and open your project.

Click VCS on the top menu.

Point to Git and select Remotes.

Click + to add a new remote resource.

Keep the name as origin and past the remote repository URL.

Click OK. IntelliJ will verify the URL.

Click OK to close the Git Remotes box.

Initial Commit and Merge

Choosing Files for Version Control

The project directory contains quite a few files and directories. To avoid security issues, unnecessary merge complications and headaches for yourself and your team, only a few of those should be tracked by version control.

To view the project structure, expand the Project menu.

From LineDrop’s experience, we recommend adding the following to version control:

  • app directory. App directory contains the application logic.
  • logback.xml, messages and routes files in the conf directory. Do not track application.conf, it will include credentials not to be uploaded to a third party.
  • build.properties and plugins.sbt in the project directory. Do not track project/project/target and target directories; they are only used during the debugging process.
  • public directory. This directory contains application assets such as images, JavaScripts, css, et cetera.
  • .gitignore. This file lets Git know which directories and files not to track.
  • build.sbt. The build file includes versioning information and library dependencies required to run the application. This file along with build.properties and plugins.sbt in the project directory will allow another team member to easily clone and compile the project.
To summarize, only these items will be tracked by version control.
  • /app
  • /conf/logback.xml
  • /conf/messages
  • /conf/routes
  • /project/build.properties
  • /project/plugins.sbt
  • /public
  • /.gitignore
  • /build.sbt

Ctrl-click on each of the items above and select Git - Add to add to the version control. Items tracked by Git will be colored green.

Committing Changes

Commit changes by selecting VCS - Commit from the top menu.

Review the files and directories before committing. Please verify that application.conf and target directories are not selected.

Enter the commit message: This is the initial commit.

To save time, we usually unselect Perform code analysis and Check TODO.

...

Click Commit.

Enter Git Username and email.

Click Set and Commit.

Merging with Remote Repository

Once the files have been committed, we can synchronize our local repository with the remote repository (origin).

Select VCS - Git - Push from the top menu.

Click Push.

Log into your GitHub.com account: https://github.com, and click on the repository name in the left panel.

Verify that your files are now on the remote repository.

Creating the Development Branch

So far, our version control has been set to master branch. Before we get carried away with development, let’s create a new development branch and merge it with master.

From the top menu, select VCS - Git - Branches and click + New Branch.

Enter development for the branch name. Keep Checkout branch selected.

Click Create.

Now you are on the development branch. From this point on, all new development will be done on the development branch, with the master branch reserved for releases.

Update the remote repository by selecting VCS - Git - Push. Click Push.

Browse to your GitHub repository on https://github.com to verify that both branches are available.

Multiple Project Backups

To avoid losing your project due to unforeseen circumstances, we recommend that in addition to the local copy of your project on your machine and the copy stored on VCS, to save another copy on a separate network drive. The drive could be on premises or a remote location.


Next: Application Basics