Git: VS Code

Learning outcomes

• use code editor VS Code for working collaboratively in Git with Windows, Mac and Linux
• track changes in VS Code
• clone and push a remote repository from the code editor

Starting our editor with add-ons: Visual Studio Code

VS Code is an example for code editors. Using the command line or terminal instead has the same results. However, in a code editor, you can work in a graphical user interface.

Working with git in the editor

Cloning a repository and getting data

For example we want to clone teapot from https://github.com/acdh-oeaw/howto_trainingmaterials. The data at this location, in this repository, is marked as public. So you do not need to log into the Oeaw GitHub, but you need to be logged into your GitHub account that you set up to see the contents.

On the top right there is a Clone button which, when clicked, gives you two options HTTPS and GitHub CLI. We need the HTTPS option. On the right there is a copy to the clipboard button we can use.

At the end there is a little dialog in the bottom right corner, click open there:

Because Visual Studio Code is a development environment where developers can execute code they just downloaded from somewhere on the internet, Visual Studio Code asks if we trust the current repository. Therefore, choose to “trust” the repository that you downloaded from a team you know.

See our GIT collaboration guide to learn more about cloning a remote repository.

Tracking changes

Git is very helpful in tracking changes in a project.

Git can record which changes, to which documents, have been made when, and by whom. It allows to keep a detailed revision history of a project, because it can save snapshots - the commits - of a project at specific points in time, thus being open to review any time in the future.

Version control allows to save versions of content, restore previous versions, and compare different versions. This is especially beneficial when working with multiple documents, and when working in teams of more than one (potentially working on the same document).

Before uploading any changes, you want to track them locally. After cloning the howto_trainingmaterials, let’s open the teapot.txt in Visual Studio Code. This is done while the uppermost icon on the left is selected (the two sheets, files).

We want to change something so we replace every I with you in the lyrics and add the line You drink tea every day at the end. Save this file version.

Now we can select the third mode from the top (three connected circles, the graph changes and branches make up in version control).

This only lists those files that we changed since we last made our changes permanent, committed (to) them. The teapot.txt is listed. If we click on it we get the following view:

If we are not 100% sure about the changes we will now stage, that is prepare to be committed, we can open each file and see the differences per line. This might also give us a hint what we did if the last commit was a while back and we don’t remember exactly why we changed the files.

Mark content changes to be included in the version history

Let’s tell Git that we are committed to our changes in the document teapot.txt:

We put changes in the staging area, before we commit.

See our GIT version control via command line guide to learn more about adding files.

Bundle changes into meaningful chunks and commit to them

Including content changes in Git’s version history involves a two-step process. First, related changes are added to create semantically meaningful units of changes. These changes wait in the staging area but it needs an extra step to propagate these changes and feed them into the documents. Keep that in mind.

When all related changes have been added to the “staging area”, we can save them together as a current snapshot of our data, a commit, with a commit message that briefly describes why changes were made. This makes it easier to understand them later when viewing the version history. Committing means permanently recording a snapshot of contents at a specific point in time. In VS Code you use the commit button.

The very first commit error

If you are on a new machine and/or just installed Git you will get an error. Here is how it looks:

Whether you use Learn More or Open Git log, you will eventually see that Git just wants to know who commits here. We suggest to use Open Git log which shows a new set of controls at the bottom right.

There is no graphical interface for this one time configuration. You need to copy the two suggested git config commands and fill in your own details and execute them in a terminal. Create a new text file with File->New text file, copy the above lines starting with git config and fill in your information. Use the Visual Studio Code tab Terminal at the bottom. Alternatively you can select “Terminal” and “New Terminal” from the menu bar.

See our GIT version control via command line guide to learn more about bundle changes into meaningful chunks and commit to them.

Keeping repositories in sync: fetch, pull, push

To get our changes to the server, so other people in our team can fetch them to review or amend them, we now push what we committed on our machine to the server.

The opposite action is to pull from the server. This means getting all the changes accumulated there and integrating them (merging them with our local changes if any) in the files we see locally.

If we just want to download all change not integrating them at the same time we fetch from the server.

Merging and conflict resolution

What happens if two people edit the same file? Well it depends:

1. If two people edit different lines in the file, then the changes can be merged automatically. That is a good solution in most cases and it saves a lot of time.
2. If two people edit the same line, then there is a conflict that needs to be resolved.

Conflicts are marked with these distinct lines:

<<<<<<<< ...
One change
--------
The other change
>>>>>>>> ...

Note that Visual Studio Code provides us with a few controls we can click to resolve the conflict.

We now can decide which is the better change (or use both if applicable). Visual Studio Code shows you different options in a three-way-editor:

And for example, accept the incoming change.

And after resolving all the conflicts we do a merge commit (the text is there automatically).

Training task

Open your code editor. Clone the repository https://github.com/acdh-oeaw/howto_trainingmaterials to your local work station. We used it in the Git collaboration - resource too.

Inspect the repository by checking its status, and pull all changes that have been created in the meantime. If you do this exercise on your own, there might be no changes - still, it’s best practice to pull regularly.

Navigate to the test-file.mdx and open it. In it, you will find several sentences talking about a particular breed of dogs. Replace the current breed with another of your choosing and move all those new sentences to the very end of the document. Save your actions and commit them with a meaningful message.

Perform git push.