While logged in, visit Piwik’s github repo. In the upper right corner there will be a Fork button. Click it. Github will copy the repository and place the new forked repository in your account.
When committing, git will need to know your username & email. To set them, run the following commands:
git config --global user.name $username git config --global user.email $email
Also, if you have a favorite text editor you’d like to use when creating commit messages, you can configure git to launch it when you commit changes. For example:
git config --global core.editor my-text-editor
To be able to work on Piwik you’ll need to have a copy of your forked repository on your computer. To copy your forked repository, run the following command after replacing myusername with your github username:
git clone https://github.com/myusername/piwik piwik
This will copy the entire forked repository (including all history) to the piwik folder on your hard drive.
Now, we’ll run one more command so git remembers the original Piwik repository in addition to your fork:
git remote add upstream https://github.com/piwik/piwik
This will save https://github.com/piwik/piwik as a remote and name it upstream.
Now that you have a copy of the latest Piwik source code, you can start modifying it. For this section, let’s assume there’s a bug that you found and want to fix.
Before you start coding, you should make sure to keep your changes separate from the master branch. This will make it much easier to track the changes specific to your feature since your changes won’t be mixed with any of your other changes or new commits to the master branch from other developers.
We’ll give our new branch a name, bugfix, that describes what we’re doing so we can recognize it later. To add a new branch, run the following command:
git checkout -b bugfix
The checkout command will create a new branch if the -b option is supplied, otherwise it will try and load an existing branch.
Once you’ve created a branch, you have a place to start working on the feature. There’s nothing special about this part of the process, just fix the bug or finish the feature you’re working on.
If you’re working on something more complex than a bugfix, though, you may have the need to keep your new branch updated with changes from the main repository. Keeping your branch up to date is a two-three step process. First, on your master branch (remember to use the checkout command to switch branches), pull changes from the main Piwik repository, nicknamed upstream:
git pull upstream master
Then, on your new branch (bugfix for this tutorial), merge with master:
git merge master
If there are conflicts, git will list them and tell you to fix them and then commit. To fix commits, you can do it manually in a text editor (which is usually pretty simple), or you can let git launch a GUI by calling:
What git will launch depends on what diff-ing tools you have installed.
After you fix conflicts, you have to let git know the conflicts are gone and re-commit. To do that, you run git add on the files with conflicts then git commit. More on how to add files and commit in the next section.
Now that you’ve finished the bug fix or new feature (or just part of it), it’s time to save your changes. First, you want to commit them to your local clone of your github repository. To do that, run the following command:
git commit -a -m "Fixed a bug."
This will commit every modified file and use “Fixed a bug.” as the commit message. If you have new files to add, run the following command before committing:
git add /path/to/file
If you only want to commit some files and not every modified file, run the above command for every modified file you want to commit, then run:
git commit -m "..."
The -a option (which we used above) tells git to automatically commit every file that has been modified, not just the specific files that have been used with git add.
If you delete a file, git will notice it is deleted, but you still have to git add the file or use the -a option to commit the deletion.
Now that you’ve committed your changes locally, you need to make them visible on your github repository. This is done with one command:
git push origin bugfix
This command will push every change you made on the bugfix branch to the origin remote (which is your github repository).
You can also use this command to publish changes to your master branch by running:
git push origin master
Your changes are published, which means you can now send a pull request to the main Piwik project. To do this, visit your forked repository in a browser, and select the bugfix branch in the branch selector (located right above the directory listing on the left side of the page). Then click the Pull Request button in the middle of the top of the page.
On this screen you’ll be able to see exactly what changes you’ve made by looking at your commits and at what files have been changed. You can use this as an opportunity to review your own code if you like.
Once you’re ready to create the pull request, write a description of the pull request and any notes that are important for the person who will review your code, and then click Send pull request. This will create a new pull request which you will be able to find and view here.
Once your pull request is public, someone will review it and leave comments regarding what should be changed. You can then make changes, commit them and then push them to your remote repository (origin) and they will automatically be shown in the pull request.
Your pull request has been reviewed and deemed worthy: it has been merged with Piwik’s master branch. Now, you need to sync your fork with the main repo. This is the same process that was described in Work on Feature:
# first make sure you're on master git checkout master # now we'll pull in changes from 'upstream' the original Piwik repository git pull upstream master # then we'll push those changes to 'origin' git push origin master
And finally, now that the changes are part of Piwik, there’s no need for your feature branch, so we’ll delete it:
git branch -D bugfix
List all branches
Create a new branch:
git checkout -b $branch_name
Checkout an existing branch:
git checkout $branch_name
Delete existing branch:
git branch -D $branch_name
Delete branch in remote repository
# first delete the branch locally git branch -D $branch_name # then delete the remote branch by running this: git push $remote_name :$branch_name
Revert all changes that haven’t been committed:
git reset --hard
Revert changes to one specific file:
git checkout -- path/to/file
Commit all modified files + all git added files:
git commit -a -m "commit message goes here"
-m is optional.
Add specific changes and commit only those changes:
git add path/to/new/file git add path/to/deleted/file git add path/to/modified/file git commit -m "Added new file, deleted old file & modified existing file."
See status of all files:
See log of all commits:
git revert $commit_hash
You can get a commit hash by looking through the commit log.
Note: reverting changes through the command can sometimes get complicated, especially if you’re reverting a merge.
Push changes to remote:
git push $remote_name $branch_name
Pull changes from remote:
git pull $remote_name $branch_name
Merge a branch with the currently checked out branch:
git merge $other_branch
Merge a branch but make it look like one commit:
git merge --squash $other_branch git commit # in the editor, rewrite the commit message