git merge origin/develop
Month: August 2020
Notes
It’s important that you execute a particular kind of merge. I.e., if you run a regular merge, all of your original individual commits will be transformed into one large fast-forward commit. A fast-forward only updates the HEAD pointer; it doesn’t create a commit object.
Note: You can’t just push the new commits into your mainline because the branch names differ. This can happen if another writer spawned and working branch, completed their work, and then merged their new content into your mainline (thus, advancing HEAD by one commit). Alternately, if you currently have another working branch with unfinished work. In both cases, all you have to do is execute git pull before you push, so it’s in synch with your mainline.
To can preserve the history of your revisions, you must specifying command line options:
- Force “no fast forward” (–no-ff),
- Show a difference statistic at the end of the merge (–stat),
- Specify the use of the recursive strategy for the merge (-s recursive),
- Specify that change priority be given to the new content (from in the source branch) (-X theirs),
- Add a comment for the commit (-m).
Example
Merging the new content from /v1.4x_doc_update, into your local feature/api_doc branch.
git merge -s recursive -X theirs v1.43_doc_updates
Note: In Git terminology, the original content belongs to yours, and the new content belongs to theirs.
To avoid aborting an auto-merge when it hits a conflict (in particular, one that results from the insertion of a new item into the middle of a reference table), be sure to use the Recursive Merge Strategy, and use it with the theirs option. Why? Because this particular option forces conflicting content to be auto-resolved cleanly by favoring the new content.
Example
git merge -s recursive -X theirs v1.43_doc_updates
For more information, see: https://www.kernel.org/pub/software/scm/git/docs/git-merge.html.
1. Rebuild the docs
In Eclipse, click Run > Run History > 1 Rebuild HTML Docs.
2. Archive this doc build
Copy this version of the docs
Use this time-saving trick: Double-click the link below and Windows Explorer automatically opens, displaying the directory of the current build. Click anywhere in the contents pane, Select All (Ctrl+A), and copy everything to the Clipboard (Ctrl+C).
C:\Users\Chris\src\python_rest_api\doc\user\v1\build\html
Within this directory, create a new directory to hold this doc snapshot
Give it a name that indicates what made this doc version special. E.g., KeyPress.
Paste
Open the new directory, and paste the content of the Clipboard into it.
3. Make sure the working directory is clean
That is, make sure that you have no unstaged changes. In Eclipse, with the project folder selected in the PyDev Package Explorer, open the Git Staging tab, and click Refresh. If you have unstaged changes, stage them, and then commit them; and then go back and start again (from Step 1. Rebuild the docs).
4. Switch to the feature/api_doc branch
In Eclipse, right-click the project folder in the PyDev Package Explorer tab, and then click Team > Switch to > feature/api_doc.
Or from the git bash
Open a Git BASH, navigate to the current project working folder, and execute the following command:
$ git checkout feature/api_doc
5. Make sure your local branch is in sync (is up to date) with the remote repository
Update your local repository. This is a precautionary measure, in case the remote tracking branch has any commits that you don’t have locally. You didn’t do this once, and it caused you problems (which you easily solved by simply pulling – but it took you a while to figure out what the nature of the problems was).
Note: You must have a VPN connection to 3rdParty.
In Eclipse,
Right-click the project folder in the PyDev Package Explorer tab, and then click Team > Fetch from Upstream.
Or from the git bash
git fetch
6. Create the merge command line
Copy the example git command line below, to a new blank file in EditPad Pro, and revise the <comment/> and <branch_name/>, and then copy the line to the clip board.
git merge --stat --no-ff -m "<comment/>" -s recursive -X theirs <branch_name/>
E.g., (copy & paste from EditPad Pro)
git merge --stat --no-ff -m "Added HTTP status code 429 Too Many Requests" -s recursive -X theirs v1.43_updates
7. Execute the merge
At this point in time, I don’t know how to execute this command in Eclipse.
From the git bash
Click anywhere inside the Git command window, and then dump the contents of the clipboard onto the command line (Trick: right-click).
Note
The merge might have conflicts. If so, then run git mergetool.
Example
git merge --stat --no-ff -m "Added HTTP status code 429 Too Many Requests" -s recursive -X theirs v1.43_updates
8. How to resolve merge conflicts if any
Prerequesite: You’ve registered Beyond Compare 4 as the merge tool in the Git environment.
- Run the merge
From the Git BASH, execute the comnmand: git mergetool, and then press Return. Beyond Compare launches, and displays the original version of the file in the left pane, and the revised version in the right pane. The lines that conflict are highlighted.
- Accept revisions into the original file
In the bottom pane, accept each one in succession, and/or edit the content to your liking.
- When you’re done with that file, click File > Exit
This kicks you back to the Git BASH.
- If there’s another file conflict, just wrince & repeat
Press Return, and step through the conflicts in this file.
Note: At this point, the merge isn’t actually done, despite the fact that you’ve resolved all of the conflicts.
- Conclude the merge
Commit the merge object, and include an informative message.
git commit -m "Merged new content for R1.42 (Verify Registration)."
9. Push the new content upstream
That is, update remote refs along with the associated tree objects from your local feature/api_doc to origin feature/api_doc.
- From the git bash, enter the following command:
git push --tags
- Copy that last line (the one immediately above) so you can use it in the broadcast e-mail.
What to do when there isn’t yet, an upstream branch
You spell it out for Git. I.e., “Create a branch called ‘feature/doc_update’ in the origin repository”.
git push origin feature/doc_update
10. Check the local branch status
Just to make sure the push worked properly.
git status
11. Create a new branch for the next release
You should still have the feature/api_doc checked out, and it should now be up to date with respact to your latest bits. From here, spawn a new branch for your work for the next drop. From the Git BASH, enter the command:
git branch --track -l v1.4x_doc_updates
12. Send the broadcast email
Right after you push your doc updates to the origin repository, send a broadcast e-mail to the team summarizing the changes, asking for (making) a Pull Request, and CC PM (the PM distribution list).
Note: Set the Importance level to High.
In the body of the message, list the doc work items that went into this doc update. You can get this information quite easily in Eclipse. Simply select the Git Reflog tab. The line items of interest are the ones with “commit:” in the Reflog Messages.
E.g.
To: pm@3rdParty.com Importance: High
Subject: Pull Request: REST API Docs v1.51
I pushed a documentation update (To git@git.c11.3rdParty.com:python_rest_api.git 26d53cf..62ed6c1 feature/api_doc -> feature/api_docs ).
This update includes
- TD-41 Fixed a broken link. “State Abbreviation Code” now links to http://pe.usps.com/text/pub28/28apb.htm.
- TD-44 Changed Required to Optional, for the ‘ucid’ request parameter.
- TD-45 Changed the default value for number of verification code digits that 3rdParty automatically generates by default from six, to five.
- TD-48 Corrected two spelling mistakes.
- TD-49 Corrected a spelling mistake.
-
- TD-57 Added two new error codes:
-
- -40008 [Product method] exceeded transaction hard cap; Request denied.
- -60001 PhoneID Contact data not found).
Would you please pull from feature/api_docs, then rebuild the REST API doc set, and then publish it?
If this content update involved TechDoc bugs (Issues), then resolve them as fixed, and then add an appropriate comment
I incorporated this content update in v 1.51 of the REST API docs.
13. Increment the version number
Checkout the new branch. Open the file: doc/user/v1/source/conf.py. Rebuild the docs. Now the current doc build shows the upcoming release number.
14. Put the latest doc set up on Gullinx
Create a new directory. Copy the contents of C:\Users\Chris\src\python_rest_api\doc\user\v1\buildhtml.
New/revised content is always/only considered new/revised in reference to the latest content in the feature/api_doc branch (I like to refer to this branch as my “Mainline” branch). As such, always author your new/revised content in a new branch spawned off of the feature/api_doc branch. The neat thing about this approach is that when you’ve completed and vetted your new content, you can update the docs using git merge (you simply check-out the mainline branch, and then merge-in the working branch).
If, while you worked on the new content (in its working branch), the mainline didn’t change, then the difference between the two branches will be just the commits on the working branch.
- If you merge the new content into feature/api_doc, it produces a Fast Forward. I.e,. feature/api_doc HEAD is advanced by one commit; it is a Merge Commit, and it contains all of the individual commits for incremental updates you made to the content in the working branch.
- you can switch back to mainline, and then pull the new content just by merging the commits from the spawned branch into feature/api_doc. This type of version tracking allows you to do things like undoing a content revision by simply rolling-back the commit.
If the cloned project has no develop branch
git branch -l develop
git checkout develop
git push origin develop
git checkout -b feature/doc_update
git push origin feature/doc_update
git branch --track -l migrate_comments
git checkout migrate_comments
If you’re not already on the feature/api_doc branch, then switch over to it
git checkout feature/api_doc
Check to make sure the working directory is clean (just in case).
git status
Update your local repository
git fetch
or
git fetch origin
You can omit “origin” if your repo is already setup with a default path-spec. To find out, try running “git fetch” and see what happens.
Spawn a new branch off of feature/api_doc
This git command for this, along with its options, is somewhat complicated. Here’s a breakdown of the pieces.
Set the command options
When creating a new branch, mark the start-point branch as upstream from the new branch. Note that track needs two dashes. I noticed that when I pasted the command line into the BASH, one dash was missing!
--track
Note: At this point, I’m not sure if you need to track the starting branch though. Tracking is useful when the spawned-from branch keeps growing due to other people’s commits. In that case, you, along with each of the other contributers should each keep your working directory up to date with respect to the spawned-from branch. Why? Because the assumption is that everyone contributing to the project always contribute to the current state of it. Think of it as a way to simulate the same experience for each contributor as if they were working on the mainline, alone. In your case, there are no other contributers. As such, the spawned-from branch should never change. That is unless you work on more than one content update at a time.
Ok then: You definately do need to use that tracking feature because you sometimes have to have more than on working branches going at the same time. This has already happened, and you didn’t realize that after you’d merged the first woking branch’s content update into mainline, that you then needed to synchronize the second working branch with it (i.e., that you needed to checkout the second working branch, and then execute a “git pull” from it).
-l
Create the branch’s reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as “<branchname>@{yesterday}”.
Issue the command
It’s easiest if you simply copy & paste this command line example into a new document in EditPad Pro; and then modify it accordingly.
Note: I chose not to create and switch to the new branch in one operation using “git checkout -b” – because I wasn’t sure if I could still include the options I needed (–track and -l). I’ll experiment with this and see if it’s possible, and if it is, I’ll recommend that approach.
git branch --track -l v1.4x_updates
Branch v1.4x_updates set up to track local branch feature/api_doc.
Checkout the new branch
And start documenting the new feature.
git checkout v1.4x_updates
Switched to branch ‘v1.4x_updates’
Increment the doc build number
%GITSOURCE%\python_rest_api\doc\user\v1\source\conf.py
Add the new content files to the local repo
Use Stage Changed.
Usually when you run a merge, it results in a fast forward. But sometimes things aren’t so simple.
Here’s a typical scenario where you have to resolve a merge conflict.
First, you perform:
git fetch origin
and then, you perform:
git merge origin/develop
and it results in a merge conflict. Automatic merge failed; fix conflicts and then commit the result.
To Resolve the Conflict
git mergetool
Assuming that you are currently in your working branch.
git fetch origin
git merge origin/develop
When the project is hosted privately on a remote Git server
Important! You must establish a VPN connection to the remote Git server.
- Open a Git bash prompt. You can simply click the shortcut on your Taskbar (or “C:Program Files (x86)Gitbinsh.exe” –login -i).
- Make sure you’re in your GIT_HOME directory (%USERPROFILE%\src), and then execute the following commands.
git clone git@git.c11.3rdParty.com:python_rest_api.git
cd python_rest_api
git pull
git checkout feature/api_doc
When the project is hosted on GitHub
When a project is hosted on GitHub, you can’t push your changes to it. Instead, you have to submit a pull request. But you can only do that if you fork the project, and host your fork up on GitHub. But how can you work on content when you repository isn’t local? The answer is you “Clone in Desktop.” So,
The java 3rd party SDK
-
Using your web browser, navigate to the project site on GitHub (for example, https://github.com/3rdParty/java_3rdParty.git), and click “Fork.”
-
Navigate to your new forked version (https://github.com/%USERNAME%/java_3rdParty/).
-
Clone the new forked version (i.e., make a local working copy of it). To Clone from the Python Bash (the preferred method).
- Launch MINGW32 (click the icon in the Task Bar).
- Execute: git clone https://github.com/%USERNAME%/java_3rdParty.git. Your forked repo on Github automatically becomes the remote for the cloned repo, called “origin”.
OR
To Clone using GitHub for Windows, you must have previously installed GutHub for Windows: http://windows.github.com/
Note
You’ll receive an e-mail message from github.com The following SSH key was added to your account: GitHub for Windows – Production 9d:86:da:ce:4b:e6:c6:d3:c7:47:57:c1:1b:32:f4:c7 If you believe this key was added in error, you can remove the key and disable access at the following location: https://github.com/settings/ssh
You must configure GutHub for Windows to downlad cloned repositories to your %USERPOFILE%/src/ directory. On your new forked repository web page, and click “Clone in Desktop”. Now you have a local, working copy of the project repository.
- cd to the new enlistment directory (e.g., java_3rdParty).
- Add the original source repo (under the 3rdParty GitHub account) as a remote named “upstream”.
git remote add upstream https://github.com/3rdParty/java_3rdParty.git
When you execute this command, nothing appears to happen (but something does).
- Fetch from both origin and upstream. This brings in new branch ‘master’ -> upstream/master.
git fetch --all
- Create a new local branch called develop, and check it out.
git checkout -b develop
Switched to a new branch 'develop'
- Create a new local branch called feature/doc_update, and check it out.
git checkout -b feature/doc_update
Your github enlistment for the Java sdk:
git@github.com:%USERNAME%/java_3rdParty.git
Note from Humnberto
- Chris,
- Please pull the latest version of the master branch into your branch and then repush. Run the following commands from your branch. If you haven’t already, please make sure that your upstream is configured.
https://help.github.com/articles/fork-a-repo
Commands to run after upstream has been configured.
git fetch upstream
git merge upstream/master
The python 3rd party SDK
To clone a local working enlistment
- git clone https://github.com/%USERNAME%/python_3rdParty_sdk.git.
- cd python_3rdParty.
- git remote add upstream https://github.com/3rdParty/python_3rdParty.git.
- git fetch –all. This fetches from both origin and upstream. This brings in new branch ‘master’ -> upstream/master.
- git checkout -b develop. This create a new branch called ‘develop’, based on a snapshot of ‘master’.
- git checkout -b feature/doc_update.
- git push origin feature/doc_update.
Allows you to visualize the project history as a branch map.
git gitk
Allows you to use mouse clicks to perform git commands.
git gui
Categories
How to Use Git for Technical Writing
First you need to learn how to use Git, but then you need to find a way to use Git. I.e., Create a workflow that exploits Git’s strengths. This wasn’t obvious to me at first. Heck, I’d never even considered it until someone suggested I read this: A successful Git Branching Model. I’d been struggling with using Git, and I just figured that was a normal part of the learning curve.
Leverage branching
It turns out that you can do some pretty neat things with Git because of the way Git branching works (which is fundamentally different than what you’re used to). I now see branching in Git as its greatest strength. As a technical writer, I use branching in pretty much that same way that the devs use it. The documentation I write is always released in-step with the products (APIs and SDKs) that the docs cover.
Whenever I start a new doc project, I begin by getting an enlistment to the code base.
-
Open a Git bash session. The Git command prompt automatically positions you in your Git Home directory (e.g., /src).
"C:\Program Files (x86)\Git\bin\sh.exe" --login -i -
Get an enlistment to the project source code repository (i.e., Clone it locally). Here’s an example:
git clone git@git.c11.3rdParty.com:android_mobile_verification.git -
Change directories; move down from the HOME directory to the project directory. Notice that you currently have the Master branch checked out.
cd android_mobile_verification/ -
Switch to the develop branch because that’s where all of the new bits are staged for the dev’s code, and for your new doc content.
git checkout develop -
Fork off of (i.e., create a new branch off of) develop to use as a baseline branch for doc work that your team can then merge in with their latest code bits. My team and I settled on the convention of the branch name feature/api_doc.
git branch --track -l feature/api_doc
Note: the use of the track option to mark the start-point branch as “upstream” from the new branch. The track needs two dashes. The l switch is used to create the branch’s reflog. This activates recording of all changes made to the branch ref. This allows me to create a paper trail (isolate and capture each change in a uniqe commit) for each and every change that I make to the docs.
-
Checkout your new feature/api_doc branch.
git checkout feature/api_doc -
Fork off of (see Fork a repo) feature/api_doc for authoring content for a specific version of the docs (e.g., maybe the devs added a new feature for the next version of the product). I usually give the new branch a name that indicates the product release number that the new content is for, but if I have no idea what that will be, then I choose something that appropriately indicates the state of the docs.
git branch --track -l initial -
Checkout your new working branch.
git checkout initial -
Author new content. I.e., Add, revise, and/or delete content.
-
Merge the content into your baseline branch. As the product evolves, and the devs add new features, this step updates existing content with new content. When I complete the content, and after it’s been reviewd, and I’ve incorporated the revisions, I switch back to the feature/api_doc branch, and then merge the new content into it (i.e., I execute a git merge coming from the branch I was just in). These particular command options ensure that each of the iindividual commit ref log entries from the work I did in the other branch appear in the feature/api_doc as well (otherwise, they appear as just one merge commit).
git merge -s recursive -X theirs initial
-
All that needs to happen now is to make sure that the new content is merged into the devs new code bits. This entails two steps:
- Push the content upstream.
- Send a Pull Request (e-mail) to the Release Management team.
Categories
Using Git with Eclipse
Background
I’m using Eclipse on Windows 10.
The Jgit API
Git functionality is programmatically exposed via the JGit API (Java library). To use Git in Eclipse, you install the plugin called EGit, which makes calls to the JGit library.
- EGit – the EGit plugin is a Team Provider that implements the Git features in Eclipse.
- JGit – the programming API Java library that implements the Git version control file access routines, network protocols, and core version control algorithms. JGit contains Git porcelain commands in the org.eclipse.jgit.api package.
Resources
Goal
To get the curent Git Commit SHA1 from the environment, you are going to have to write code that calls the JGit API.
The HEAD reference is a SHA1 of the current branch.
- HEAD = ref: refs/heads/feature/api_doc
- = C:\Users\Chris\src\python_rest_api.git\refs\heads\feature\api_doc
But it might not be what you want…
Remember that your work in progress resides in your Working Tree, and isn’t yet associated with a changeset.
As you edit your work, it currently resides in RAM. When you save your work, a snapshot of the current RAM image is copied into a file. When you stage your work, the current state of the file is converted into a git Blob, and is added to the Index to create the next changeset. When you commit your work, the Index becomes the current changeset (and is pointed to by the local HEAD ref).
If you want to find out which Change Set any topic in a doc set belongs to (perhaps by using View Source on the topic you’re currently viewing) – then you don’t want to know the Change Set SHA1 of HEAD if you simply built the docs as a matter of course of writing/editing. You’ll want the SHA1 of the commit that corresponds to the final committ, which you won’t get until you’ve completed the writing work.
JGit cookBook
This project has example code that demonstrates how to develop code using JGit.
Grab it
git clone git://github.com/centic9/jgit-cookbook
Build it and create Eclipse project files
mvn dependency:sources eclipse:eclipse package
Run it
Import the project into an Eclipse workspace and execute the snippets there.