Help:Git

From Wikitech

Git/Gerrit and the repositories

Restrictions and Anonymous access

Note: Push access is currently limited to staff developers and operations engineers. This will change soon. To pull the repository anonymously for read access use the following command: 

git clone https://gerrit.wikimedia.org/r/p/<repository>

For example: 

git clone https://gerrit.wikimedia.org/r/p/operations/puppet

Browsing only via the web

Public repositories can be browsed from the web:

https://gerrit.wikimedia.org/r/gitweb?p=operations/puppet.git;a=summary

Set up your ssh key in Gerrit

Log into the web interface for gerrit. Click on Settings then SSH Public Keys then add your key.

Checking out the repositories

We have the following main repositories and branches:

  • operations/puppet
    • production (HEAD)
      • used in production
    • test
      • used in configuring labs instances
  • labs/private
    • master (HEAD)
      • only used in testlabs project

To check out the master (HEAD) branch of a repo, you can clone it like so (if they're different, shell-username is your unix shell name, not the wiki username): 

git clone ssh://<shell-username>@gerrit.wikimedia.org:29418/<repository-name>.git

To check out the operations/puppet repo, you can clone it like so: 

git clone ssh://gerrit.wikimedia.org:29418/operations/puppet.git

To check out the operations/software repo, you can clone it like so: 

git clone ssh://<username>@gerrit.wikimedia.org:29418/operations/software.git

To check out the labs/private repo, you can clone it like so: 

git clone ssh://gerrit.wikimedia.org:29418/labs/private.git

'NOTE': Cloning the operations/puppet repo does not work (yet) on Windows as some of the files have names that Windows cannot handle.

Git configuration required to commit

Use git-setup

After the initial clone of the git repository, you can use the git-setup script (in the root level of the repository). It will set your user name and email, pull hooks required for proper use of gerrit, and set up aliases to make pushing for review easier.

...or do initial git configuration manually

First, you should set your name and email address in your local git configuration. The email address and wiki username are the same as what you use to log into this wiki: 

git config --global user.email "<email-address>"
git config --global user.name "<wiki-username>"

Next you'll need to add a commit-msg hook to your local repository. This hook is required for pushing changes to the Gerrit server. 

curl "https://gerrit.wikimedia.org/r/tools/hooks/commit-msg" > .git/hooks/commit-msg && chmod u+x .git/hooks/commit-msg

Finally, you'll need to set up the push-for-review aliases. For the puppet repo: 

cd path/to/your/checkout/of/puppet
git remote add puppet ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet
git config alias.push-for-review-test "push puppet HEAD:refs/for/test"
git config alias.push-for-review-production "push puppet HEAD:refs/for/production"

And for the private labs repo: 

cd path/to/your/checkout/of/private
git remote add private ssh://<username>@gerrit.wikimedia.org:29418/labs/private
git config alias.push-for-review-private "push private HEAD:refs/for/master"

Switch to the correct remote branch

If you're going to be working on Labs, you should switch to the test branch so that 'git pull' can work correctly. 

 git checkout -b test remotes/origin/test

now 'git pull' will fetch and merge changes from the test branch instead of the production branch.

Updating your local repository

After you do the initial repository clone, git will automatically set up a remote tracking branch for you. You simply need to fetch/merge or pull: 

git fetch
git diff origin/<branch>
git merge origin/<branch>

or: 

git pull

Making changes

After cloning the repo, you can make changes the normal git way: 

<make changes>
git add <newfiles>
git commit -a

After doing so, you'll need to push the changes for review; for instance, here's how to push to the test branch of the puppet repository: 

git push-for-review-test

And here's how you push to production: 

git push-for-review-production

And for the private labs repo: 

git push-for-review-private

In order to use the push-for-review aliases, you must set them up first. git-setup does this for you; alternatively, you can add them by hand.

Also, staff operations members have the ability to (but shouldn't!) skip the review step; to do so, simply do a push: 

git push puppet

Review

Review your change (or someone elses!) in Gerrit.

  1. Go to https://gerrit.wikimedia.org
    • if it's your own change, you will see it listed on the first screen
    • if it's someone else's, click on 'All' then 'open' to see all unreviewed changes
  2. click on the change you want to review
  3. click on "Diff all side by side" to examine the diff
    • this will open each changed file in a new tab
  4. when you're done reviewing, go back to the parent tab
  5. click 'Review'
    1. check +1 Verified
    2. check +2 Reviewed
    3. click "Publish and Submit"

You're done! The change is now merged.

under consideration for future workflow: Git-review

Amending a change

Occasionally your change may fail a lint test, or someone may review your change and ask you to fix something. In this case, you'll need to amend your change. To do this:

  1. Checkout the change (you can find this line in Gerrit, on the change, in Download -> checkout, ssh):
    git fetch ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet <ref> && git checkout FETCH_HEAD
  2. Make changes
  3. Commit the change, ensuring you are amending the commit
    git commit --amend -a
  4. Push the change
    git push-for-review-production

The above assumes you are pushing to the production branch, change commands appropriately for other branches.

Fixing a path conflict

For this, assume you have a path conflict in the test branch. To fix a path conflict, you can rebase your change against the tip of the branch. Here's a basic example:

  1. Ensure your branch is up to date:
    git pull
  2. Checkout your change
    git fetch ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet <ref> && git checkout FETCH_HEAD
  3. Rebase it against origin/test
    git rebase origin/test
  4. If there are conflicts, fix them, and run git rebase --continue
  5. Push the change
    git push-for-review-test

Making the changes live in puppet

Test

Changes merged in the test branch will go live in puppet within a minute. Live meaning the change will be available to others when they pull from the test branch, it is not deployed anywhere.

Production

Public repo

Changes for production need to be pulled manually; this is done for security purposes. Here's the procedure you should use: 

cd ~/puppet
git fetch
git diff HEAD origin/production | less
git merge origin/production

Explanations:

The fetch command grabs pending changes in your local repository.

diff HEAD origin/production lets you review them before submitting.

merge origin/production makes you apply the changes to the production branch.

Private repo
cd ~/private
<make changes>
git add <newfiles>
git commit -a

next, sync the changes to stafford 

 ssh stafford
 cd /var/lib/git/operations/private
 git pull

the changes are now live.

Merging changes from test into production

git pull
git merge --no-ff origin/test
git commit --amend
git push-for-review-production

The above assumes you are in the production branch.

Merging changes from production to test

git pull
git merge --no-ff origin/production
git commit --amend
git push-for-review-test

The above assumes you are in the test branch.

dry runs

  • git push has "--dry-run" ("will do everything except for the actually sending of the data.")
  • git merge has "--no-commit --no-ff"
  • git pull - "does not really need it ('git fetch origin', then a 'git log master..origin/master', before a git merge origin/master)"

[1],[2], [3]

Windows

These are the instructions for setting up on a Windows dev machine. Please improve these instructions if you find them to be inaccurate / incomplete.

Installation

Install the following packages:

  • msysgit (http://code.google.com/p/msysgit/) Afterward, restart Windows because the changes to the path seem to only be actuated when that is done.
  • turn on Pageant (comes with putty), and load your private key
  • install git-review (pip install git-review)

Optional packages:

'IMPORTANT': Add the git directory to your path.

Configuration

Command line:

  • Clone the repository: git clone ssh://<username>@gerrit.wikimedia.org:29418/<main_project>/<project>.git

UI:

  • Right click in Windows Explorer and select "Git clone"
  • Fill in Url (ssh://<username>@gerrit.wikimedia.org:29418/analytics/reportcard.git) and Directory (some not-yet-existing or empty directory). Select "Load Putty key" and navigate to where your private key resides.

From then on, use a command prompt for further commands. First navigate to the location of the repository, then:

  • git checkout -b mytestbranch (or another name)
  • ...edit...
  • git add <filename> (depends on whether you added new files)
  • git commit -a
  • git-review
  • (if necessary) git checkout master

Books, guides, tutorials, documentation, etc.

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=Help:Git&oldid=3512"