Before you start
- Complete steps in Getting started with Git on Drupal.org
- Apply and receive full Git privileges
- Create a full project on Drupal.org
Note: the brackets on this are not part of the commands, they just mark variables, so for example when you read
mkdir [project_name] and your project is called Views, what you need to type is
Create your repository on Drupal.org
Note: These are one-time steps for populating your repository on Drupal.org. If you need to get a new copy of your repo, on a machine at work for example, follow the instructions to Clone your repository.
- Create a directory on your computer and change into it:
Next, initialize the repository. This adds the .git directory, subdirectories and files that store your repository data.
Then, add files to your repository. Use the sample command to create a .info file, or work with your actual files and directories as suits you. The key thing is to put something into your repository so you can complete the setup.
echo "name = [Human Readable Project Name]" >project_name.info
Let's make the repository on Drupal.org the default remote repository we pull from and push to. The command to do this is called "git remote add" and it takes two arguments, the first is the name we will use in our push and pull commands for this repository and the second is the actual repository URL. It's practical to make the first argument "origin" because push and pull both defaults to that name. The second argument looks like 'ssh://[username]@git.drupal.org:project/[projectname].git'.
git remote add origin [username]@git.drupal.org:project/[project_name].git
Finally, put your code on Drupal.org. Git commits are a little bit like the Ready, Set, Go of running a race. You get ready by staging your files with 'git add', get set by committing the files in your local repository with 'git commit', and go when you push your changes to the remote server with 'git push'.
git add project_name.info
git commit -m "Initial commit."
git push origin master
Clone your repository (to work on your existing project locally)
When a repository already exists on Drupal.org, you'll use 'git clone' to set it up in your local environment for the first time. The command below guides you to explicitly choose the branch you are cloning. The project's Git instructions tab allows you to choose from existing branches and formats the command for copy and paste.
git clone --branch [branch_name] [username]@git.drupal.org:project/[project_name].git
Note: You can also find git instructions specific to your project under the "Git instructions" tab on your project page.
Work in your local repository
Once you have your repository created on Drupal.org and cloned locally, you can do various tasks.
Check out an existing branch
In Git, "check out" means to switch your local clone to using a different branch. To do this:
git checkout [branch_name]
Create a branch
See also Creating a tag or branch in Git. You will want to do this when you are working on an issue or a new feature. Typically, you will use a branch name of "[issue-number]-[short-description]". To create a branch:
git checkout -b [branch_name]
Then you can edit files, apply patches, etc. Finish by committing to your branch, and then merging the changes back into the main line. (Instructions for all of these tasks are below.)
Apply a patch
If you need to review/test the patch before committing it, first create a branch (see above). If not, you can work directly in the branch that you need to apply the patch to, and just checkout that branch. To apply a patch someone else has created for your project:
- Checkout the branch or create a new one (see above).
- Download the patch to your local machine (outside the repository).
- Apply the patch by typing
git apply /path/to/patch
Check your repository status
The git status command tells you:
- What you would commit if you ran git commit
- What you could add to the next commit by running git add
- What you have committed but not pushed back to Drupal.org
After making changes (edits, adding files, applying patches, etc.) in your local repository, get your changes ready to commit with 'git add'. We recommend the '-u' flag, which looks at all the currently tracked files and stages the changes to them if they are different or if they have been removed. It does not add any new files, it only stages changes to already tracked files. This keeps you from inadvertently uploading files.
To add specific new files, you can use 'git add' with an explicit path and file name. To stage everything, files that have been removed, updated, and added, use 'git add -A'.
git add -u
git commit -m "Issue #[issue number] by [comma-separated usernames]: [Short summary of the change]."
Merge your changes back to the main branch
If you were working on an issue/feature branch, after committing, you will need to merge your changes back to the main branch. To do that:
git checkout [main-branch-name]
git merge [issue-branch-name]
Push your code back to the repository on Drupal.org
Everything you have done up to this point has been acting on the local clone of your repository. The final step is to get these changes back to Drupal.org. (Note: The
git pull --rebase; git push approach here will work in simple workflows, but note that with many committers or with sophisticated long-running feature branches you may have to adopt a more complex workflow like the one described in the Sandbox Collaboration Guide.)
# Update with changes that another committer might have made.
git pull --rebase
# Push your commits back up.
Note: if you want to push another branch, one that is not currently worked on, you can use
git push origin [branch_name].
Create a patch
git format-patch origin --stdout > [description]-[issue-number].patch
Branch for a dev release
This creates and checks out a new branch in one command:
git checkout -b 7.x-1.x
git commit -am "Commit message"
git push origin 7.x-1.x
Tag for a stable release
git checkout 7.x-1.x
git tag 7.x-1.0
git push origin 7.x-1.0
Note that for new branches and tags you can not use the simpler
git push command, you need to specify the name of the remote repository (
origin was set up above) and the name of the tag/branch to be pushed.
git push -u origin 7.x-1.0 will make
git push work again.
Copy your repository onto Drupal.org from an existing repository
These are one-time steps for populating a Drupal.org repository from an existing Git repository (from Github or anywhere else it might live).
# Clone the repo as a mirror from the original source
git clone --mirror [github_or_other_url]
# Create a new remote using the maintainer URL from the git instructions.
git remote add newproject [maintainer_url_from_git_instructions]
# Push all the code and branches into the git.drupal.org remote
git push --all newproject