Source Control

Prerequisites

If you are using Visual Studio:

  • Git
    • Execute “git config --global init.defaultBranch main” in a Terminal (run as Administrator) to set the default branch name.
    • Make sure Visual Studio has the correct user name and email address (Tools -> Options → Source Control → Git Global Settings) and enter the following:

Connecting GitHub with SSH

  1. Open Git Bash (run as Administrator).
  2. Enter “ssh-keygen -t rsa -C "someone@somewhere.com"” (where the email address matches the one above) and follow through the instructions.
  3. Then run "ssh -T git@github.com".
  4. Go to GitHub SSH Keys (logged in with your collaborator account) and create a new SSH key.
    • The public key can be found at c:\users\{user-name}\.ssh\id_rsa.pub.

Publishing a New Repository

 The following instructions will show you how to publish your changes to GitHub using either using Visual Studio or the Terminal.

Using Visual Studio

  1. Create a GitHub repository under “Git Changes” by clicking “Create Git Repository...”.
    • Enter the repository name e.g. my-test-project.
    • Select “kontrolit” for the Owner.
    • Select “Private Repository”.
  2. Click “Create and Push”.
  3. Delete the “.gitattributes” file (in the root of the project) that Visual Studio creates and commit the change to GitHub.

Using the Terminal

First you should create your repository on the GitHub website.

Open the Terminal at the project root and execute the following (replacing the repository name accordingly):

git init
git add .
git remote add origin git@github.com:kontrolit/{repository-name}.git
git commit -m "Initial version"
git push origin main

Opening an Existing Repository

The process of opening an existing repository is known as cloning.

Using Visual Studio

  1. Open Visual Studio.
  2. Select “Clone a repository”.
    • Enter the repository location e.g. “git@github.com:kontrolit/{repository-name}.git”.
    • Select where you would like the store the project e.g. “C:\Users\{user-name}\Projects\{repository-name}”.
  3. Click “Clone”.

Note: You should execute “npm install” from the root of the project to install the Node.js packages.

Using the Terminal

Open the Terminal at the projects folder (e.g. “C:\Users\{user-name}\Projects”) and execute the following (replacing the repository name accordingly):

git clone git@github.com:kontrolit/{repository-name}.git

GitHub Permissions

Whenever a repository is added, the member who added the repository is automatically assigned as an administrator. Administrators have permission to do as they please to the repository.

To grant access for other members you'll need to add them under “Manage access” in the settings for the repository. Make sure you add the team they are assigned e.g. Devs, rather than the individual person.

Enabling Branch Restrictions

On certain repositories you may wish to restrict who can merge into a particular branch. To restrict who can merge in to the “main” branch, follow the instructions below:

  1. On GitHub, navigate to the main page of the repository.
  2. Under your repository name, click “Settings”.
  3. In the left menu, click “Branches”.
  4. Next to "Branch protection rules", click “Add rule”.
  5. Fill out the following information:
    • Under "Branch name pattern", type the branch name or pattern you want to protect, e.g. “main”.
    • Optionally, select Include administrators. This enforces all configured restrictions for repository administrators.
    • Under "Protect matching branches", select “Restrict who can push to matching branches”.
    • Search for and select the people, teams, or apps who will have permission to push to the protected branch. Leave blank for none.
  6. Click “Create”.

Creating a Pull Request

If you do not have permission to modify the “main” branch then you'll need to submit a pull request to have your changes approved. The following instructions show you how to submit a new pull request using Visual Studio. First we need to create a branch for changes:

  1. Click on “Team Explorer”.
  2. Click the “Home” icon and select “Branches”.
  3. Now click “New Branch”, enter a name and click “Create Branch”.

You should now be in your new branch (see bottom right for the current branch name). Make the desired changes and commit them. There is no need to sync the changes as this will be synced once we create the pull request below:

  1. Click on “Team Explorer”.
  2. Click the “Home” icon and select “Pull Requests” (the one on the right).
  3. Now click “Create New”, fill out the information and submit it.

Your pull request will now be submitted to GitHub for someone to review.

Merging a Pull Request

Click here to watch a video which shows how to do this. Alternatively you can follow the following instructions:

  1. In Visual Studio, click on “Team Explorer”.
  2. Click the “Home” icon and select “Pull Requests” (the one on the right).
  3. Select the pull request you are interested in. This will show a list of the files which have been changed.
  4. Click “Checkout to {pull-request-name}” which will create a new branch, pull the changes from the pull request and checkout the new branch (see bottom right for the current branch name).

At this stage you are free to review and modify the changes. Once you are happy you then commit the changes for your branch. Note that you do not have to sync them. Next we have to merge the changes:

  1. Click on “Team Explorer”.
  2. Click the “Home” icon and select “Branches”.
  3. Right click the “main” branch select “Checkout”.
  4. Now right click the branch we would like to merge and select “Merge From…”.
  5. Finally click “Merge” and sync your changes to push them to GitHub.

Notice this will automatically close the pull request on GitHub. You can now go ahead and delete the branch, both locally and online.