Git for Apache Flex Guide

Welcome!

As the title suggests, this page is dedicated to the use of git as the VCS for the Apache Flex project. This means that everything that is described on this page is specific to this project and may differ from the git workflow you're used to or have seen described on the internet. This also means that the content of this page is the consensus of the contributors on the Apache Flex Dev mailing list. If you see anything here that you think might need changing or clarifying, please discuss it on the list first.Now, on to the matter at hand: using git to get work done on the Apache Flex project.

A little history

The VOTE that made it all happen: http://markmail.org/message/ajlskznzec4wqda2

The JIRA ticket that made it all happen: https://issues.apache.org/jira/browse/INFRA-5549

First: know git

If you are not familiar with the basics of git, stop here. These pages assume a working knowledge of the terminology and commands that git uses. There are excellent tutorials/references available on the internet, some of which are listed here: tutorials and other resources.

Configuring Git

You can customize your Git configuration using

git config

see https://www.kernel.org/pub/software/scm/git/docs/git-config.html or editing your <USER_HOME>\.gitconfig, here is an example of what it might look like:

[user]
	name = Frédéric THOMAS
	email = fthomas@apache.org
[core]
	excludesfile = .gitignore
[push]
	default = simple
[merge]
	tool = p4merge
[mergetool "p4merge"]
	path = C:\\Program Files\\Perforce\\p4merge.exe
[color]
	diff = auto
	status = auto
	branch = auto
[alias]
  co = checkout
  ci = commit
  st = status
  br = branch
  hist = log --pretty=format:\"%h %ad | %s%d [%an]\" --graph --date=short --decorate
  type = cat-file -t
  dump = cat-file -p
  cdel = ls-files --deleted
  dodel = ls-files --deleted | xargs git rm
  show = show --format=full
  auf = update-index --assume-unchanged
  nauf = update-index --no-assume-unchanged

The mergetool configuration is used when you want an external diff/merge tool to be called while resolving conflicts.

To set another merge tool, e.g. WinMerge, simply do:

[merge]
    tool = winmerge
[mergetool "winmerge"]
    path = <PATH_TO WINMERGE>\\winmerge.exe

You can create Git aliases too, don't forget to escape double quotes, here an explanation of some of them:

• hist: Shows a graph of the log history.
• type: Following by a hash, shows you the type of object corresponding to this hash.
• dump: Following by a hash, shows you the content corresponding to this hash.
• cdel: Shows you the files deleted in your working tree not added to staged area.

• dodel: Add the deleted files to your staged area, you can use this command if you didn't use

  git rm <fileToDelete>

• auf: Does a git show showing up every parents
• auf: Assumes the file/directory passed as parameter didn't change, really handy to avoid Git to commit your changed file/directory.
• nauf: Does the opposite of 'auf'

Git and Apache Flex

In the same VOTE that decided the use of git as VCS, the project also chose an official working model: Gitflow. Gitflow is a git branching model, initially proposed by Vincent Driessen. You can read all about on his blog: http://nvie.com/posts/a-successful-git-branching-model/. Everything that follows on this page should be interpreted in the context of Gitflow.

First things first

• read this: https://git-wip-us.apache.org/#committers-getting-started
• create setting in git: https://git-wip-us.apache.org/#line-endings

The repositories

• Full, automated list: https://git-wip-us.apache.org/repos/asf?s=flex
• SDK: https://git-wip-us.apache.org/repos/asf/flex-sdk.git
• TLF: https://git-wip-us.apache.org/repos/asf/flex-tlf.git
• FALCON: https://git-wip-us.apache.org/repos/asf/flex-falcon.git
• ASJS: https://git-wip-us.apache.org/repos/asf/flex-asjs.git
• Utilities: https://git-wip-us.apache.org/repos/asf/flex-utilities.git
• Whiteboard: https://git-wip-us.apache.org/repos/asf/flex-whiteboard.git

Initial setup

1) Create a root directory for your Apache Flex repos; let's name it "apacheFlex". For the next steps, make sure to move your command line to that directory.

2) Clone the repo of your choice (I'll use the SDK in this example) to a sub directory "sdk":

git clone https://git-wip-us.apache.org/repos/asf/flex-sdk.git sdk

3) Move the command line to the new subdirectory:

cd sdk

4) Change to the develop branch (remember, the default branch after cloning is master):

git checkout develop

Working on the code

1) Now you're ready to do some work. Let's say you want to fix JIRA issue FLEX-12345. You start by creating a new local branch, called a feature branch in Gitflow:

