GitHub repositories are remote directories that store files and their revision histories (see this guide). With GitHub repositories, code collaborators can track changes made to source code, create different versions of code through branches, and manage access to code through repository visibility. GitHub repositories can be created through the GitHub GUI or through the command line with Git. This section will show how to create an empty remote GitHub repository using the GitHub GUI and how to initialize a remote GitHub repository from a local project.
On the GitHub home page navigate to “+” at the top right of the page and click “new repository”
Set the owner of the repository from the drop down under the owner field and name the repository. The owner can be your own user account or an organization if your account is linked to any team/organization.
On the same page, set the repository access to public or private. This sets the read access for the repository. Public repositories can be read by anyone on the internet while private repositories can only be accessed by users or organizations you explicitly share the repository with. For both visibility modes, you choose who can commit to the repository.
(optional) Add a README file. README files are Markdown files that describe what your repository does and how to use it. Clicking the “Add a README file” box initializes your repository with an empty README file. The contents of README files will be displayed on the code section of the repository page.
(optional) Add a .gitignore file. The .gitignore file lists all the files that you don’t want to track the version history of. Under the “Add .gitignore” there is a drop down of templates for the .gitignore file for different industry practices or best practices for different languages.
(optional) Choose a license. You can initialize your project with a software license that defines what is fair use of your software. Under the “Choose a license” there is a drop down of software licenses that you can choose from.
Finally, click “create repository” at the bottom of the page.
To create a repository from an existing local project, first follow the steps in Creating an Empty Repo to create an empty remote repository. Next, enter the following commands in a command shell:
$ cd [local_project]
# initialize empty repository in .git directory
$ git init
# Track all files in the project
$ git add --all
$ git add LICENSE
# commit tracked files to the repository
$ git commit -m "first commit" see https://rubygarage.org/blog/most-basic-git-commands-with-examples
These commands create a local Git repository and stage all the files in the workspace to be added to the empty remote workspace. To link this local workspace to the empty remote repository, you need an HTTPS link to your remote repository. To copy this https link:
Click on the "code" section on the GitHub repository page
Click on the “code” button
Click on “HTTPS”
Click the clipboard icon
Next, enter the following commands in a command shell:
$ cd [local_project]
#add a new remote
$ git remote add origin [your https link]
#verify the new remote
$ git remote -v
#push committed changes to repo
$ git push -u origin master These commands add a new remote for the empty repository and then push all the staged changes in the local Git repository to the remote repository.
Unless you created a repository from an existing local directory, The GitHub repositories created in previous sections are purely remote repositories. To sync these remote repositories with a local workspace you can clone your repository into a local directory. Once you clone your repository into a workspace, you can add changes on your local machine and then push them to your remote repository.
To clone your repository you first need an HTTPS link. If your repository is empty you can copy this from the top of your repository page.
If the repository is not empty, you can copy the HTTPS link by:
Clicking on the "code" section on the GitHub repository page
Clicking “code” button
Clicking “HTTPS”
Clicking the clipboard icon
In the command line enter the following:
$ cd [your_local_workspace]
$ git clone [HTTPS link]Now your remote repository is synced to your local workspace. All changes that are explicitly committed and pushed will be added to the remote repository.
At a high level, Git performs Version Control for repositories through branches. Each repository has a master branch which is the mainline of the project (see Git branches guide). Code collaborators can create different versions of the same repository by creating new branches diverging from the master branch (see Git branches guide). Every branch, including master, keeps track of the changes explicitly committed to it..
To push local changes in your cloned repository to the current branch, enter the following commands in your cloned repository:
$ git add --all
$ git commit -m "your commit message"
$ git pushGit add marks the files you want to include in the next commit (see Git add guide). Using “git add --all” marks all files in the current directory. For more Git add options see Git add guide. At a high level, Git commit stores a “snapshot” of the state of marked files to save to the branch (see this article). Finally “git push” transfers your commit to your remote repository (see this article).
When collaborating with others, you should always make sure you are working with the latest version of the repository before making local changes. To update your local workspace to the latest commit of the remote repository, enter the following command in your local workspace directory:
$ git pullGit pull fetches and merges the latest commit of the branch your local workspace is currently on. For more on Git pull see this documentation.
If you don’t already have a GitHub account, go to https://github.com/ and sign up (this is completely free unless you want to use a paid version of GitHub). Once you have a GitHub account, open a command shell and enter:
$ git --versionIf you already have Git installed then a version number should appear. If your computer doesn’t recognize this command then consult this guide on installing Git for your machine.
Once Git is installed, you can alter its settings by changing configuration variables with the “git config” command (see this article). If this is your first time using Git on the command line, you will need to set the “user.name” and “user.email” configuration variables to your GitHub username and email so that Git command line is linked to your account. You can do this by entering the following commands:
$ git config --global user.name = "your username"
$ git config --global user.email = [your github email account]The global flag makes these the default values for anything you do on the machine (see this article). These are the only configuration variables that you are required to alter to use Git. For more information on configuring Git see this Git documentation.
As mentioned in the section, you can determine which users can see your repositories. If you set repository visibility to “Public” then anyone on the internet can read and download your repository. If you set repository visibility to “Private”, then only users or organizations you explicitly invite can read and download your repository. To change visibility of your repository:
Click “settings” on your repository’s GitHub page
Click "Options" from the sidebar
Scroll down to "Danger Zone" section
Click "Change Visibility"
Changing the visibility of your repository can affect your repository’s forks and must be done with caution (see article for more details).
You can explicitly invite users to commit changes to your repository through adding collaborators:
On the repository page navigate to “settings”
Click “Manage access”
Click “invite collaborators” and type in the user name of the users you want to add.
