Amarok/Development/Git: Difference between revisions

From KDE Community Wiki
(Created page with "Category:Amarok Category:Development Git is a distributed revision control system, and the system currently used by Amarok (since switching from SVN in 2010). Thanks ...")
 
 
(9 intermediate revisions by 4 users not shown)
Line 10: Line 10:


== Getting Amarok ==
== Getting Amarok ==
The Amarok source is currently hosted on [http://gitweb.kde.org/ 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:
To view the revision history and the source tree, go to https://invent.kde.org/kde/amarok. To checkout a copy of the most current source tree, run:
  git clone git://anongit.kde.org/amarok.git
  git clone https://invent.kde.org/kde/amarok.git
  cd amarok
  cd amarok
  git remote set-url --push origin git@anongit.kde.org:amarok.git
  git remote set-url --push origin git@invent.kde.org:kde/amarok.git
This will create a local copy of the repository under the directory '''<tt>amarok/</tt>''' 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.
This will create a local copy of the repository under the directory '''<tt>amarok/</tt>''' 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.


Line 25: Line 25:
To update your local clone of the Amarok repository, please execute
To update your local clone of the Amarok repository, please execute
  git pull --rebase
  git pull --rebase
This command will run <tt>git fetch</tt> to download all new commits in the remote branch, and <tt>git rebase</tt> to add them to your local clone, "replaying" any changes you may have made locally '''on top''' of the commits pulled in.
This command will run <tt>git fetch</tt> to download all new commits in the remote branch, and <tt>git rebase</tt> to add them to your local clone, "replaying" any changes you may have made locally '''on top''' of the commits pulled in. To save your time typing --rebase every time when pulling from master, issue
git config branch.master.rebase true


== Viewing Commits ==
== Viewing Commits ==
Line 37: Line 38:
  git status    # A summary of which files are changed/new/deleted/etc.
  git status    # A summary of which files are changed/new/deleted/etc.
  git diff      # Show the actual changes
  git diff      # Show the actual changes
Check HACKING/commitchecklist.txt
  git commit -a  # Commit all current 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 "<tt>-a</tt>" 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
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 "<tt>-a</tt>" 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
Line 45: Line 47:
If you have access to the Amarok repository, you can then run
If you have access to the Amarok repository, you can then run
  git push
  git push
to push your local changes to the remote Amarok repository.
to push your local changes to the remote Amarok repository, but always check that you're going to push right things before with gitk or a similar tool.


== Branching ==
== Branching ==
Line 58: Line 60:
  git branch
  git branch
The branch with an asterisk before it is the one you are currently working in.
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 <tt>master</tt>,
git rebase master NameOfPrivateBranch
You may need to resolve conflicts between local changes and remote commits at this point.  See [http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html git-rebase] ("<tt>git help rebase</tt>") for more information.


=== Merging a Branch into <tt>master</tt> ===
=== Merging a Branch into <tt>master</tt> ===
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:
Merging your branch to master is easy, following commands will merge a branch into master, keeping its history, making sure the merge commit is created and embedding a list of commits into the merge commit text:
  git checkout master
  git checkout master
  git merge --squash MYBRANCH # merge MYBRANCH into master as a single commit
  git merge --no-ff --log MYBRANCH
git commit
git push


After you've merged the changes from a branch into the master, you can delete the branch:
After you've merged the changes from a branch into the master, you can delete the branch:
  git branch -d MYBRANCH
  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:
=== Maintaining a Long-lived Branch ===
  git checkout MYBRANCH
This section deals with some recommended techniques when dealing with long-lived feature branches, perhaps entire GSoC projects.
git rebase master
 
  git rebase --skip # repeat until MYBRANCH is up to date
'''Initial Branching'''
 
Be sure not to get unlucky by choosing an unstable/buggy commit as you're branching point, because you'll may be using that for months. Test that features you'll be affecting work as expected.
 
'''Backup & Publish Code Using a Personal Clone'''
 
To backup your work and make it accessible for interested parties, you are encouraged to [[Sysadmin/GitFAQ#Personal_clones_of_project_repositories|create a personal Amarok repo clone on git.kde.org]]. Then add it as another remote to your Amarok repository
git remote add personal [email protected]:clones/amarok/<your identity.kde.org login>/<clone name, perhaps just amarok>
and push your feature branch to it (use the -u option first time so that git remembers branch upstream)
git checkout gsoc    # assuming your feature branch is called gsoc
git push -u personal gsoc
 
'''Don't Merge from <tt>master</tt> to a Feature Branch'''
 
Merging from master into a feature branch creates a messy "loopy" history, which is generally frowned upon, because it's a structure without semantics. Rebasing a long-lived feature branch
git rebase master gsoc
should be preferred to merging upstream master repeatedly into it, on the other hand rebasing a published branch will create pain for those who have pulled it.
 
Unless you depend on some new features being added to upstream master (like API changes, or bugfixes), you don't need to rebase often, or even at all.
 
'''Get your code reviewed'''
 
Especially in case of GSoC, we recommend to submit weekly diffs to reviewboard (assign to whole amarok team) so that everyone is up-to-date with current advances. Thanks to ''rbtools'', git tags and aliases this can be easy. With following alias in your [amarok repo]/.git/config
  [alias]
    gsoc-review = !post-review --summary '<NAME> GSoC week <NUMBER> (squashed commits, recent on top)' --guess-description --username=<your username> --branch gsoc --parent=gsoc-review-base --open --target-groups=amarok
it is easy as maintaining git tag <tt>gsoc-review-base</tt> pointed to latest revision you've submitted and issuing
  git gsoc-review
every week or so. These review requests are not meant to be merged (make it clear) and they can be closed as discarded after some time, provided that you've resolved any possible issues spotted by other developers.
 
'''Final merging'''
 
...is covered by ''Merging a Branch into master'' above, just keep in mind that it is usual to submit a final review request with '''all''' the changes and to retain development history as mentioned above. The merge commit is also a place to add any missing BUG:, FIXED-IN: etc. tags and ChangeLog entries if it wasn't already done during feature branch development.


== Conflicts ==
== Conflicts ==
Line 88: Line 114:
Once all conflicts are resolved and staged, commit the pending merge with:
Once all conflicts are resolved and staged, commit the pending merge with:
  git commit
  git commit
= Using Phabricator =
Amarok uses [https://phabricator.kde.org/ Phabricator] for code changes, please see the [https://community.kde.org/Infrastructure/Phabricator Community Wiki page] about using Phabricator]


= Tricks 'n Tips =
= Tricks 'n Tips =
Line 102: Line 132:
Undo your last commit
Undo your last commit
  git reset --soft HEAD^
  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 ==
== 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.
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. See
 
  man gitignore
Solution:
 
# Goto <strike>./amarok/.git/info/exclude</strike> ./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 ==
== Colorize Output ==
Line 138: Line 141:


  [color]
  [color]
     branch = auto
     ui = auto
    diff = auto
    status = auto
[color "branch"]
    current = yellow reverse
    local = yellow
    remote = green
  [color "diff"]
  [color "diff"]
     meta = yellow bold
     whitespace = red reverse
    frag = magenta bold
    old = red bold
    new = green bold
[color "status"]
    added = yellow
    changed = green
    untracked = cyan


== Further Reading ==
== Further Reading ==
# [http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html "Git Magic" Tutorial]
# [http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html "Git Magic" Tutorial]
# [http://cheat.errtheblog.com/s/git/ Reference Sheet]
# [http://cheat.errtheblog.com/s/git/ Reference Sheet]

Latest revision as of 10:11, 12 April 2020

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

To view the revision history and the source tree, go to https://invent.kde.org/kde/amarok. To checkout a copy of the most current source tree, run:

git clone https://invent.kde.org/kde/amarok.git
cd amarok
git remote set-url --push origin [email protected]:kde/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. To save your time typing --rebase every time when pulling from master, issue

git config branch.master.rebase true

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

Check HACKING/commitchecklist.txt

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, but always check that you're going to push right things before with gitk or a similar tool.

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.

Merging a Branch into master

Merging your branch to master is easy, following commands will merge a branch into master, keeping its history, making sure the merge commit is created and embedding a list of commits into the merge commit text:

git checkout master
git merge --no-ff --log MYBRANCH

After you've merged the changes from a branch into the master, you can delete the branch:

git branch -d MYBRANCH

Maintaining a Long-lived Branch

This section deals with some recommended techniques when dealing with long-lived feature branches, perhaps entire GSoC projects.

Initial Branching

Be sure not to get unlucky by choosing an unstable/buggy commit as you're branching point, because you'll may be using that for months. Test that features you'll be affecting work as expected.

Backup & Publish Code Using a Personal Clone

To backup your work and make it accessible for interested parties, you are encouraged to create a personal Amarok repo clone on git.kde.org. Then add it as another remote to your Amarok repository

git remote add personal [email protected]:clones/amarok/<your identity.kde.org login>/<clone name, perhaps just amarok>

and push your feature branch to it (use the -u option first time so that git remembers branch upstream)

git checkout gsoc     # assuming your feature branch is called gsoc
git push -u personal gsoc

Don't Merge from master to a Feature Branch

Merging from master into a feature branch creates a messy "loopy" history, which is generally frowned upon, because it's a structure without semantics. Rebasing a long-lived feature branch

git rebase master gsoc

should be preferred to merging upstream master repeatedly into it, on the other hand rebasing a published branch will create pain for those who have pulled it.

Unless you depend on some new features being added to upstream master (like API changes, or bugfixes), you don't need to rebase often, or even at all.

Get your code reviewed

Especially in case of GSoC, we recommend to submit weekly diffs to reviewboard (assign to whole amarok team) so that everyone is up-to-date with current advances. Thanks to rbtools, git tags and aliases this can be easy. With following alias in your [amarok repo]/.git/config

[alias]
   gsoc-review = !post-review --summary '<NAME> GSoC week <NUMBER> (squashed commits, recent on top)' --guess-description --username=<your username> --branch gsoc --parent=gsoc-review-base --open --target-groups=amarok

it is easy as maintaining git tag gsoc-review-base pointed to latest revision you've submitted and issuing

git gsoc-review

every week or so. These review requests are not meant to be merged (make it clear) and they can be closed as discarded after some time, provided that you've resolved any possible issues spotted by other developers.

Final merging

...is covered by Merging a Branch into master above, just keep in mind that it is usual to submit a final review request with all the changes and to retain development history as mentioned above. The merge commit is also a place to add any missing BUG:, FIXED-IN: etc. tags and ChangeLog entries if it wasn't already done during feature branch development.

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

Using Phabricator

Amarok uses Phabricator for code changes, please see the Community Wiki page about using Phabricator]

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^

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

man gitignore

Colorize Output

Treat yourself to some color. Add the following to ~/.gitconfig

[color]
   ui = auto
[color "diff"]
   whitespace = red reverse

Further Reading

  1. "Git Magic" Tutorial
  2. Reference Sheet