Intro to Git for PS Users - Intro

git clone https://@github.com/qic-ibk/projective_simulation.git

where <PAT> is your personal access token.

Creating A Branch

The best practice for collaborative projects it to work in your own branch of the repository. Creating a branch essentially means that git keeps track of two versions of the repository that you can easily switch between. When you have finished a task or a project, you can “merge” branches back together. Generally, if merging two branches would be destructive, meaning any data from either branch would be overwritten, you will recieve a warning and an opportunity to review any conflicts. Creating your own branch means that you can push any changes you make to the remote repository without overwriting anything and give other team members an opportunity to review any conflicts before the merge is made. To create a new branch, use the command

git branch

**Important**: Creating a new branch does automatically change the version you are working on to that branch! To do this, you need to checkout the branch:

git checkout

You can view a list of all available branches using

git branch

Committing Your Changes

Once you have created your own branch of the repository, you can work in the repository however you choose. You can create a snapshot of the repository at any time, allowing you to revert to that repository state later. We won’t discuss reverting in this document, but it is recommended that you commit your changes often. This is done in a two step process. First, you need to “stage” the files you want git to update with its new snapshot, then you commit all of the staged files:

git add file1.py git add file2.py git commit -m “Commit Demonstration”

The -m (“message”) is optional, but it is highly (highly) recommended that you include a short message with every commit that makes it clear what changes you have made. As a general rule-of-thumb, if you are staging multiple files or need long commit messages to describe your changes, you aren’t commiting often enough! The simple habit of making a commit any time you complete a task in your workflow will go a long way toward helping other people understand your work, and can be a real life saver if you ever want to go back and remember exactly how you did something, or try a new approach starting from an old version of code, etc. . .

Pushing Your Changes to the Remote Repository

When you are ready to add your work to the remote PS repository, you can do this either by “pushing” your local repository or by making a “pull request” of the remote repository administrators. Pushing is much simpler, but if your work creates conflicts you will overwrite data in the remote repository. Note that conflicts are not caused by changes in files per se but by differences in commits. For example, if you push your branch to the remote repository, then delete a file locally, commit and push again, there won’t be a conflict! The conflict occurs if somebody else has already pushed a commit that isn’t the branch you are trying to push from your local repository. You can easily recover the deleted file by reverting to an old commit. If you are working using your own branch, you can thus always push it to the remote repository safely:

git push origin

The argument “origin” simply tells git that you are pushing your local repository to the repository from which it was cloned.

If you are working on a branch of the repository collaboratively, or you want to push your changes directly to the “master” brach of the remote repository you should always pull from the remote repository before you push. When you pull from the remote repository, git will try to add any changes made in the remote repository since the last time you pulled from (or cloned) it. If any of these changes would be destructive, you will get a warning and the pull will fail. There are ways to override this, but we won’t discuss them here: if you get a warning about conflicts when both attempting to push and to pull a branch, your collaborative workflow is not working and you should discuss how to proceed with your teammates. The effective approach to making changes to a shared branch such as “master” goes as follows:

git pull origin master git merge -m “local changes merge” git push origin master

Note that merging automatically makes a commit to the master branch (or whatever branch orginates from). Thus, even if your merge requires you to manage some conflicts (for example, your branch deleted a few line of code), you should be able to push to the remote repository without trouble. You aren’t deleting those lines of code, you are just adding a commit that doesn’t include them! Of course, such changes should still be discussed with project administrators - even though the deleted code is recoverable, it doesn’t mean other teammates want to revert to an old commit to find the file version that has it!

With that, you should be equipped to work collaboratively with the PS team! Happy Coding (: