ARCHIVE: Project maintainer guide

Last updated September 30, 2012. Created by eliza411 on February 12, 2011.
Edited by andreathegiant, danmuzyka, jhodgdon, chx. Log in to edit this page.

Before you start

Prerequisites:

• 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 mkdir views.

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.

1. Create a directory on your computer and change into it:

   mkdir [project_name]
cd [project_name]

2. Next, initialize the repository. This adds the .git directory, subdirectories and files that store your repository data.

   git init

3. 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

4. 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

5. 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
cd [project_name]

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

Type:

git status

Commit changes

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.)

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 fetch
git format-patch origin --stdout > [description]-[issue-number].patch

Create releases

See the naming conventions for a complete description of how to name branches and tags so you can create releases. See also Creating a tag or branch in Git.

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).