This tutorial provides an overview of how to set up a repository (repository) under Git version control. This resource will guide you through initializing a Git repository for a new or existing project. The following are workflow examples of repositories created locally and cloned from remote repositories. This guide assumes a basic familiarity with a command-line interface.
The high-level points that this guide will cover are:
Initializing a new Git repository Clone an existing Git repository
- Commit a modified version of a file to the
- versioning commands
- Git
- repository
repository Setting up a Git repository for remote collaboration Common Git
by the end of this module you should be able to create a
, use common Git commands, commit a modified file, view your project history, and set up a connection to a Git hosting service (Bitbucket).
What is a Git repository?
A Git repository is a virtual store of your project. It allows you to save versions of your code, which you can access when needed.
Initializing
a new repository: git init To create a new repository, you will use the git init command.
git init is a one-time command that is used during the initial configuration of a new repository. Running this command will create a new .git subdirectory in your current working directory. This will also create a new parent branch.
Version control of an existing project
with a new git
repository
This example assumes that you already have an existing project folder in which you want to create a repository. You’ll first cd to the root folder of the project and then run the git init command.
Pointing git init to an existing project directory will run the same initialization configuration as mentioned above, but with the scope of that project directory.
Visit the git init
page for a more detailed resource on git init.
Cloning an existing repository: git
clone
If a project has already been set up in a central repository, the clone command is the most common way for users to get a locally developed clone. Like git init, cloning is generally a one-time operation. Once a developer has obtained a working copy, all version control operations are managed through their local repository.
Git Clone is used to create a copy or clone of remote repositories. Pass git clone a repository URL. Git supports a few different network protocols and corresponding URL formats. In this example, we will use the Git SSH protocol. Git SSH URLs follow
a template of: git@HOSTNAME:USERNAME/REPONAME.git
An example of Git SSH URL would be: git@bitbucket.org:rhyolight/javascript-data-store.git where the template values match
:
- HOSTNAME: bitbucket.org
- USERNAME: RHYOLIGHT
- REPONAME: JAVASCRIPT-DATA-STORE
When run, the latest version of the remote repository files in the main branch will be deployed and added to a new folder. The new folder will be named REPONAME in this case javascript-data-store. The folder will contain the complete history of the remote repository and a newly created parent branch.
For more documentation on using git clones and supported Git URL formats, visit the git clones page.
Save changes to the repository: git
add and git
commit
Now that you have a cloned or initialized repository, you can commit file version changes to it. The following example assumes that you have configured a project in /path/to/project. The steps in
this example are: Change directories to /path/to/project Create a new CommitTest file.txt with content ~”Test
- content for git tutorial”~
- Create a new commit with a message describing what work was done on the commit
- CommitTest.txt
git Add CommitTest.txt to the repository staging area
After running this example, the repository will now have
added to the history and track future updates to the file
.
This example introduced two additional git commands: add and commit. This was a very limited example, but both commands are covered more in depth in the git add and git commit pages. Another common use case for git add is the -all option. Running git add -all will take any modified, uncrawled files in the repository and add them to the repository and update the repository work tree.
Repository-to-repo collaboration: git push
It’s important to understand that Git’s idea of a “working copy” is very different from the working copy you get by pulling source code from an SVN repository. Unlike SVN, Git makes no distinction between working copies and the central repository, they are all full Git repositories.
This makes collaborating with Git fundamentally different than with SVN. While SVN depends on the relationship between the central repository and the working copy, Git’s collaboration model is based on repository-to-repository interaction. Instead of checking a working copy into the central SVN repository, it sends or pulls commits from one repository to another.
Of course, there’s nothing stopping you from giving certain Git repositories special meaning. For example, by simply designating a Git repository as a “central” repository, it is possible to replicate a centralized workflow using Git. This is achieved through conventions rather than being wired into the VCS itself.
Bare repositories vs. cloned repositories
If you used git clone in the “Initializing a new repository” section above to configure your local repository, your repository is already configured for remote collaboration. Git Clone will automatically configure your repository with a remote control pointing to the Git URL from which you cloned it. This means that once you make changes to a file and commit them, you can push those changes to the remote repository.
If you used git init to make a new repository, you won’t have a remote repository to push changes. A common pattern when initializing a new repository is to go to a hosted Git service like Bitbucket and create a repository there. The service will provide a Git URL that you can then add to your local Git repository and push git to the hosted repository. Once you’ve created a remote repository with the service of your choice, you’ll need to update your local repository with an assignment. We discuss this process in the setup and configuration guide below.
If you prefer to host your own remote repository, you will need to set up a “Bare repository.” Both git init and git clone accept a -bare argument. The most common use case for bare repository is to create a remote central Git
repository Configuration and configuration: git config Once you have a remote repository configuration, you will need to add a remote repository URL to your local
git configuration and set an upstream branch for your local branches. The git remote command provides such a utility.
This command will map the remote repository to a reference in its local repository in . Once you have assigned the remote repository, you can push local branch offices to it.
This command will push the local repository branch under < local_branch_name > to the remote repository on < remote_name >.
For a more detailed look at git remote, see the git remote page.
In addition to configuring a remote repository URL, you might also need to set Git global configuration options, such as username or email. The git config command allows you to configure your Git installation (or an individual repository) from the command line. This command can define everything from user information to the preferences and behavior of a repository. Several common configuration options are listed below.
Git stores configuration settings
in three separate files, allowing you to define the scope of options for individual (local), user (Global), or system-wide (system) repositories
: Local: /.
- git/config – Repository-specific configuration
- Global: /.gitconfig: User-specific settings. This is where the options set with the -global indicator are stored.
- System: $(prefix)/etc/gitconfig – System-wide configuration.
.
Define the author name to use for all commits in the current repository. Typically, you’ll want to use the -global flag to set configuration options for the current user.
Define the author name that the current user will use for all commits.
Adding the -local option
or not passing a configuration level option at all will set the user.name for the current local repository.
Define the author email to be used for all confirmations for the current user.
Create a shortcut for a Git command. This is a powerful utility for creating custom shortcuts for commonly used git commands. A simplistic example would be:
This creates a ci command that you can run as a shortcut for git commit. For more information about git aliases, visit the git settings page.
Set the text editor used by commands such as git commit for all users on the current machine. The editor < > argument must be the command that starts the desired editor (for example, vi). This example presents the -system option. The -system option will set the settings for the entire system, that is, all users and repositories on a machine. For more detailed information about configuration levels, visit the git configuration page.
Open the global configuration file in a text editor for manual editing. A detailed guide on how to set up a text editor for git to use can be found on the Git settings page.
Discussion
All configuration options are stored in plain text files, so the git config command is really just a convenient command line interface. Typically, you’ll only need to set up a Git installation the first time you start working on a new development machine, and for virtually all cases, you’ll want to use the -global flag. An important exception is to cancel the author’s email address. You may want to set your personal email address for personal and open source repositories, and your professional email address for work-related repositories.
Git stores configuration settings in three separate files, allowing you to define the scope of options for individual repositories, users, or the entire system: /.git
/config – Repository-specific settings.
- ~
- /.gitconfig – User-specific settings.
- This is where the options set with the -global indicator are stored.
- $(prefix)/etc/gitconfig – System-wide configuration.
When the settings
in these files conflict, the local settings override the user settings, which override the system-wide settings. If you open any of these files, you’ll see something like the following:
You can manually edit these values with the same effect as git config
.
Example
The first thing you’ll want to do after installing Git is to tell it your name/email and customize some of the default settings. A typical initial configuration might look similar to the following:
Tell Git
who you are Git
config Select your favorite text editor
Add some SVN-like aliases
This will produce the ~/.gitconfig file from the previous section. Take a deeper look at git config on the git configuration page.
Summary
Here we demonstrate how to create a git repository using two methods: git init and git clone. This guide can be applied to manage the source code of software or other content that needs to be versioned. Git add, git commit, git push, and git remote were also introduced and used at a high level.
Read our guide on which code repository system is right for your team!