git checkout -b FLEX-12345

The -b switch creates a feature branch from develop.

2) Before you start work, get your feature branch up to date with the remote develop branch to pick up any changes made there:

git pull --rebase origin develop

If there are any conflicts after calling this command, resolve those before starting your work.

3) After you've completed your work:

git add <Your added/modified files> / git rm <file to be deleted> / git add -u (Add all untracked/modified/removed files to the staged area)
git commit -m "Flex-12345: Fixed this"

This will stage all changed files and commit them to the local repository.

4) Perform any local check to verify your fix didn't break anything (e.g. build the SDK, run Mustella).

5) When you're ready to share your fix with the rest of the world:

git pull --rebase origin develop

This brings your feature branch up to date with any changes on the remote develop branch. If there are any conflicts, resolve and commit them before continuing.

6) Switch to the local develop branch and merge the changes from the feature branch:

git checkout develop
git merge --no-ff Flex-12345

If you have only one commit don't use --no-ff.

7) Check your git log to see if everything is correct; if needed consult the development mailing list on how to resolve.

git log --pretty=format:"%h %ad | %s%d [%an|%an]" --graph --date=short

8a) Committers: push your changes to the remote develop branch:

If some time has elapsed between your merge and the push you willing to do (This will update your files preserving your merge. If there are any conflicts, resolve and commit them before continuing):

git fetch
git rebase -p

then:

git push

8b) Everyone else: create a patch

git format-patch develop --stdout > Flex-12345.patch

9) Optional step: If all went well, your local feature branch is no longer needed, so you can delete it:

git branch -d Flex-12345

FAQ:

1. How do I revert/discard a changed file ?

Whatever you modified/deleted/renamed a file/directory and want it to be restored from the HEAD, use:

git checkout <Original file/directory name>

And then delete the remaining new file/directory in case where you reverted after renaming.

To restore a file from the staged area:

git checkout -- <file name>

If you want to discard all the work you did in your branch since the last commit, use:

git reset --hard HEAD

If you want to revert the last commit without to loose your work (this will move the HEAD to the commit c-1 and restore the files committed with the last commit in your working area), use:

git reset --soft HEAD~1

If you find a error in a committed file not yet publish, use:

git rebase -i

to re-edit the changes.

I want locally remove the removed remote branches, use:

git fetch -p origin

If you want to revert on the remote branch, use:

git checkout <BRANCH>
git revert <HASH> (HASH: can be obtain from 'git log')
git push

Use the "-m 1" flag if you want to revert a merge commit, it'll generate a new commit that undoes all of the changes introduced in <HASH>, then apply it to the current branch and push it.

If you want to reset a remote branch to a commit or a tag, use:

git checkout <BRANCH>
git reset --hard <HASH/TAG> (HASH/TAG: can be obtain from 'git log' or 'git tag')
git push --force

It overwrites existing history in the remote repo and may cause problems for other developers who have this repo checked out, warn them first.

I want to know in which branch is a commit (will list all branches where this commit is contained into), use:

git branch --contains <HASH> (HASH: can be obtain from 'git log')

I want to see the commits contains in develop but not in master:

git log origin/develop --not origin/master

After Easter, it's time to pick cherries (haha)
I want to get a commit which is on another branch (note that the HASH will change), use:

git cherry-pick <HASH> (HASH: can be obtain from 'git log')

Release Manager
1. How do I branch to make a release?
2. How do I work out what's included in the release?
3. How do I merge fixes from develop in the release?
4. How do I tag the release?
5. How do I merge the release back into develop?
6. How do I apply hot fixes to the release?

ANT:

- since git branches use the same physical path for each branch, the build files that rely on a specific branch (e.g. Falcon relies on the develop branch of the SDK) MUST be accompanied with plenty of documentation that states which branch must be checked out for the build to properly function.

GITHUB:

- is it in sync and if so, do we accept pull requests (dev-faq on the website)?

Project specific instructions:

How to build Falcon(JS/Jx): build SDK, build Falcon etc...

Goodies:

- empty directories in git: create a .gitignore inside the directory that contains these four lines:

# Ignore everything in this directory
*
# Except this file
!.gitignore

- checkout only part of repo (sparse checkout): http://jasonkarns.com/blog/subdirectory-checkouts-with-git-sparse-checkout/ (in practice: http://markmail.org/message/dg7hplezkzwiroes, with the comment: http://markmail.org/message/c6okcnaytmpry7j2)