From bf426b0f7d0c868f9ad97778412cd29228542859 Mon Sep 17 00:00:00 2001 From: James Moger Date: Thu, 6 Mar 2014 15:53:20 -0500 Subject: [PATCH] Documentation and clarify git workflows --- src/main/java/com/gitblit/tickets/commands.md | 8 ++-- .../com/gitblit/wicket/pages/TicketPage.java | 14 +++--- .../com/gitblit/wicket/pages/propose_git.md | 2 +- src/site/features.mkd | 26 ++++++----- src/site/tickets_using.mkd | 43 ++++++++++++++++--- 5 files changed, 58 insertions(+), 35 deletions(-) diff --git a/src/main/java/com/gitblit/tickets/commands.md b/src/main/java/com/gitblit/tickets/commands.md index 25c24f4f..44098d28 100644 --- a/src/main/java/com/gitblit/tickets/commands.md +++ b/src/main/java/com/gitblit/tickets/commands.md @@ -1,11 +1,11 @@ #### To review with Git -on a detached HEAD... +To review an updated patchset - git fetch ${repositoryUrl} ${ticketRef} && git checkout FETCH_HEAD + git fetch && git checkout ${reviewBranch} && git pull --ff-only -on a new branch... +To review a rewritten patchset - git fetch ${repositoryUrl} ${ticketRef} && git checkout -B ${reviewBranch} FETCH_HEAD + git fetch && git checkout ${reviewBranch} && git reset --hard origin/${reviewBranch} diff --git a/src/main/java/com/gitblit/wicket/pages/TicketPage.java b/src/main/java/com/gitblit/wicket/pages/TicketPage.java index 5e0e6820..115fba76 100644 --- a/src/main/java/com/gitblit/wicket/pages/TicketPage.java +++ b/src/main/java/com/gitblit/wicket/pages/TicketPage.java @@ -1254,16 +1254,13 @@ public class TicketPage extends TicketBasePage { } protected void addGitReviewInstructions(UserModel user, RepositoryModel repository, MarkupContainer panel) { - String repoUrl = getRepositoryUrl(user, repository); - panel.add(new Label("gitStep1", MessageFormat.format(getString("gb.stepN"), 1))); panel.add(new Label("gitStep2", MessageFormat.format(getString("gb.stepN"), 2))); String ticketBranch = Repository.shortenRefName(PatchsetCommand.getTicketBranch(ticket.number)); - String reviewBranch = PatchsetCommand.getReviewBranch(ticket.number); - String step1 = MessageFormat.format("git fetch {0} {1}", repoUrl, ticketBranch); - String step2 = MessageFormat.format("git checkout -B {0} FETCH_HEAD", reviewBranch); + String step1 = "git fetch"; + String step2 = MessageFormat.format("git checkout {0} && git pull -ff-only\nOR\ngit checkout {0} && git reset --hard origin/{0}", ticketBranch); panel.add(new Label("gitPreStep1", step1)); panel.add(new Label("gitPreStep2", step2)); @@ -1417,7 +1414,6 @@ public class TicketPage extends TicketBasePage { protected Component getMergeInstructions(UserModel user, RepositoryModel repository, String markupId, String infoKey) { Fragment cmd = new Fragment(markupId, "commandlineMergeFragment", this); cmd.add(new Label("instructions", MessageFormat.format(getString(infoKey), ticket.mergeTo))); - String repoUrl = getRepositoryUrl(user, repository); // git instructions cmd.add(new Label("mergeStep1", MessageFormat.format(getString("gb.stepN"), 1))); @@ -1427,9 +1423,9 @@ public class TicketPage extends TicketBasePage { String ticketBranch = Repository.shortenRefName(PatchsetCommand.getTicketBranch(ticket.number)); String reviewBranch = PatchsetCommand.getReviewBranch(ticket.number); - String step1 = MessageFormat.format("git checkout -B {0} {1}", reviewBranch, ticket.mergeTo); - String step2 = MessageFormat.format("git pull {0} {1}", repoUrl, ticketBranch); - String step3 = MessageFormat.format("git checkout {0}\ngit merge {1}\ngit push origin {0}", ticket.mergeTo, reviewBranch); + String step1 = MessageFormat.format("git checkout -b {0} {1}", reviewBranch, ticket.mergeTo); + String step2 = MessageFormat.format("git pull origin {0}", ticketBranch); + String step3 = MessageFormat.format("git checkout {0}\ngit merge {1}\ngit push origin {0}\ngit branch -d {1}", ticket.mergeTo, reviewBranch); cmd.add(new Label("mergePreStep1", step1)); cmd.add(new Label("mergePreStep2", step2)); diff --git a/src/main/java/com/gitblit/wicket/pages/propose_git.md b/src/main/java/com/gitblit/wicket/pages/propose_git.md index 4589bf89..9d956bba 100644 --- a/src/main/java/com/gitblit/wicket/pages/propose_git.md +++ b/src/main/java/com/gitblit/wicket/pages/propose_git.md @@ -2,5 +2,5 @@ cd ${repo} git checkout -b ${reviewBranch} ${integrationBranch} ... - git push --up-stream origin ${reviewBranch} + git push --set-upstream origin ${reviewBranch} diff --git a/src/site/features.mkd b/src/site/features.mkd index 0f4e7f89..314fe393 100644 --- a/src/site/features.mkd +++ b/src/site/features.mkd @@ -1,8 +1,11 @@ ## Standard Features (GO/WAR) - JGit http/https SmartHTTP servlet - JGit git protocol daemon -- Menu driven native platform clone links for all popular Git clients -- Browser and git client authentication +- Optional feature to allow users to create personal repositories +- Optional feature to fork a repository to a personal repository +- Optional feature to create a repository on push +- Optional feature to automatically fetch ref updates for repository mirrors +- Optional Issue Tracker and Pull-Request-like mechanism - Four *per-repository* access restriction configurations with a Read-Only control flag - ![anonymous](blank.png) *Anonymous View, Clone & Push* - ![push](lock_go_16x16.png) *Authenticated Push* @@ -16,19 +19,15 @@ - **RWC** (clone and push with ref creation) - **RWD** (clone and push with ref creation, deletion) - **RW+** (clone and push with ref creation, deletion, rewind) -- Optional feature to allow users to create personal repositories -- Optional feature to fork a repository to a personal repository -- Optional feature to create a repository on push -- Optional feature to automatically fetch ref updates for repository mirrors -- Optional Issue Tracker and Pull-Request-like mechanism +- Menu driven native platform clone links for all popular Git clients - *Experimental* built-in Garbage Collection - Ability to federate with one or more other Gitblit instances - RSS/JSON RPC interface - Java/Swing Gitblit Manager tool -- Gitweb inspired web UI - Responsive web UI that subtracts elements to be usable on phones, tablets, and desktop browsers - Groovy pre- and post- push hook scripts, per-repository or globally for all repositories -- Email push notifications *(via sendmail.groovy push script)* +- Rich Push email notifications *(via sendmail.groovy push script)* +- Rich Ticket email notifications - Lucene indexing of specified repository branches - Administrators may create, edit, rename, or delete repositories through the web UI or RPC interface - Administrators may create, edit, rename, or delete users through the web UI or RPC interface @@ -53,12 +52,11 @@ - Display of Author and Committer email addresses can be disabled - Case-insensitive searching of commit messages, authors, or committers - Dynamic zip downloads feature +- Docs page which enumerates all Markdown files within a repository - Markdown, Confluence, Textile, Twiki, Tracwiki, & Mediawiki markup rendering support - Syntax highlighting for popular source code types - Customizable regular expression substitution for commit messages (i.e. bug or code review link integration) - Single text file for users configuration -- Optional Docs page which enumerates all Markdown files within a repository -2009-01-27)* - Translations - English - Japanese @@ -67,7 +65,7 @@ - Korean - Brazilian Portuguese - Dutch - - Chinese (zh_CN) + - Simplified Chinese (zh_CN) ## Gitblit GO Features - Out-of-the-box integrated stack requiring minimal configuration @@ -78,7 +76,7 @@ - Built-in AJP connector for Apache httpd ## Limitations -- HTTP/HTTPS/GIT are the only supported Git protocols (SSH is in progress) -- Built-in access controls are not path-based, they are repository-based. +- HTTP/HTTPS/GIT are the only supported Git protocols (SSH is in progress, ticket-6) +- Built-in access controls are not branch-based, they are repository-based. [jgit]: http://eclipse.org/jgit "Eclipse JGit Site" diff --git a/src/site/tickets_using.mkd b/src/site/tickets_using.mkd index 228cf925..6541ed8f 100644 --- a/src/site/tickets_using.mkd +++ b/src/site/tickets_using.mkd @@ -22,23 +22,27 @@ Because you are too lazy to create a ticket in the web ui first. The proposal t Any authenticated user who can clone your repository. + git clone https://server/r/repo.git + cd repo git checkout -b mytopic ...add a single commit... git push origin HEAD:refs/for/new - git branch --set-upstream-to={remote}/ticket/{id} + # read ticket id from server output + git branch --set-upstream-to=origin/ticket/{id} ### Creating the first Patchset for an Existing Ticket -If you have an existing ticket that does **not** yet have a proposed patchset you can push using the magic ref. +If you have an existing ticket that does **not** yet have a proposed patchset you can push using the ticket branch ref. *Who can create the first patchset for an existing ticket?* Any authenticated user who can clone your repository. - git checkout -b mytopic + git clone https://server/r/repo.git + cd repo + git checkout -b ticket/{id} ...add one or more commits... - git push origin HEAD:refs/for/{id} - git branch --set-upstream-to={remote}/ticket/{id} + git push --set-upstream origin ticket/{id} ### Safely adding commits to a Patchset for an Existing Ticket @@ -50,7 +54,8 @@ Any authenticated user who can clone your repository. 4. Any user with write (RW) permissions to the repository - git checkout ticket/{id} + git fetch && git checkout ticket/{id} + git pull --ff-only ...add one or more commits... git push @@ -60,10 +65,33 @@ Any authenticated user who can clone your repository. See the above rules for who can add commits to a patchset. You do **not** need rewind (RW+) to the repository to push a non-fast-forward patchset. Gitblit will detect the non-fast-forward update and create a new patchset ref. This preserves the previous patchset. - git checkout ticket/{id} + git fetch && git checkout ticket/{id} + git pull --ff-only ...amend, rebase, squash... git push origin HEAD:refs/for/{id} +OR if you have RW+ permissions, then you can push using *-f* flag. + + git push -f + +### Updating your copy of a rewritten Patchset + +If a patchset has been rewritten you can no longer simply *pull* to update. Let's assume your checkout *does not* have any unshared commits - i.e. it represents the previous patchset. The simplest way to update your branch to the current patchset is to reset it. + + git fetch && git checkout ticket/{id} + git reset --hard origin/ticket/{id} + +If you *do* have unshared commits then you'll could make a new temporary branch and then cherry-pick your changes onto the rewritten patchset. + + git branch oldticket ticket/{id} + git fetch && git checkout ticket/{id} + git reset --hard origin/ticket/{id} + git cherry-pick + git branch -D oldticket + +Since Git is a powerful and flexible tool, there are no doubt several other strategies you could use to resolve this situation. + + ### Ticket RefSpecs Gitblit supports two primary push ref specs: the magic ref and the patchset ref. @@ -130,6 +158,7 @@ There are complicated merge scenarios for which it may be best to merge using yo git checkout master git merge ticket-{id} git push origin master + git branch -d ticket-{id} ### Closing Tickets on Push with a Completely New Patchset -- 2.39.5