Amarok/Development/Git
Git is a distributed revision control system, and the system currently used by Amarok (since switching from SVN in 2010). Thanks to Ian for the initial git information and for being the resident Git expert.
Initial Setup
User Config (IMPORTANT!!!)
If you plan on ever pushing a commit to main repository, be sure to set your name and e-mail for commit messages:
git config --global user.name "John Doe" git config --global user.email "[email protected]"
The above two commands will set your name and e-mail in Git (globally). This will allow Git to automatically tag all of your commits with your name and e-mail address.
Getting Amarok
The Amarok source is currently hosted on gitweb.kde.org. To view the revision history and the source tree, go to http://gitweb.kde.org/amarok.git. To checkout a copy of the most current source tree, run:
git clone git://anongit.kde.org/amarok.git cd amarok git remote set-url --push origin [email protected]:amarok.git
This will create a local copy of the repository under the directory amarok/ in the directory in which the command was executed. The repo will be set to pull from the fast git:// URL and push commits using SSH.
Git Basics
Getting Help
All information on this page is merely an introduction to Git. For more complete information, see
git help
You can also ask the developers on #amarok if you need more help.
Updating Your Repository
To update your local clone of the Amarok repository, please execute
git pull --rebase
This command will run git fetch to download all new commits in the remote branch, and git rebase to add them to your local clone, "replaying" any changes you may have made locally on top of the commits pulled in.
Viewing Commits
To see all of the commits in your current branch, run
git log
For a graphical view of the revision history, you can run
gitk
This program should have been installed with Git, and provides a nice graphical view of the revision history.
Committing Changes
git status # A summary of which files are changed/new/deleted/etc. git diff # Show the actual changes git commit -a # Commit all current changes
After the last command, Git will open a text editor to allow you to add the commit message. Please write a concise, yet descriptive, summary of the changes included in the commit, then save the file and exit. The option "-a" tells Git to include all changes made to already-existing files. This includes modifications and file deletes. It does not, however, encompass new files. To tell Git to include new files, you have to explicitly run
git add /path/to/new/file1 /path/to/new/file2 ...
before running git commit. To commit only changes made to certain files, you can similarly run git add with the paths of the files whose changes you do want to commit. You can also try either of the following for a more interactive method of adding changes:
git add --interactive git add --path # Essentially the same, but jumps directly to the patch subcommand
If you have access to the Amarok repository, you can then run
git push
to push your local changes to the remote Amarok repository.
Branching
One of Git's greatest strengths lies in branching. If are planning to make complicated changes to the source code, you can easily create a private branch, track your changes in the branch, and get the changes working before committing the whole thing to the main Amarok Git repository.
Creating a New Branch
By default, your local clone of the Amarok repository lies in the "master" branch. To create a private branch from this one:
git branch NewBranchName # Create the new branch, with name "NewBranchName" git checkout NewBranchName # Switch to the new branch git checkout master # Switch back to the master branch
To see a list of all of your branches:
git branch
The branch with an asterisk before it is the one you are currently working in.
Updating a Private Branch
To update your private branch with the latest commits in master,
git rebase master NameOfPrivateBranch
You may need to resolve conflicts between local changes and remote commits at this point. See git-rebase ("git help rebase") for more information.
Merging a Branch into master
To commit changes in a branch to the main Git repository, your should first update your private branch to the latest SVN sources (see above). Then you can merge the private branch into the master branch and commit it to the SVN repository:
git checkout master git merge --squash MYBRANCH # merge MYBRANCH into master as a single commit git commit git push
After you've merged the changes from a branch into the master, you can delete the branch:
git branch -d MYBRANCH
If you want to keep using the branch after merging its changes into the master, the easiest thing to do is to delete it and recreate it. If you don't want to do that, you can run:
git checkout MYBRANCH git rebase master git rebase --skip # repeat until MYBRANCH is up to date
Conflicts
Work through conflicted files by opening them in your mergetool (opendiff, kdiff3, etc.) and choosing left/right chunks. The merged result is staged for commit.
git mergetool
For binary files or if mergetool won't do, resolve the conflict(s) manually and then do:
git add <file1> [<file2> ...]
Once all conflicts are resolved and staged, commit the pending merge with:
git commit
Tricks 'n Tips
Oh Shit: Undo
You've made some changes to a file(s) and you've decided you want to scrap all the work.
git checkout /path/to/file
Abandon everything since your last commit. This command can be DANGEROUS. If merging has resulted in conflicts and you'd like to just forget about the merge use this command.
git reset --hard
Undo your most recent successful merge and any changes that occurred after. Useful for forgetting about the merge you just did. If there are conflicts (the merge was not successful), use "git reset --hard" (above) instead.
git reset --hard ORIG_HEAD
Undo your last commit
git reset --soft HEAD^
You committed something to svn but now you want to take it back:
git log # grab the commit hash you want to revert git revert <commit hash> git svn dcommit
Ignoring Files/Directories
There are certain folders/files which may not require tracking, and git will say on every checkout and status what these files are, which can be a nuisance.
Solution:
- Goto
./amarok/.git/info/exclude./amarok/.gitignore - Add directories/files desired to be ignored. Wildcards are OK (and encouraged).
Example exclude:
/src/context/animators /src/context/plasma /Doxyfile /src/amarok-build
Ramblurr's .gitignore
*~ src/context/animators /src/context/plasma *.kdev* .gitignore tags Doxyfile *#*# .#*
Colorize Output
Treat yourself to some color. Add the following to ~/.gitconfig
[color] branch = auto diff = auto status = auto [color "branch"] current = yellow reverse local = yellow remote = green [color "diff"] meta = yellow bold frag = magenta bold old = red bold new = green bold [color "status"] added = yellow changed = green untracked = cyan