Documentation and clarify git workflows

James Moger

2014-03-06 bf426b0f7d0c868f9ad97778412cd29228542859

Documentation and clarify git workflows

 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}



 src/main/java/com/gitblit/wicket/pages/TicketPage.java

@@ -1254,16 +1254,13 @@
    }



    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 @@
    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 @@
        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));


 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}


 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"


 src/site/tickets_using.mkd

@@ -22,23 +22,27 @@

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 @@
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,9 +65,32 @@

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 <commitid1> <commitid2>
    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

@@ -130,6 +158,7 @@
    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