[FFmpeg-devel] [GIT] ready by the weekend

[Anton Khirnov]

On Thu, Nov 18, 2010 at 03:02:00PM +0100, Luca Barbato wrote:
> On 11/18/2010 11:58 AM, Luca Barbato wrote:
> > On 11/18/2010 11:07 AM, Michael Niedermayer wrote:
> >> I think wiki is not a good idea as resting place for the final document.
> >> maybe iam paranoid ...
> > 
> > We need a place to start putting it together.
> > Then it can live in the source tree or web tree.
> 
> Here the initial diff to the svn-howto.txt
> 
> Once I complete all the section it could live in the ffmpeg docs dir.
> 
> lu
> 
ataching the complete file would be much more readable IMO

>  
> -    svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ <target>
> +    git clone git at git.videolan.org:ffmpeg <target>
this will only work for people with an account, i think we should put
the public repo here
> +2.a Rebasing your local branches:
>  
> +    git fetch && git rebase origin
git pull --rebase
is equivalent and shorter
> +
> +  fetches the changes from the main repository and replays your local changes
> +  over it. This is useful to keep all your local changes at the top of your
> +  tree.
it's better to say 'commits' instead of changes here, people coming from
svn might be confused by commits being local.
> -  Don't do a lot of cut'n'paste from one file to another without a very good
> -  reason and discuss it on the mplayer-dev-eng mailing list first. It will make
> -  those changes hard to trace.
> +  git revert will generate a revert commit. This will not make the faulty
> +  commit disapper from the history.
disapper->disappear
>  
> -  Such actions are useless and treated as cosmetics in 99% of cases,
> -  so try to avoid them.
> +    git reset <commit>
>  
> +  git reset will uncommit the changes till <commit> rewriting the current
> +  branch history. It should be used on local branches to cleanup them for
> +  pull/merge requests.
>  
> -9. Reverting broken commits
> +    git commit --amend
>  
> -  There are 2 ways to reverse a change, they differ significantly in what they
> -  do to the repository.
> -  The recommit old method:
> -    svn merge
> -    svn ci <file>
> -    This simply changes the file(s) back to their old version locally and then
> -    the change is committed as if it were a new change.
> -  The svn copy method
> -    svn rm <file>
> -    svn cp -r<good revision> svn://svn.mplayerhq.hu/mplayer/trunk/[<path>/]<file> <file>
> -    svn ci <file>
> -    This simply removes the file and then copies the last good version with
> -    its history over it. This method can only be used to revert the n last
> -    commits but not to revert a bad commit in the middle of its history.
> -  Neither method will change the history, checking out an old version will
> -  always return exactly that revision with all its bugs and features. The
> -  difference is that with the svn copy method the broken commit will not be
> -  part of the directly visible history of the revisions after the reversal
> -  So if the change was completely broken like reindenting a file against the
> -  maintainers decision, or a change which mixed functional and cosmetic
> -  changes then it is better if it is not part of the visible history as it
> -  would make it hard to read, review and would also break svn annotate.
> -  For the example of a change which mixed functional and cosmetic parts they
> -  should of course be committed again after the reversal but separately, so one
> -  change with the functional stuff and one with the cosmetics.
> -  OTOH if the change which you want to reverse was simply buggy but not
> -  totally broken then it should be reversed with svn merge as otherwise
> -  the fact that the change was bad would be hidden.
> -  One method to decide which reversal method is best is to ask yourself
> -  if there is any value in seeing the whole bad change and its removal
> -  in SVN vs. just seeing a comment that says what has been reversed while
> -  the actual change does not clutter the immediately visible history and
> -  svn annotate.
> -  If you are even just slightly uncertain how to revert something then ask on
> -  the mplayer-dev-eng mailing list.
> +  allows to amend the last commit details quickly.
>  
added a paragraph about interactive rebase.


-- 
Anton Khirnov
-------------- next part --------------

About Git write access:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before everything else, you should know how to use GIT properly.
Luckily Git comes with excellent documentation.

  git --help
  man git

shows you the available subcommands,

  git <command> --help
  man git-<command>

shows information about the subcommand <command>.

The most comprehensive manual is the website Git Reference

http://gitref.org/

For more information about the Git project, visit

http://git-scm.com/

Consult these resources whenever you have problems, they are quite exhaustive.

