In order to use Git and easily navigate through folder (repositories), you can use the Terminal. The default shell takes Bash commands.
Every coder has her own favourite editor. A popular choice is Sublime: it is crisp and favours focusing, the default dark background is relaxing, it provide appealing syntax and color rendering, it has a minimal intuitive IDE (and customizable settings). You can launch Sublime from the command line. In the Terminal, navigate to the folder of your choice and open its contents with
subl .
There is no escape: for modern collaborative projects, the way to go is to make an effort and learn some basic tools of version control, which means using git and Github (or a similar provider). The effort of this steep learning curve will be rewarded as the complexity of your project increases.
Sync GitHub with your computer using git:
- Create a repository on GitHub and then sync it with your machine.
There are a few basic concepts to start using git, and they involve some jargon, as for GitHub.
git init: Move to a given folder from the Terminal, such as cd Dropbox/dev/ and tell git that this folder needs to be initialized.
git status: Check the status of your folder with respect to the origin (which is the folder on GitHub). You can always set what is your remote repository locally.
git add .: After you have made your changes to the files of your folder (repository) on your machine, you want to add all this changes to the modification you want to submit (commit).
git commit -m "your comment": you are submitting a modification in a bundle (commit) and you are commenting the modification for your records (a track of this changes will be available in the repository history).
git pull: this command downloads the current version of the repository (master or branch) to your local machine, e.g. with git pull origin master;
git push <branch>: this command uploads the current version of your local repository to the online copy, e.g. with git push origin master;
git checkout -b <new-branch>: Create a new branch; moving from the master to a branch is equivalent to taking a diversion from the main route, in order to do some changes without affecting the core project, at least yet.
git merge <branch>: Once you are satisfied with the changes, you are ready to merge the branch back into the master and eventually you can delete the branch.
Open the Terminal, navigate to the folder of your repository, such as
cd github/opensource/mylibrary/mylibrary
You can Make changes to code in your text editor or in a Jupyter Notebook
git status
git add .
git commit -m "fix a small typo"
git push origin <name-of-branch>
where you should substitute <name-of-branch> with the name of the branch.
GitHub provides the largest collection of code projects in the world. This is an invaluable treasure of searchable open-source projects from which you can copy, modify, and get inspiration for your own library and benefit as a simple user. As of 2019, Github allows single users also to host private repositories for free. GitHub has been acquired in late 2018 by Microsoft. Other similar services include Gitlab and BitBucket.
The basics of GitHub is that to contribute to an open-source projects there are three connected locations. Roughly speaking:
-
the "official" online repository of the project (your
upstream); -
the copy of such repository on your profile (your
origin); -
the local copy of your repository on your machine.
A typical workflow would consist in the synchronization and update with modifications of these three different locations where the code project lives.
To create a new repository from scratch, you can navigate to your GitHub account profile page, select Repositories from the tabs and then click on New. Github will guide you through the creation of a new repository online.
In order to contribute to an existing open-source project, once you have your GitHub account, navigate to the repository of your choice and click on the upper right on Fork. This command creates a copy of the project's folder on your profile.
In order to create the local copy of one of your profile's repository, hosted online on GitHub, such as mylibrary, you can clone it. On the upper right part of the web page, click on Clone or download and copy the link that appears. Then, on your machine, open the Terminal, navigate to the folder where you wish to keep this repository (such a github/ folder), and then write in the terminal
git clone https://github.com/yourusername/mylibrary.git
To open a pull request (PR), navigate to the repository webpage, such as QuTiP's qutip/qutip, click on the right menu where you can find an Pull Requests tab.
You can click on New pull request to raise a PR online, however the best practice is usually to go through your fork and open it from your remote origin repository.
To raise an issue, navigate to the repository webpage, such as QuTiP's qutip/qutip, click on the right menu where you can find an Issues tab, and then click on New issue. There are some best practices on starting new issues. Some are project-independent, some are project specifics. For example, in repository where you have administrative rights, you can improve the issue traceability by adding some metadata, such as giving the issue a label, or asking for a specific user to look into it.
Although the word "Issue" sounds quite negative, Issues can be brought up also regarding enhancements to a project. Once an issue is taken care of, it can be closed. All closed issues are listed on a repository's page on Github.
Anaconda is a package manager. You can install it for the command line, so that from the Terminal, you'll be able to install packages with the conda prefix as a command. For example:
conda install numpyNote that you can install pip in conda and hence use packages that are distributed only there. For example:
conda install pip
pip install qiskitComplete information on how to manage environments can be found [here](Conda: Manage environments).
It is particularly helpful to use conda to create siloed environments in which to define specific installations of various packages:
conda create -n myenv
conda activate myenv
(myenv)
To deactivate a conda environment simply do
(myenv) conda deactivate
To delete a conda environment (this is advised at some point as multiple conda environments can take up GB of space) type
conda remove --name myenv --all
To list your environments
conda env list
- Add Sublime to the command line
- GitHub: Add remote repo.
- GitHub: Create a repository
- Conda: Manage environments
- Github: Contribute to an open-source project: some guidelines from the QuTiP project.
Advance to Section 2 - Developing Your Code.