Organizing code in a repo

Organizing code in a repo#

Now we will learn how to organize our code on a repository primarily for keeping a diary about our work and sharing it. First we will store them in a local repository and afterwards in a remote one.

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.

Why do we use repositories?#

Most programmers use repositories to organize their software projects, but should you – as a student in this course?

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 maybe already downloaded something from the code forges GitHub, GitLab, or Codeberg. GitHub is the most popular one and on which most of the open source projects in the world are organized. GitLab is popular among companies, because GitLab is open-source. Codeberg is European and is privacy-focused.

Last but not least, pushing your code to a forge will keep a backup of your project in the cloud.

forge

a web-based collaborative software platform for developing and sharing software applications

Installation#

Git is the most popular version control software. Before we can use git related functions in the editor, we have to install git using our package manager:

winget install git.git

brew install git

Repository initialization && creating the first commit#

Go back to your editor.

  1. On the activity bar, click the icon. Source Control window will open up.

  2. On the Source Control window, you should see Initialize Repository button. If not, click reload.

  3. Click Initialize Repository. Changes window will show up, which should show you the following files:

    1. main.c

    2. main

    3. tasks.json

    4. launch.json

    5. compile_flags.txt

    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 and files for compiling the project are tracked in a repository, so we will only track main.c, tasks.json, launch.json, compile_flags.txt, but not the compiled file main.

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

    Fig. 2 Four added files (A) and one untracked (U) file on the Changes window. 5 on the icon indicates that there are changes on 5 files.#

  4. To add these two files to the repository – or to track in other words, hover on the filenames and click the symbol on each. You will an A on the right of the files, which stands for added as depicted in Figure 2.

  5. Click 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.

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

Warning

When you commit your first changeset, you may get an error about that you did not setup git username and email. Git attaches a name and email address for each commit to identify the committer.

Setup them using following commands on a terminal. You can choose any name or email. If you use your GitHub username, then the forge will link your commits to your profile.

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR_EMAIL"
changeset

list of differences between two successive versions in a repository

commit

the operation of committing such a changeset to the repository

Sharing our repository on GitHub#

The repository we used is until now local to our computer. Now we will create a copy of the local repository on GitHub.

  1. On the Graph window, click the Publish Branch icon. 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 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 the (bell) icon in the below right corner of the editor.

Checking the forge after push#

After pushing your code, you should see the notification on the bottom left:

Successfully published the “YOUR_USERNAME/PROJECT” repository to GitHub.

To see if everything went correctly, Click Open on GitHub.

If you cannot find this notification, you can also browse github and search for your project there. If you cannot find it, you can also use the following URL template:

https://github.com/YOUR_USERNAME/YOUR_PROJECT

You should see something similar to:

YOUR_USERNAME  initial   ... 1 Commit

.vscode
compile_flags.txt
main.c

Adding a README on GitHub#

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

We could do these steps in our editor, but we will try the web interface to demonstrate the synchronization between the forge and local repository.

  1. Go to github and to your project repository.

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

  3. You can write something along the lines of:

    # Hello

An example program for my C programming course.

    Click Preview to see how this text will be rendered.

  4. Commit changes.... Commit changes window will pop up.

  5. 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. You can close GitHub.

  2. We made changes on GitHub, which are not visible on the repository on our computer.

  3. On the editor, if you have a notification about: Would you like ... to periodically run "git fetch"?. Click Yes, unless you prefer manually pulling the changes. If you don’t see the notification, then search for git.autofetch in settings and activate it.

    This setting will automatically get the project updates from the forge. This is useful when we collaborate or edit our code on different platforms, e.g., local computer, web-based IDE or on the forge.

  4. Auto-fetch will automatically download the changes you have done on the forge every 3 minutes. After some time you should see that the blue main icon will be below the violet origin/main icon. If not, you manually fetch using the icon.

The different levels of the and icon means that your repository downloaded the changes from the forge, but they are currently not applied. The application operation is called pull.

  1. To pull the changes, on the Graph window, click Pull icon. Now the icons and will be on the same level.

When should we create additional commits?#

After you have a meaningful progress on your project, then you should create a commit. Let us take this website as an example. These course materials are also organized in a repository. When I begin working, a have typically a goal, e.g., I want to write a new section about Organizing code in a repo in the file organizing-code-in-a-repo.md. In the process of writing this section, then I may also have to modify other already existing files like first-project.md and ide-installation.md. When I am finished, my changeset will consist of the modifications in first-project.md and ide-installation.md, and the new file organizing-code-in-a-repo.md. Then I would stage these three changes and write a commit message like:

new section: Organizing code in a repo

Finally I would commit and push my changes.

Adding additional commits in the editor#

../_images/git-staged-changes.png

Fig. 3 Two staged files after our initial commit.#

Now we will create commits in our editor ourselves. Let us assume you have an initial commit that contains your initial C project. You modified your main.c by formatting the code and added the flowchart image flowchart.svg that documents your code.

  1. On the activity bar, click the icon. Source Control window will open up.

  2. Hover over one file that you want to stage before committing, then click the symbol. Repeat this for each file you want to stage.

    In our case we want to add flowchart.svg and main.c.

    After staging, your Changes window should look like Figure 3.

  3. Write a descriptive message, e.g.,

    formatting & flowchart

  4. Click Commit or Commit & Push. The latter is under the icon.

Which files belong to the repository?#

Only add source files and project files which are relevant to compile and run your code to the repository. Files generated from source files usually do not belong to the repository, e.g., *.exe, log files etc. Some reasons are:

  • A repository is typically used to track changes in text files, because text files consists of readable lines which can be easily differentiated between commits.

  • We want to keep our repository minimal to avoid complexity. If some files can be easily generated using the source files, we have less amount of files by avoiding generated files.

.gitignore for hiding files that do not belong to the repo#

We did not stage one of the files in Figure 3 – main (main.exe on Windows). We should never commit an executable file, so hiding it forever from git changes would be more convenient.

You can ignore it by following the steps using the .gitignore file:

  1. Click the icon on the sidebar.

  2. In the root of your project, create a file named .gitignore and open it.

  3. Add the following line

    main

    .gitignore contains the names of files or folders which should be ignored by git.

  4. Save the file. You will see that the green U symbol right to the main will vanish and main will also be grayed out.

    The graying out helps with focusing on source files instead.

  5. Click the icon. You will see that main does not show up anymore.

  6. Stage .gitignore and commit (and push) your changes.

Contents