Scores of Beauty Engraving Challenges
<= Editing workflow
Main page
Using Git =>
If you have not worked on projects that use Git and GitHub for collaborating, here is a brief overview of the basic concepts involved. If you are already familiar with these tools, feel free to skip this section.
Version Control Systems (VCS) are used to track how a set of files changes over time, and to manage these changes. VCS software, such as Git, stores the complete development history of a project. This allows its users to investigate, compare and manipulate any states the project has ever been in over time.
As a first approximation you may understand version control as an infinitely flexible undo/redo mechanism.
The rest of this document is focused on Git, which we use to manage Engraving Challenges.
A project usually has one main repository ("repo"), stored on GitHub (or other similar service) - which reflects the "official" state of the project. This repository is used as the basis for other repositories that individual contributors may maintain, both on GitHub and on their own local machines. It is customary to refer to this main repository as the "upstream" repo.
This repo is what you will read from whenever you need to get the latest versions of the project files. All your changes should also finally land there, but you will probably not write to this repo directly - the project lead(s) will merge your changes when you sumbit them.
When you join a project, you start by creating your own copies of the main repo. Firstly, you create a "fork" on GitHub - this repository will be visible to other people, and you will have write access to it. You will then "clone" this fork to your computer; we will refer to this copy as the "local clone" or "local repo". This local repo remembers the adress of your fork as a "remote" repository called origin.
Repositories can talk to each other. Uploading changes from local repository to remote repository is called "pushing", and downloading changes from remote repo is called "pulling" or "fetching". Any repository can talk to any other repository (i.e. changes can be sent between any repos), but usually changes travel between repos in a specific order.
Changes in one repository aren't automatically transferred to other repositories. In particular, new work submitted by other contributors to the main repo won't be automatically copied to your GitHub fork, nor downloaded to your local repo.
Most of the time you'll be working with your local repo, which is your own personal sandbox. You can play with these files however you like - in particular, you can create new files and tell Git to track them.
Every so often, you'll decide that you want to make a snapshot of the current state of your work. This is called a "commit". Making a commit is similar to saving a document after making some modifications, except that when you save a document, it's previous version is overwritten - but when you make a new commit, all previous versions (commits) will remain available in your repository.
After one or more of these commits, you can upload ("push") them to your fork on GitHub. This has two purposes: first, you will have a backup of your work; second, other people will be able to see what you've done.
When you decide that you have finished a coherent set of changes and would like to submit them to the official repo, you once again upload your changes to your GitHub fork and then issue a Pull Request to ask the project lead to merge your changes into the upstream repo.
You will also periodically grab the work others have submitted by pulling changes from upstream repository. After doing so, you can continue working, do more commits, more pushes, and pull requests, and the cycle continues.
This basic overview applies to many projects on GitHub. In the next section, you'll find some more specific information on working with Engraving Challenges repositories.
Version control might at first seem to be complicated, and you're probably wondering whether it's really worth using. If that's the case, we suggest that you take a look at this blog post written by Urs Liska. You may also browse all posts tagged with "version control".
Scores of Beauty Engraving Challenges
<= Editing workflow
Main page
Using Git =>