- 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
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.
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
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
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
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
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:
- If two people edit different lines in the file, then the changes can be
mergedautomatically. That is a good solution in most cases and it saves a lot of time.
- If two people edit the same line, then there is a
conflictthat needs to be
Conflicts are marked with these distinct lines:
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).
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.