Organizing code with repos

Organizing code with repos#

In this section we will learn how to store our code on a repository primarily for keeping a diary about our work and sharing it. We will use GitHub.

repository

(in context of version control systems) a data structure that stores metadata for a set of files or directory structure. The main purpose of a repository is to store a set of files, as well as the history of changes made to those files.

version control

the software engineering practice of controlling, organizing, and tracking different versions in history of computer files; primarily source code text files, but generally any type of file.

Keeping a history of changes is helpful if we or someone else who also work in the project would like to understand changes in the project which is useful for collaboration. Keeping a history helps also to roll changes back if something does not work as intended.

Keeping projects in a repository is also helpful to collaborate and share code. You will use it later to share or submit your projects. You probably already downloaded something from the code forges GitHub or GitLab, on which most of the open source in the world is organized.

code forge

a web interface to a version control system

Installing Git#

We will setup Git in VS Code now.

  1. On the activity bar, click on Source Control.

  2. Install Git using the package manager:

    • Windows: winget install git.git

    • MacOS: brew install git

  3. On the editor Source Control window click on reload. The editor’s window will refresh and you will see other button on the Source Control window.

Initialization#

  1. Click on Initialize Repository. Changes window will show up, which should show you the three files:

    1. main.c

    2. a.exe

    3. tasks.json

    ../_images/git-untracked-added.png

    Fig. 1 Two added files (A) and one Untracked (U) file on the Changes window. The mouse pointer hovers on a.exe, but the pointer cannot be seen.#

    You will see U beside these files. U stands for untracked, which means these files are not tracked by the repository. Typically only source files are tracked in a repository, so we will only track main.c and tasks.json.

  2. To track these two files, hover on the filenames and click on the symbol on each. You will an A on the right of the files, which stands for added.

  3. Click on the Message prompt to write a commit message. When we use repositories we make our changes in commits.

    Ideally each commit should be a set of changes that adds one or many describable feature like improved user name handling or added robot program. The advantage is that the programmer can roll back changes if these features led to problems later. Sometimes people don’t want to put so much structuring work and use a repository as a diary and commit code at the end of the day, which is not a good practice in a professional environment.

    This is our first commit, so use the message initial.

  4. Click on Commit. You will see your first commit on the Graph window below.

changeset

list of differences between two successive versions in a repository

commit

the operation of committing such a changeset to the repository

Pushing code to a code forge#

The repository we used is until now local to our computer. To share our work, we must push our changes for a code forge like GitHub.

  1. On the Graph window, click on Publish Branch. A confirmation window will pop up to sign in using GitHub.

  2. Allow. A new window will pop up with authentication code.

  3. Copy & Continue to GitHub. A new confirmation window will pop up.

  4. Open. A browser window will pop up.

    Create (if you don’t have an account) and login to GitHub. You will be forwarded to the Device Activation page on GitHub.

  5. Paste your code. Authorize Visual Studio Code should come up.

    If the code is not available anymore, go back to the editor and start from step 1.

  6. Click on Authorize Visual-Studio-Code. You should see Congratulations …

  7. You can close the browser.

  8. A window will pop up with two options — whether you want to publish privately or publicly. You will use this repository to submit your work, so: select Publish to GitHub public repository ...

  9. You will get the notification Successfully published ....

    If you missed the notification, click on the (bell) icon in the below right corner of the editor.

  10. On the notification, click on Open on GitHub. A confirmation window will pop up.

  11. Click on Open. Your browser will pop up and show you your repository on the GitHub.

    Use this address to share your work in general. If you want to submit for an assignment, use another address. This will be shown later below.

Adding a README on GitHub#

  1. When we share work, we should also write some information about what the code is about in the README file.

    On the repository page on GitHub, click on Add a README.

  2. You can write something along the lines of:

    # Hello

An example program for my C programming course.

    Click on Preview to see how this text will be rendered.

  3. Commit changes.... Commit changes window will pop up.

  4. You can leave the automatic commit message. Commit changes. You will be forwarded to your main repository page.

Synchronizing repositories on the code forge and local computer#

  1. We made changes on GitHub, which are not visible on the repository on our computer. Remember that repositories are also used for collaboration, so if you are working in group, a code forge can also be used to synchronize the work between collaborators.

  2. You can close the browser.

  3. On the editor, you should have a notification about: Would you like ... to periodically run "git fetch"?.

    This setting (git.autofetch in settings) will automatically get the project updates from the code forge. This is useful when we collaborate or edit our code on different platforms, e.g., local computer, web-based IDE or on the code forge like we did. We will turn this feature on later, when you will write code in a group project, because manually getting the changes is often more efficient when working solo. So click No.

  4. On the Graph window (below Changes), click on Pull . On the same window, the commit that you have done should pop up and your files will be updated.

Contents