Paranoid RPG (Repo Pleb Guide)
This should act as a basic guide for improving your workflow while using repo/git
This takes into consideration that you already have the repo tool installed, initialized and synced.
You are still encouraged to read up on how Git actually works as this attempts to keep simple layman terms
Useful guide - http://source.android.com/source/developing.html
- A pointer to the current active commit (top commit of the current branch)
- Alternate working path, keeps it's own history and modifications
- Git keeps track of all file changes regardless of if they are committed or not.
This allows you to select which changes you want to commit without having to first revert your changes.
To stage a change, you'll need to execute the command git add
- Once you perform git add on a modified file, it's now staged and ready for committing.
You can build and test modified files without actually staging or committing them
You however, cannot push upstream changes without first committing those changes
(used to create a new branch with one or more projects)
repo start branchName projectPath projectPath2 ...
(used to stage modified/new files)
git add pathAndFileName
git add .
git add pathAndFileName stages only the named file, while git add . will stage all unstaged files
(used to stage deleted files)
git rm pathAndFileName
git add -u
git rm pathAndFileName stages only the named file (to be deleted), while git add -u will stage all unstaged files that are to be deleted
(used to compare file changes, shows the diff between HEAD and the current project state)
git diff fileName
When diff is executed, if a file is not specified, it shows the difference between all files changed
The file being compared is shown at the top of the analysis, followed by it's differences
Deleted lines start with a minus (-) sign
New lines start with a plus (+) sign
Lines starting with @@ are simply line numbers within the file
Example: diff --git a/AndroidManifest.xml b/AndroidManifest.xml
Example: changing one line in AndroidManifest.xml
diff --git a/AndroidManifest.xml b/AndroidManifest.xml
index e5ce889..5b8c41e 100644
@@ -1581,7 +1581,7 @@
<action android:name="android.intent.action.MAIN" />
<action android:name="android.app.action.START_ENCRYPTION" />
- <category android:name="android.intent.category.DEFAULT" /> />
+ <category android:name="android.intent.category.DEFAULT" />
(shows the status of modified files, staged or unstaged)
(commits your staged files to the working directory)
git commit -a
git commit -m [message]
git commit --amend
This should be your standard for creating commit messages. Allows for multi-line entry for well formatted commit messages
commit -m 'commitMessage'
This is essentially a short-cut that allows you to enter a quick commit message
Allows you to amend the commit. It can be used simply to update the commit message or to include new files in a previous commit instead of creating a brand new commit.
(create a link to another repository for easy referrence)
(update your local copy of a remote branch, does not affect your working directory)
git fetch remoteAlias -branch
(brings your repository up to date with a remote repository. Updates your working directory)
git pull remoteAlias - branch
(fetches and merges files from a remote repository into your local repository)
git cherry-pick SHA
(lists all commits/commit history on your current branch)
Notes on repo syncing
- repo sync
- Create branch (repo start) <or use previously created branch>
- Do some programming/cherry-picking
- git status to see what changed
- git diff [file] to see exactly what was modified
- git add [all or selected] file(s)
- git commit -a | -m [message] | --amend to commit
Repo sync pulls in all changes from the remote repository defined in your local manifest
and update your working directory to match the state of said repository.
Firstly, git will not overwrite any commit, so don't worry about that.
However, there are two ways that repo sync handles the upstream updates.
If you work on an unnamed or non-tracking branch, repo sync leaves your HEAD and switches to the tip of the branch specified in the manifest. This makes it appear as though your changes were deleted.
If you are on a tracking branch, repo sync will rebase your commits on top of the branch tip, after updating your working directory.
(i.e., re-apply your changes after the upstream updates so you now have updated remote files plus your own commits)
Recommendation: you should create a tracking branch before committing. This does not mean every time you want to commit you should start a new branch, but, for better workflow you should have at least one main tracked branch. For testing various new features/cherry-picks its best to branch first before committing.
repo start my_branch frameworks/base
Notes on repo start
- You are automatically switched to the new branch (for the specified projects only) once repo start branch is executed.
- New branches are created based on the HEAD of the remote repo in your manifest.
- Projects not specified for the new branch (in the repo start command) will remain on their current branch.
Example: You have commits on branch 1 and you decide to create branch 2
repo start branch2 ProjectA ProjectC
Your build environment will now contain
This is important to note because if changes present in branch1/ProjectB
depend on code in branch1/ProjectA
you will run into errors if branch2/(projectA or ProjectC)
does not contain those required changes. To avoid this, simply repo start branch2/ProjectB
as well, even if you don't intend to make changes to this project on your new branch. Of course, if there are no dependencies, there is no need to branch additional projects.
- Other projects can be added to an existing branch by simply running repo start again and using the existing branch name
- If you create a tracking branch, repo sync will rebase it automatically. So you don't have to do it by hand.
Notes on cherry-picking
git fetch remoteBranch
git cherry-pick commit_SHA
login to gerrit
click the downloads tab
copy & paste cherry-pick link into the appropriate project path in terminal
Regardless of the method used, cherry-picking a commit will not always result in a clean merge.
If there is a conflict you will see a message similar to Prerecorded image for...
A bad merge does not mean bad code. It simply means your working directory is not at the same point
as the working directory used for the commit you are attempting to pick. This may be because you are
picking a commit from one ROM to another or the working directory was updated since the commit was
uploaded to gerrit
Conflicts must be cleared manually.
The simplest conflicts would present as merge tags
This is not the only thing you should look out for however, there may also be
-- Duplicated or deleted lines of code/resources
-- Unnecessary resources
-- Missing resources
Use git diff to see which files conflict and again to see the changes in those files. Of course you have to actually open those files and make your edits/fixes. Once edidted, simply commit the changes to the existing cherry-picked commit
git add <changed files>
git commit (Opens the cherry-pick commit message)
Save ... and you're done