You do not need a special username or password.
All you need is to provide a ssh public key to the Git server admin.

What follows now is a basic introduction to Git and some FFmpeg-specific
guidelines. Read it at least once, if you are granted commit privileges to the
FFmpeg project you are expected to be familiar with these rules.



I. BASICS:
==========

0. Get GIT:

  You can get git from http://git-scm.com/


1. Cloning the source tree:

    git clone git://git.videolan.org/ffmpeg <target>

  This will put the FFmpeg sources into the directory <target>.


2. Updating the source tree to the latest revision:

    git pull

  pulls in the latest changes from the repository to your local master branch.

2.a Rebasing your local branches:

    git pull --rebase

  fetches the changes from the main repository and replays your local commits
  over it. This is useful to keep all your local changes at the top of your
  tree.


3. Adding/removing files/directories:

    git add <filename/dirname>
    git rm [-r] <filename/dirname>

  GIT needs to get notified of all changes you make to your working
  directory.


4. Showing modifications:

    git diff <filename(s)>

  will show all local modifications in your working directory as unified diff.


5. Inspecting the changelog:

    git log <filename(s)>

  You may also use the graphical tools like gitview or gitk or the web
  interface available at http://git.videolan.org

6. Checking source tree status:

    git status

  detects all the changes you made and lists what actions will be taken in case
  of a commit (additions, modifications, deletions, etc.).


7. Committing:

    git diff --check

  to doublecheck your changes before committing them to avoid trouble later
  on. All experienced developers do this on each and every commit, no matter
  how small.
  Every one of them has been saved from looking like a fool by this many times.
  It's very easy for stray debug output or cosmetic modifications to slip in,
  please avoid problems through this extra level of scrutiny.

  For cosmetics-only commits you should get (almost) empty output from

    git diff -wb <filename(s)>

  Also check the output of

    git status

  to make sure you don't have untracked files.

    git add [-i|-p] <filenames/dirnames>

  Git will select the changes to the files for commit. Optionally you can use
  the interactive or the patch mode to select hunk by hunk what should be
  added to the commit.

    git commit

  Git will commit the selected changes to your current local branch.

  You will be prompted for a log message in an editor, which is either
  set in your personal configuration file throught

    git config core.editor

  or set by one of the following environment variables:
  GIT_EDITOR, VISUAL or EDITOR.

  Log messages should be concise but descriptive. Explain why you made a change,
  what you did will be obvious from the changes themselves most of the time.
  Saying just "bug fix" or "10l" is bad. Remember that people of varying skill
  levels look at and educate themselves while reading through your code. Don't
  include filenames in log messages, Git provides that information.


8. Renaming/moving/copying files or contents of files:

  Git automatically tracks such changes, making those normal commits.

    mv/cp path/file otherpath/otherfile

    git add .

    git commit

  Do not move, rename or copy files of which you are not the maintainer without
  discussing it on the mailing list first!

9. Reverting broken commits

    git revert

  git revert will generate a revert commit. This will not make the faulty
  commit disappear from the history.

    git reset <commit>

  git reset will uncommit the changes till <commit> rewriting the current
  branch history.

    git commit --amend

  allows to amend the last commit details quickly.

    git rebase -i origin/master

  will replay local commits over the main repository allowing to edit,
  merge or remove some of them in the process.

  Note that the reset, commit --amend and rebase rewrite history, so they
  should only be used on commits that haven't been published yet!

10. Preparing a patchset.

    git format-patch <commit> [-o directory]

  will generate a set of patches out of the current branch starting from
  commit. By default the patches are created in the current directory.

11. Sending patches for review

    git send-email <commit list|directory>

  will send the patches created by git format-patch or directly generates
  them. All the email fields can be configured in the global/local
  configuration or overridden by command line.

12. Pushing changes to remote trees

    git remote add <name> <url>

  Will add additional remote with a name reference

    git push <remote> <refspec>

  Will push the changes to the remote repository. Omitting refspec makes git
  push update all the remote branches matching the local ones.

    git push

  Will push the changes to the default remote (origin).
  Git will prevent you from pushing changes if the local and remote trees are
  out of sync. Refer to 2 and 2.a to sync the local tree.

Contact the project admins <root at mplayerhq dot hu> if you have technical
problems with the GIT server.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20101118/6e4a3487/attachment.pgp>